All posts
Engineering

MCP servers for codebase context: what to give your coding agent

An MCP server for codebase context lets a coding agent ask questions about your code (where a feature lives, who calls a function, what a change breaks) instead of re-reading files. The Ensemble MCP server answers from a codebase graph plus generated product knowledge. It works with Claude Code, Cursor and any MCP client, over HTTP or stdio.

5 min read

What an MCP server is, in one paragraph

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools and read external resources through one interface. An MCP server exposes those tools; an MCP client, such as Claude Code or Cursor, discovers them and lets the agent call them mid-task. A context server is one kind of MCP server: its tools answer questions about something the agent can't see on its own. For a codebase, that means structure, history and meaning the agent would otherwise piece together from file reads. The spec lives at modelcontextprotocol.io.

What a codebase context server should answer

A useful context server answers the questions an agent would otherwise answer by grepping, and a few it can't answer that way at all.

Five kinds of questions matter:

  1. Structure. Where is this defined? Who references it? What does it call, and what calls it? How do modules depend on each other?
  2. Impact. What does this diff break? Which callers aren't covered by tests? Which invariants does it touch?
  3. Conventions. Where does a new handler, service or job go, and what should it look like here?
  4. Product. What is this feature, who uses it, and which code implements it?
  5. History. How was a comparable ticket solved, and what did it change?

An agent can answer the first two by searching and reading files, as long as the code is checked out. The rest is harder to find that way: calls into a service in another repo, the team's recipe for background jobs, or the fact that billing for teams is admin-only.

A second test for a context server: does it say how much to trust each answer? An answer about the wrong commit, or a name match presented as a resolved reference, is worse than no answer.

The Ensemble MCP tools

The Ensemble MCP server has two groups of tools: compound tools that answer a whole question in one call, and primitives for exact lookups.

Compound tools

Reach for these first.

Tool What it answers
orient What is this codebase, and what matters for my task?
explain What is this symbol, who calls it, which tests cover it, what must stay true?
check_diff What does this change break: blast radius, untested callers, invariants?
trace What happens when this entry point runs?
how_to_add Where does a new service, handler or job go, and what must it look like?
product What does this product do, and what are its features?
feature What is this feature, and which code implements it?
similar_tasks How was a comparable ticket solved, and what did it change?
investigate A question the others can't answer in one call. Slower: it runs an agent loop on the server.

Primitives

For when the agent knows exactly what it wants: find_symbols, find_references, find_callers, find_callees, impact_of_change, file_outline, module_graph, repo_map, module_brief and search_code.

Resources

MCP resources are documents the agent can read, and pin so they stay in context across turns without being fetched again. Ensemble exposes the product overview, each feature, a card describing each repository, the codebase's own glossary, module briefs, execution flows, recipes, saved answers and architecture decision records. For a long task, pinning the repo card saves the agent from re-orienting halfway through.

Prompts worth pasting

You don't need special syntax. Tell the agent to check Ensemble before it writes. These four cover most tasks:

  1. "Use Ensemble to orient on this repo for the task: add a team-plan toggle to billing."
  2. "Ask Ensemble how auth is used before you add the SSO hint."
  3. "Before committing, run check_diff on this diff and tell me the blast radius."
  4. "Ask Ensemble how_to_add a background job, then follow that recipe."

To make it a habit rather than a reminder, add a line to your CLAUDE.md, AGENTS.md or Cursor rules: "Before editing unfamiliar code, ask Ensemble (orient, explain). Before finishing, run check_diff."

What not to paste into the prompt

Keep the prompt about the task. The map of the codebase belongs in the context server.

Three things people paste that they shouldn't:

  • A file tree or a repo tour. It's big, it's out of date by next week, and it pushes the actual request down the context window.
  • An old architecture doc. If it's stale, the agent trusts it anyway.
  • Secrets. API keys and credentials don't belong in prompts, ever. They end up in logs and transcripts.

How much you can trust the answers

Every Ensemble answer says which commit it describes and how precise it is.

  • meta.commitSha names the commit. The index describes committed code, not your working tree. To ask about uncommitted edits, pass a diff to check_diff.
  • meta.precision is precise for a resolved reference from a compiler-grade index, or heuristic for a name match. Treat heuristic results as leads and verify them.
  • Page status. Generated pages end with a status: draft, approved or stale. A stale page is still served, because it's usually mostly right and withholding it would leave the agent with nothing. Check the status before relying on it.

Access uses a workspace key, created in Ensemble's settings. It's scoped to one workspace and can be revoked at any time. The server never reads your disk: every call goes through Ensemble's API. The stdio version can additionally run Semgrep on your working tree if you have it installed, and merges those findings into check_diff.

Setting it up

Setup takes a key and a few lines of config:

Any other MCP client that supports HTTP or stdio servers works the same way.

FAQ

Does this work if I only use the terminal?

Yes. Add the Ensemble MCP server to Claude Code or any terminal MCP client. You never have to open the Ensemble web app.

Will Ensemble write the code for me?

No. Your agent writes the change. Ensemble answers its questions about the codebase and the product.

Does the MCP server read my local disk?

No. Every call goes to Ensemble's API with a workspace key and answers from the indexed commit. The stdio version can also scan your working tree with Semgrep if it's installed locally.

How is this different from my editor's built-in codebase indexing?

Editor indexes usually cover one repo, for one editor. Ensemble's index is shared by the whole team, spans repos, includes call graphs and product knowledge, and works across editors and agents.


Ensemble turns every change into a running copy of your real app, with its services and data, at a private link anyone on the team can open. What is Ensemble?

Stop shipping the hard way

Agents write the code. Ensemble runs it. Everyone clicks it: product people in the browser, agents in parallel, engineers deciding what merges.

Start free