Cursor MCP Setup: Add and Configure MCP Servers in Cursor

How to Add an MCP Server in Cursor

To add an MCP server in Cursor, put it in an mcp.json file: ~/.cursor/mcp.json makes it available in every project, and .cursor/mcp.json in your repo makes it project-only. Local servers use command and args (stdio); remote servers use url (Streamable HTTP or SSE). You can also install servers with one click from the Cursor Marketplace or an install link, then turn them on and off from Customize in the sidebar.

Everything below is checked against the official Cursor MCP documentation. If you still need a server to connect, browse the MCP server directory first.

Quick Reference

Step 1: Pick Global or Project Scope

Cursor reads MCP servers from two places:

• ~/.cursor/mcp.json in your home directory, for tools you want everywhere (a docs server, a browser, a memory server).
• .cursor/mcp.json in your project, for tools that belong to that codebase (its database, its issue tracker). Commit this file so teammates get the same servers, but never commit secrets in it (see Step 3).

Both files use the same format: a top-level mcpServers object where each key is the server name you'll see in Cursor.

Step 2: Add a Server

Cursor supports three transports. Per the docs, stdio servers are launched and managed by Cursor itself, while SSE and Streamable HTTP servers are reached by URL and can authenticate with OAuth.

Local stdio server

A stdio server is a program Cursor starts on your machine. Here is the Playwright MCP server, which gives the agent a real browser:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The same shape works for Python servers: set command to python (or uvx) and put the script or package in args. Fields available for stdio are type ("stdio"), command (required), args, env and envFile.

Remote server (Streamable HTTP or SSE)

A remote server only needs a URL. Cursor picks up both Streamable HTTP and the older SSE transport:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CONTEXT7_API_KEY}"
      }
    }
  }
}

That's the Context7 MCP server, which feeds up-to-date library docs to the agent. Many hosted servers (for example Notion, Linear or Sentry) use OAuth instead of a header: add just the url, and Cursor opens a browser sign-in the first time the server connects. For background on the two transports, see SSE vs Streamable HTTP.

Mixing several servers

Each server is just another key in mcpServers, so one file can hold local and remote entries side by side. Restarting is not usually needed; if a server doesn't appear, toggle it off and on in Customize.

Step 3: Keep Secrets Out of mcp.json

Hardcoding an API key in a committed .cursor/mcp.json is the most common mistake. Cursor has two built-in ways around it.

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

For example, a GitHub token passed to the GitHub MCP server as a bearer header:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_PAT}"
      }
    }
  }
}

envFile (stdio only). Point a local server at a dotenv file instead of listing variables one by one:

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Keep that .env in .gitignore. Note that envFile is only supported for stdio servers; remote servers should use ${env:...} in headers.

Static OAuth clients

If a remote server needs a pre-registered OAuth app rather than dynamic registration, add an auth object with CLIENT_ID (required), CLIENT_SECRET (optional) and scopes (optional; Cursor discovers them from the server's OAuth metadata when omitted). Register http://localhost:8787/callback as the redirect URL for the desktop app. More on how the flow works in our MCP authentication guide.

Step 4: One-Click Install Links

There are two one-click paths:

1. Cursor Marketplace. Open Customize and browse the marketplace, or click Add to Cursor on a marketplace entry. It installs the server and runs the OAuth sign-in.
2. Install links. Anyone can publish a deeplink in this format (docs):

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

config is the base64 of the server object alone (for example {"command":"npx","args":["-y","@playwright/mcp@latest"]}), not the whole mcpServers wrapper; the name goes in name. You can build one in a terminal:

echo -n '{"command":"npx","args":["-y","@playwright/mcp@latest"]}' | base64

Clicking the link makes Cursor show an install prompt. Treat install links like any other code you run: decode the config and read the command before you accept.

Step 5: Use, Approve and Limit Tools

Once a server is enabled, the agent sees its tools and decides when to call them. By default Cursor asks for approval before each MCP tool call; click the arrow next to the tool name to see the exact arguments. In auto-review run mode, allowlisted tools run immediately while other calls go through Cursor's classifier.

Cursor supports more than tools: prompts, resources, roots, elicitation and the MCP Apps extension (interactive UI returned by a tool) are all listed as supported.

What about the 40-tool limit? Older Cursor versions sent only the first 40 MCP tools to the model and showed a warning above that. Since January 2026 Cursor uses dynamic context discovery: tool descriptions are synced to files and the agent starts with only the tool names, loading full schemas when it needs them. Cursor reported about 46.9% fewer total agent tokens in runs that called an MCP tool. Even so, fewer servers means fewer wrong tool choices, so disable servers you're not using in Customize. If tool selection is a problem, our guide to MCP tool discovery covers the patterns.

Step 6: The Same Servers in the Cursor CLI

The Cursor CLI (agent) uses the same mcp.json configuration as the editor (CLI MCP docs):

agent mcp list                  # configured servers and their status
agent mcp list-tools playwright # a server's tools and parameters
agent mcp login notion          # authenticate a server from mcp.json
agent mcp disable playwright    # stop loading a server

Troubleshooting Cursor MCP

Start with the logs: open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux) and pick MCP Logs from the dropdown. A failing server shows an error in chat and marks the tool call as failed, but other servers keep running.

When a server misbehaves and the logs aren't enough, test it outside Cursor with the MCP Inspector. If it fails there too, the problem is the server, not Cursor.

Security Notes

A local MCP server runs with your user permissions, and every tool result lands in the model's context. Install servers only from sources you trust, prefer official servers (look for "Official" in the directory), keep approval prompts on for anything that writes data, and read our MCP security best practices before you connect production systems.

Next Steps

• Find servers worth adding in the MCP server directory or our list of the best MCP servers.
• Setting up other clients too? See Claude Code MCP, VS Code MCP setup and Claude Desktop MCP.
• New to the protocol? Start with what an MCP server is.