Add MCP servers to Cursor with mcp.json

• 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.

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.

{
  "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.

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

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.

{
  "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.

{
  "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.

• 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.