Cursor MCP Setup: mcp.json, OAuth & Fixes

Cursor MCP setup comes down to one file: mcp.json. Put your servers in ~/.cursor/mcp.json for every project, or .cursor/mcp.json in a repo for just that project, then check Settings → Cursor Settings → MCP for a green dot. That's the whole mechanism — the rest of this post is the exact JSON for local and remote servers, how OAuth servers authenticate, and how to fix the two failures everyone hits: a server stuck yellow, and a server that connects but shows no tools.

Every config below is minimal and correct, and every server is real and linked. If you want to skip the JSON entirely, the config generator writes it for you.

Where Cursor reads MCP config (global vs project)

Cursor reads MCP servers from two places, and project config wins when both exist. Global config lives at ~/.cursor/mcp.json and applies to every workspace; project config lives at .cursor/mcp.json in the repo root and applies only there. Use global for servers you always want (docs, GitHub); use project for anything with repo-specific secrets or scope.

Both files use the same mcpServers object. The safe default is: put personal, cross-project tools in global, and check the per-project file into git only if it contains no secrets. A .cursor/mcp.json full of API keys does not belong in a shared repo.

Where	Path	Scope	Use for
Global	~/.cursor/mcp.json	All workspaces	Docs, GitHub, your standard stack
Project	.cursor/mcp.json	That repo only	Repo-scoped secrets, one-off servers

The exact mcp.json for a local (stdio) server

Most servers you add are local processes Cursor launches over stdio — roughly 90% of MCP servers run this way, and it's the lowest-latency, most private option. You give Cursor a command, its args, and any env it needs. Here's the official Filesystem reference server, scoped to a single directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

The trailing path is the allowed directory — the server refuses reads and writes outside it, which is the point. For a Docker-based server like the official GitHub MCP Server, the shape is the same but the command is docker:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
               "ghcr.io/github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

Scope that token to the minimum — read-only if you only read issues. Save the file and Cursor reloads servers automatically; you shouldn't need to restart. Full walkthrough in how to add an MCP server.

Remote servers: URL config and OAuth

Remote servers are the exception, and Cursor connects to them by URL over HTTP/SSE instead of launching a process. There's nothing to install — you add a url and Cursor handles the connection. A remote docs server like Context7, which injects version-specific library docs so the model stops inventing APIs, looks like this:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

OAuth servers need one extra step, not extra JSON. When a remote server requires auth, you still add only the url — Cursor detects the OAuth challenge, pops a browser window to sign in, and stores the token itself. You never paste a secret into mcp.json. After you approve, the MCP panel shows a Login or Authenticate button next to the server; click it if the browser didn't open on its own. The GitHub server also offers a hosted remote endpoint if you'd rather not run Docker — same URL-based config, same OAuth flow. For how that handshake works under the hood, see MCP OAuth explained.

Fix: server connects but shows "no tools" (or won't turn green)

The two failures are different problems with different fixes. Diagnose by the color and the tool count in Settings → MCP before you touch anything.

Yellow / red dot, never connects. The process is failing to start. Ninety percent of the time it's the command: npx or docker isn't on the PATH Cursor inherited, or a required env var is missing. Run the exact command plus args from your mcp.json in a terminal — if it errors there, it errors in Cursor. For Docker servers, make sure Docker Desktop is actually running.

Green dot, but "0 tools enabled" or an empty tool list. The server connected fine; the tools just aren't switched on. Open the server's row in the MCP settings and toggle the tools on — Cursor ships them disabled for some servers by default. If the list is genuinely empty, the server started but crashed during initialization: check its logs (many print to stderr, which Cursor surfaces in the MCP panel).

One more cause of "the model ignores my tools": you've blown the tool budget. Cursor's tool selection degrades past roughly 40 active tools, and the average server ships about 12, so around four servers is the practical ceiling. Past it, the model picks the wrong tool or none — which reads like a bug but is a config problem. The Cursor tool-limit math has the full breakdown. More setup failures and their fixes live in troubleshooting.

A sane starter config

Start with two or three servers, not ten. A good default global mcp.json is Context7 for live docs, the GitHub server if you touch repos, and Filesystem scoped to your projects directory — three servers, comfortably under the tool ceiling, each doing one job. Add a fourth only when you hit a real gap, and remove one before you add the next. When you're ready to expand, the best MCP servers list ranks options by category so you're not adding tools blind.