How to add codebase context to Cursor with an MCP server
To add codebase context to Cursor, register an MCP server in .cursor/mcp.json (per project) or ~/.cursor/mcp.json (global). For Ensemble, add a server named ensemble with the URL https://api.ensemble.dev/mcp and your workspace key as a Bearer header. Cursor's agent can then ask where features live and what a change breaks.
How to add Ensemble to Cursor
Setup is a key and a few lines of JSON.
1. Create a workspace key
In Ensemble, go to Settings → API keys and create a key. It's scoped to one workspace and can be revoked at any time.
2. Add the server to mcp.json
Create or edit ~/.cursor/mcp.json (every project) or .cursor/mcp.json in the project root (one project):
{
"mcpServers": {
"ensemble": {
"url": "https://api.ensemble.dev/mcp",
"headers": { "Authorization": "Bearer ens_..." }
}
}
}
Because the file contains your key, prefer the global file, or keep the project file out of version control.
3. Check it's enabled
Open Cursor Settings → MCP. The ensemble server should show as enabled, with its tools listed.
4. Ask the agent to use it
In the agent chat:
Use Ensemble to orient on this repo for the task: add a team-plan toggle to the billing page.
Alternative: stdio
To run the server locally instead, use the stdio package:
{
"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"
}
}
}
}
If Semgrep is installed locally, the stdio version also scans your working tree when you call check_diff.
What stays in Cursor, and what moves to Ensemble
Cursor stays your editor and agent. Ensemble becomes the thing it asks about the codebase.
| Stays in Cursor | Moves to Ensemble |
|---|---|
| Editing, diffs and tab completion | "Where does this feature live?" |
| Your model and your settings | "Which pattern does this codebase use for this?" |
| Keybindings, extensions, workflow | "What does this change break?" |
| Chat and agent sessions | "What is this feature for, and who uses it?" |
Nothing about how you use Cursor changes. The agent simply has better answers available when it needs them.
How this differs from Cursor's codebase indexing
Cursor's built-in indexing helps its agent find relevant code. Ensemble adds structure, product knowledge and a shared index for the whole team.
They do different jobs, and they work well together:
- Structure, not just similarity. Ensemble answers with call graphs and references: who calls this function, which tests cover it, what a diff affects (
check_diff). - Conventions as recipes.
how_to_addreturns how this codebase builds a new handler, service or job, so new code follows the existing pattern. - Product knowledge.
productandfeatureanswer what features exist and which code implements them. - Shared across tools. The same answers are available to teammates using Claude Code or other MCP clients, so everyone's agent works from the same picture.
Prompts to try
- "Use Ensemble to orient on this repo for the task: add a team-plan toggle to billing."
- "Ask Ensemble how auth is used before you add the SSO hint."
- "Before committing, run check_diff on this diff and tell me the blast radius."
- "Ask Ensemble how_to_add a background job, then follow that recipe."
To make it automatic, add a Cursor rule: "Before editing unfamiliar code, ask Ensemble (orient, explain). Before finishing, run check_diff."
For every tool and resource, see MCP servers for codebase context.
What about people who don't use Cursor?
PMs and designers can't open your local dev server. When they need to see your branch, Ensemble gives it a running preview at its own URL, with seeded data, behind a login. You send a link instead of screen-sharing. The same goes for you: if agents are working on several branches at once, each branch gets its own running copy instead of sharing your localhost. See how to review a pull request without running it locally.
FAQ
Where is Cursor's MCP config file?
.cursor/mcp.json in the project root for one project, or ~/.cursor/mcp.json for every project.
Does Ensemble have its own IDE?
No. Ensemble Studio is a browser workspace for people who don't use an IDE. Developers stay in Cursor.
Does the context update when I commit?
Ensemble re-indexes when a protected branch changes. For uncommitted edits, pass the diff to check_diff.
Does Ensemble replace Cursor's model?
No. Cursor keeps whatever model you use. Ensemble supplies context through MCP.
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?