Skip to content
AgentAtlas

Add MCP servers to Cursor with mcp.json

How do I add an MCP server to Cursor?

Install a server in one click from Customize in the sidebar, or define it under "mcpServers" in .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects). Local servers use a command, and remote servers use a url plus optional headers or OAuth settings. You can toggle servers on or off from Customize, and Cursor asks for approval before running MCP tools by default.

Compare: add an MCP server in every AI coding agent →

Where mcp.json lives

  • Project: .cursor/mcp.json in your project folder, for project-specific tools. You can commit it to git so teammates get the same tools.
  • Global: ~/.cursor/mcp.json in your home directory, for tools available in every project.
  • Both files are merged. If the same server name appears in both, the project-level config takes priority.
  • For one-click installs, open Customize in the sidebar, click MCPs, and choose Add to Cursor. Follow any authentication prompts.
  • Save the file and restart Cursor after editing it by hand.

Local (stdio) and remote (url) servers

Cursor supports three transports: stdio (a local shell command that Cursor manages), SSE, and Streamable HTTP. A stdio server takes a command (required), plus optional args, env, and envFile. The command must be on your system path or be a full path.

.cursor/mcp.json (local stdio server)

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

A remote server uses url instead of command. Add headers if the server needs them. The envFile option only works for stdio servers, not for remote HTTP or SSE servers.

.cursor/mcp.json (remote server)

{
  "mcpServers": {
    "my-service": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Environment variables and OAuth

Cursor resolves variables in the command, args, env, url, and headers fields (and in auth values). Supported syntax: ${env:NAME} for environment variables, ${userHome} for your home folder, ${workspaceFolder} for the project root (the folder containing .cursor/mcp.json), ${workspaceFolderBasename} for the project root name, and ${pathSeparator} or ${/} for the OS path separator.

Interpolation example

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    },
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

Cursor supports OAuth for remote servers. If a provider gives you a fixed client ID, requires a whitelisted redirect URL, or does not support Dynamic Client Registration, add an auth object with CLIENT_ID (required), CLIENT_SECRET (optional), and scopes (optional). If scopes is omitted, Cursor discovers scopes_supported from /.well-known/oauth-authorization-server.

Remote server with static OAuth

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "scopes": ["read", "write"]
      }
    }
  }
}
  • Register https://www.cursor.com/agents/mcp/oauth/callback as a redirect URI for web and Cursor Agents.
  • Register http://localhost:8787/callback as a redirect URI for the desktop app.
  • The server is identified through the OAuth state parameter, so the same redirect URLs work for every MCP server.

Enable, disable, approve, and debug tools

  • Toggle a server on or off without removing it: open Customize in the sidebar, then MCPs, and use the toggle. Disabled servers do not load or appear in chat.
  • Toggle individual tools by clicking the tool name in the tools list at the top of the chat panel.
  • Agent uses MCP tools listed under Available Tools automatically when relevant, including in Plan Mode. You can also ask for a tool by name.
  • By default Cursor asks for approval before running an MCP tool. MCP follows the same Run Modes as terminal commands: in Auto-review mode, allowlisted MCP tools run immediately and the rest go through a classifier.
  • To debug, open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows and Linux) and select MCP Logs.
  • If a server crashes or times out, the tool call is marked as failed and other MCP servers keep working.

MCP in the Cursor CLI: agent mcp commands

The Cursor CLI uses the same MCP configuration as the editor, so a server in mcp.json works in both. The CLI looks for config in the project, then global, then nested locations, and also searches parent directories.

  • agent mcp list: interactive view of each server's name, connection status, config source (project or global) and transport (stdio, HTTP or SSE). /mcp list shows the same view inside a session.
  • agent mcp list-tools <identifier>: the server's tools with descriptions, parameters, types and constraints.
  • agent mcp login <identifier>: authenticate with a server defined in mcp.json. The agent can use it once login completes.
  • agent mcp enable <identifier> adds the server to the local approved list; agent mcp disable <identifier> stops it from loading or asking for approval.
  • --approve-mcps skips the approval prompts for all MCP servers. Server names with spaces work in these commands.

shell

agent mcp list
agent mcp list-tools github
agent -p --approve-mcps "list my open GitHub issues"

Sources

More Cursor guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →