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
- How to allow Cursor to run all commands: Run Everything, allowlist and sandbox
- Cursor Privacy Mode: telemetry, training and data retention
- Keep files out of Cursor with .cursorignore
- Cursor CLI: install, headless mode, permissions and CI
- Cursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codes
- Cursor sandbox: sandbox.json, network allowlist and run modes
- Cursor settings: settings.json, Cursor Settings and the ~/.cursor config files
- Cursor browser agent: @browser, browser automation and approval modes
- Cursor subagents: .cursor/agents, frontmatter, built-in Explore and Browser
- Cursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API)
- Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.md
- Cursor skills and custom slash commands: .cursor/skills SKILL.md, .cursor/commands and /migrate-to-skills
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 →