Cursor MCP: set up servers with mcp.json and Customize

To use MCP in Cursor, install a server from the Cursor Marketplace on the Customize page, or add it to mcp.json: .cursor/mcp.json in your project or ~/.cursor/mcp.json for every project. Cursor then lists the server's tools in chat and calls them when they help, asking for your approval by default.

Cursor describes it this way: "Model Context Protocol (MCP) enables Cursor to connect to external tools and data sources." This guide covers file locations, the JSON fields, installs, OAuth and debugging, based on Cursor's MCP documentation read on 24 October 2026.

How does MCP work in Cursor?

An MCP server exposes tools, prompts and resources over the protocol. Cursor supports three transports:

Cursor supports these protocol features: tools, prompts, resources, roots, elicitation (a server asking you for more information) and the MCP Apps extension, which lets a tool return interactive UI. Servers can also return images as base64. Cursor attaches them to the chat, and models that support images analyze them.

Where does Cursor look for mcp.json?

Team admins can also distribute servers through a team marketplace, and those appear in Customize next to your personal and workspace servers. Cursor's extension API offers vscode.cursor.mcp.registerServer() for registering servers from code, without editing mcp.json.

How do you configure a server in mcp.json?

Every server goes under a top-level mcpServers object, keyed by a name you choose.

A local stdio server:

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

A remote server:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

Remote servers do not support envFile. Set the variables in your shell profile or system environment and reference them in headers.

Which variables can you use in mcp.json?

Cursor resolves variables in command, args, env, url and headers:

• ${env:NAME}: an environment variable
• ${userHome}: your home folder
• ${workspaceFolder}: the project root, meaning the folder that contains .cursor/mcp.json
• ${workspaceFolderBasename}: the name of that folder
• ${pathSeparator} and ${/}: the operating system's path separator

Interpolation is the main way to keep tokens out of a committed .cursor/mcp.json. Each teammate sets the variable locally, and the file only holds its name.

How do you install MCP servers in Cursor?

There are four routes:

1. Marketplace, one click. Browse the Cursor Marketplace for official plugins and install them from Customize. Clicking "Add to Cursor" on a Marketplace entry installs the server and runs the OAuth sign-in.
2. Community servers. Cursor's docs point to cursor.directory for community plugins and MCP servers. Read the source before you install, as with any third-party code.
3. Manual. Add an entry to mcp.json as shown above. This works for any server that documents a command or a URL.
4. Install links. Server authors can publish a link that opens Cursor and adds the server. Cursor's install links page gives the format:

cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG

To build one, take the server's JSON config, run it through JSON.stringify, base64 encode the result and put it in config.

For servers worth trying first, such as GitHub, Playwright, Context7 or Sentry, see the best MCP servers.

How do you sign in to remote servers?

For servers that need OAuth, Cursor uses the authorization code flow with PKCE. With dynamic client registration it registers as a public client without a secret, and it renews expired access tokens with the refresh token the server issued.

Some providers, such as Figma and Linear in Cursor's examples, need a fixed client ID or an allow-listed redirect URL. For those, add an auth object to the remote entry:

{
  "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"]
      }
    }
  }
}

CLIENT_ID is required, CLIENT_SECRET only for confidential clients, and if you leave out scopes Cursor discovers them from the server. Register Cursor's fixed redirect URLs with the provider: https://www.cursor.com/agents/mcp/oauth/callback for web and Cursor Agents, and http://localhost:8787/callback for the desktop app.

Cloud Agents keep their own MCP sign-ins on Cursor's servers. Signing out on your machine does not sign them out; do that from the server's Cloud row in Customize.

How do you use and control MCP tools?

Cursor uses tools listed under Available Tools when they are relevant, including in Plan Mode. You can also name a tool or describe what you need.

• Approval. Cursor asks before running an MCP tool by default. Click the arrow next to the tool name to see the arguments first.
• Run modes. MCP follows the same run modes as terminal commands. In Auto-review mode, allowlisted MCP tools run at once and everything else goes through the classifier.
• On and off. Toggle a server in Customize. Disabled servers do not load or appear in chat.
• Failures. If a server crashes or times out, Cursor marks that tool call as failed and keeps the other servers running.

Does the Cursor CLI use the same MCP servers?

Yes. The Cursor CLI docs say the CLI uses the same configuration as the editor. Its commands:

agent mcp list                    # servers with status, source and transport
agent mcp list-tools <identifier> # tools, descriptions and parameters
agent mcp login <identifier>      # sign in to a server from mcp.json
agent mcp enable <identifier>     # approve a server locally
agent mcp disable <identifier>    # stop a server from loading

In interactive mode, /mcp list opens the same interface as agent mcp list. The --approve-mcps flag auto-approves all MCP servers and skips their approval prompts.

How do you debug a Cursor MCP server?

1. Open the Output panel in Cursor (Cmd+Shift+U).
2. Select "MCP Logs" from the dropdown.
3. Look for connection errors, authentication problems or crashes. The logs show startup, tool calls and errors.

To update an npm-based server, Cursor suggests removing it from Customize, running npm cache clean --force, then adding it again. For a custom server, update your files and restart Cursor.

On security, Cursor's advice is to install servers only from trusted developers, review what data and APIs a server can reach, use API keys with minimal permissions, and keep secrets in environment variables.

MCP servers, rules and skills in Cursor

MCP gives Cursor's agent new tools. Cursor rules give it standing instructions, and Cursor skills give it step-by-step procedures it loads only when a task calls for them. A skill is often the best place to explain how to use a server for one job, such as "check Sentry, reproduce the bug, write a failing test."

Skills use the open SKILL.md format, so the same folder works in Cursor, Claude Code and Codex. Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own, with every skill installable into Claude Code or Codex using npx skills add https://github.com/<you>/<repo>.git --all -g. The free SKILL.md generator turns a prompt you already use into a skill folder.