All posts
Comparisons

How to add codebase context to Claude Code with an MCP server

To give Claude Code codebase context, add an MCP server that answers questions about your code. For Ensemble, create a workspace key in Settings → API keys, then run claude mcp add --transport http ensemble https://api.ensemble.dev/mcp --header "Authorization: Bearer ens_...". Claude Code can then call tools like orient, explain and check_diff alongside its own search.

4 min read

Why Claude Code needs codebase context

Claude Code is very good at editing code, and it starts every session knowing nothing about yours.

At the start of a task, Claude Code explores: it searches, lists directories and reads files until it understands enough to act. On a small repo that's quick. On a large one, it costs tokens and time every session, and what it learns depends on what it happened to search for. That's how you end up with a second session helper next to the one that already existed. Why coding agents re-read the repo goes deeper.

An MCP server gives Claude Code another option: it can ask. Ensemble's index covers where things are, how they connect across services and repos, and what each feature does.

How to add Ensemble to Claude Code

Setup takes two minutes: a key, one command, and a check.

1. Create a workspace key

In Ensemble, go to Settings → API keys and create a key. It's scoped to one workspace, and you can revoke it there at any time.

2. Add the server

Run this in your project directory:

claude mcp add --transport http ensemble https://api.ensemble.dev/mcp \
  --header "Authorization: Bearer ens_..."

To share the configuration with your team, add --scope project. Claude Code writes it to .mcp.json in the repo root. Don't commit the key itself: reference an environment variable instead, so the file looks like this:

{
  "mcpServers": {
    "ensemble": {
      "type": "http",
      "url": "https://api.ensemble.dev/mcp",
      "headers": { "Authorization": "Bearer ${ENSEMBLE_API_KEY}" }
    }
  }
}

3. Check it's connected

Start Claude Code and run /mcp. You should see ensemble listed as connected, with its tools.

4. Ask it to orient

Give Claude Code a task and tell it to start with Ensemble:

Use Ensemble to orient on this repo for the task: add an SSO hint to the login page.

Alternative: stdio

If you'd rather run the server locally, use the stdio package. It runs the same server in-process:

{
  "mcpServers": {
    "ensemble": {
      "command": "npx",
      "args": ["-y", "@ensemble/mcp"],
      "env": {
        "ENSEMBLE_API_URL": "https://api.ensemble.dev",
        "ENSEMBLE_API_KEY": "ens_...",
        "ENSEMBLE_WORKSPACE_ID": "<uuid>",
        "ENSEMBLE_REPO": "org/repo"
      }
    }
  }
}

The stdio version has one extra: if Semgrep is installed locally, check_diff also scans your working tree and merges those findings in.

What a session looks like

With Ensemble connected, Claude Code asks before it edits, and checks before it commits. Here's the shape of a typical session (illustrative, not a recorded customer session):

  1. Task: "Add an SSO hint to the login page for workspaces that have SSO enabled."
  2. orient: Ensemble returns the auth module, the login page component, the convention for feature checks, and a pitfall: session handling goes through a shared helper.
  3. explain on the auth middleware: who calls it, which tests cover it, and the invariant that unauthenticated requests never reach workspace routes.
  4. The edit: Claude Code adds the hint using the existing helper and feature-check pattern.
  5. check_diff: Ensemble reports two callers of a changed function that have no test coverage.
  6. Follow-up: Claude Code adds tests for both before finishing.

Without the index, steps 2 and 3 take a round of searches and file reads, and the untested callers in step 5 are easy to miss.

The tools Claude Code will use most

Most sessions use four tools:

Tool When Claude Code calls it
orient At the start of a task, to find what matters
explain Before changing a symbol it didn't write
how_to_add When adding a new handler, service or job
check_diff Before committing, to see the blast radius

The full list, including product and feature tools, is in MCP servers for codebase context.

Tips for better results

Tell Claude Code when to use Ensemble, and pin the context it needs for long tasks.

  • Add a line to CLAUDE.md: "Before editing unfamiliar code, ask Ensemble (orient, explain). Before committing, run check_diff." Claude Code reads it every session.
  • Pin the repo card for long tasks. The ensemble://<repo>/card resource describes the codebase and stays in context across turns without being fetched again.
  • Treat heuristic results as leads. Every answer carries a precision flag. precise is a resolved reference; heuristic is a name match to verify.
  • Remember what the index sees. Answers describe committed code, named by commit. For uncommitted edits, pass the diff to check_diff.

What Ensemble isn't

Ensemble doesn't replace Claude Code. Claude Code still writes the code; Ensemble answers its questions about the codebase and runs what it writes. And a developer who only ever uses Ensemble through Claude Code is a full Ensemble user. You never need to open the web app.

Every branch also gets its own running copy of your app, with its services and seed data, at a private link. If you run several Claude Code sessions on different branches, each has its own copy instead of sharing one localhost, and your PM or designer opens the link instead of asking you to pull the branch. See what is a preview environment.

FAQ

Does Claude Code support remote MCP servers?

Yes. Claude Code supports HTTP MCP servers with claude mcp add --transport http, as well as local stdio servers.

Do I need to open the Ensemble web app?

No. Developers who only use Claude Code with the MCP server are full Ensemble users. The web app is for people who don't work in a terminal.

Where does my API key go?

In the Authorization header of the MCP config, ideally from an environment variable. Keys are scoped to one workspace and can be revoked in settings.

Can Claude Code deploy a preview through Ensemble?

Not from the MCP server yet. Push your branch, and the preview is available to reviewers through Ensemble.


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