Cursor mcp.json Setup: Project and Global MCP Config Explained (2026)

Cursor reads MCP servers from two JSON files. A project file at .cursor/mcp.json in your repository holds servers for that project. A global file at ~/.cursor/mcp.json in your home folder holds servers you want in every project. Both use the same mcpServers format as Claude Desktop.

Add a server to one of those files, save, and manage it from Customize in Cursor's sidebar, where a toggle turns each server on or off. This guide shows minimal working configs, the variable syntax, OAuth setup and where to look when a server fails.

Checked against: Cursor's MCP documentation on 2 November 2026. eSEOspace did not test Cursor for this guide.

Where the files live

On Windows, ~ is your user folder, such as C:\Users\you\.cursor\mcp.json. Cursor's docs give the paths only in the ~/.cursor form.

If you commit .cursor/mcp.json, every teammate gets the same servers. Never commit real keys in it. Use variables instead (see below).

Minimal configs

Local (stdio) server

Cursor's docs show this shape for a server that runs as a local command:

{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

The docs note that command must be on your system path or given as a full path.

Remote server

For a server reached over HTTP, give the URL and any headers:

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Cursor lists three transports: stdio, SSE and Streamable HTTP. Both blocks were checked against Cursor's docs on 2 November 2026. Our stdio vs Streamable HTTP comparison explains when to use each.

You can also generate either block with the free MCP config generator.

Keep secrets out of the file

Cursor resolves variables in command, args, env, url and headers. Its docs list:

For example, "args": ["${workspaceFolder}/tools/mcp_server.py"] points at a script inside the repo on any machine. A header such as "Authorization": "Bearer ${env:MY_TOKEN}" reads the token from your shell.

For stdio servers, you can also set envFile to a path such as "${workspaceFolder}/.env". Cursor's docs say remote servers do not support envFile, so use ${env:...} interpolation for them.

OAuth for remote servers

When a remote server needs sign-in, Cursor uses the OAuth authorization code flow with PKCE. It finds the authorization server through the server's protected resource metadata. If the server supports dynamic registration, Cursor registers itself as a public client with no secret.

For servers that need a pre-registered app, add an auth object with CLIENT_ID, an optional CLIENT_SECRET and optional scopes. Register these redirect URLs with the provider, per Cursor's docs:

• https://www.cursor.com/agents/mcp/oauth/callback for the web and Cloud Agents
• http://localhost:8787/callback for the desktop app

Our MCP OAuth misconfiguration guide lists the mistakes that break this flow.

Verify and manage servers

1. Save mcp.json.
2. Open Customize in the sidebar and find your server. Use its toggle to enable it; Cursor's docs say disabled servers do not load.
3. In Agent chat, ask for something that needs the server's tool.
4. Cursor asks for approval before running the tool. Click the arrow beside the tool name to see its arguments before you approve.

Cursor's docs say MCP tools follow the same Run Modes as terminal commands. In Auto-review mode, allowlisted tools run at once and others go to a classifier.

Read the MCP logs

Open the Output panel with Cmd+Shift+U (Ctrl+Shift+U on Windows and Linux) and pick MCP Logs from the dropdown. Cursor says the logs show initialization, tool calls and errors. Most failures show up there as a command that could not start or a 401 from a remote server.

Common mistakes

• Wrong folder name. It is .cursor/mcp.json, with a leading dot on the folder.
• Real keys in a committed file. Use ${env:NAME} or a gitignored envFile.
• envFile on a remote server. It is ignored; use interpolation.
• A command Cursor cannot find. Use a full path if npx or uvx works in your terminal but not in Cursor.
• Too many servers. Every enabled server adds tool descriptions to the model's context. Turn off the ones a project does not need.

Next step

With the file in place, connect real tools. Our Cursor guides cover connecting Cursor to Linear and connecting Cursor to Supabase, and the best MCP servers for Cursor list helps you choose. If tools still do not appear, see MCP tools not showing in Cursor.

Frequently asked questions