Connect an MCP server to Cursor
Cursor reads MCP servers from a JSON file — one per project, or one for everything. You can also click through Settings → MCP → Add new MCP server; it writes to the same file.
Where the config lives
| Path | Scope | Good for |
|---|---|---|
| .cursor/mcp.json | This project | Repo-specific tools; commit it to share with the team |
| ~/.cursor/mcp.json | Every project | Docs search, personal utilities |
Remote (hosted) server
Vendor-run servers need only a URL — Cursor handles the sign-in flow:
{
"mcpServers": {
"linear": {
"url": "https://mcp.linear.app/mcp"
}
}
}Ready to paste right now: fal.ai, Atlassian, Datadog, Buffer, Google Drive — each page has the exact URL.
Local (stdio) server
Local servers are launched by Cursor as a subprocess:
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "@vendor/mcp-server"],
"env": { "VENDOR_API_KEY": "sk-…" }
}
}
}Python servers use uvx as the command. Package names, arguments and required
environment variables come from each server's README, which is linked from its verdict page
here.
Using it
Enable the server in Settings → MCP — a green dot means it connected and its tools were listed. Then just describe what you want in the agent panel; Cursor picks tools on its own, or you can name the server directly. Tool calls ask for approval unless you turn on auto-run, which is worth leaving off for anything that writes.
When the dot stays red
| Symptom | Usual cause | Fix |
|---|---|---|
| Red dot, no tools | Command not found | Use an absolute path from which npx — Cursor's PATH isn't your shell's |
| Connects, then drops | Server exits on startup | Run the command manually; a missing API key is the usual culprit |
| Config ignored | Wrong filename or location | It's .cursor/mcp.json at the project root, not .cursor/mcp.jsonc |
| Agent never uses the tool | Too many servers enabled | Disable unused servers, or name the tool explicitly in your prompt |
Questions
Project config or global config?
Use .cursor/mcp.json inside a repo when the server is specific to that codebase — it can be committed so teammates get it too. Use ~/.cursor/mcp.json for servers you want everywhere, like docs search.
Why is the dot next to my server red?
Cursor couldn't start the process or reach the URL. For local servers, run the exact command from your config in a terminal — you'll see the real error immediately, usually a missing binary on PATH or an unset API key.
Can I keep API keys out of the config file?
Reference environment variables in the env block rather than pasting secrets, and keep .cursor/mcp.json out of version control if it contains anything sensitive. A leaked MCP config is a leaked credential.
How many servers can I add?
Technically many, but every server's tools are injected into the model's context, so a dozen chatty servers crowd out the room for your actual code. Enable what a project needs and disable the rest.