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.

Check the server exists first. 212 of 234 brands ship an official one.

Where the config lives

PathScopeGood for
.cursor/mcp.jsonThis projectRepo-specific tools; commit it to share with the team
~/.cursor/mcp.jsonEvery projectDocs search, personal utilities

Remote (hosted) server

Vendor-run servers need only a URL — Cursor handles the sign-in flow:

.cursor/mcp.json
{
  "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:

.cursor/mcp.json
{
  "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

SymptomUsual causeFix
Red dot, no toolsCommand not foundUse an absolute path from which npx — Cursor's PATH isn't your shell's
Connects, then dropsServer exits on startupRun the command manually; a missing API key is the usual culprit
Config ignoredWrong filename or locationIt's .cursor/mcp.json at the project root, not .cursor/mcp.jsonc
Agent never uses the toolToo many servers enabledDisable 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.