How to add an MCP server to Cursor

Quick answer

1. Create ~/.cursor/mcp.json (all your projects) or .cursor/mcp.json in your project folder (that project only).
2. Add the server under an mcpServers key: a command for a local server, or a url for a remote one (examples below).
3. Save the file and restart Cursor.
4. Open Customize in the sidebar, then MCPs, and check the server is listed and switched on.

Prefer not to edit JSON? Use the one-click install first and come back to mcp.json for anything it doesn't list.

Option 1: one-click install from Customize

1. Open Customize in Cursor's sidebar and click MCPs.
2. Browse or search for the server you want.
3. Click Add to Cursor next to it.
4. Follow the sign-in (OAuth) prompts if the server asks for them.

These entries come from the Cursor Marketplace. Cursor also points to cursor.directory for community plugins and MCP servers; community servers aren't reviewed by Cursor, so check who publishes them before installing.

Option 2: add a server with mcp.json

Where the file goes

• Global (just you, every project): ~/.cursor/mcp.json in your home folder.
• Project (this project, can be shared with your team through git): .cursor/mcp.json in the project root.

Cursor merges both files. If the same server name appears in both, the project file wins.

A local (stdio) server

A local server is a program Cursor starts on your machine. You give it a command and optional args and env. This adds Playwright MCP, which lets the Agent open and control a browser (it needs Node.js 18 or newer):

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

The key (playwright here) is just a label you choose. The command has to be on your system PATH or be a full path to the program.

A remote server (URL)

A remote server is hosted by the provider and reached over HTTP. Cursor supports Streamable HTTP and SSE endpoints with a url. This adds the Notion MCP server. After saving, enable it in Customize and complete Notion's OAuth sign-in to connect your workspace:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

A remote server that needs a token

Some servers take an API key or token in a header instead of OAuth. The GitHub MCP Server's Cursor guide uses a GitHub personal access token as a Bearer header. Rather than pasting the token into the file, read it from an environment variable with ${env:NAME}:

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

Set GITHUB_PAT in your shell profile (for example export GITHUB_PAT=... in ~/.zshrc), then restart Cursor so it picks up the variable. Give the token only the repositories and permissions you want the Agent to have.

Several servers in one file

Each server is one entry inside the same mcpServers object. Separate entries with a comma, and don't leave a comma after the last one:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Keep API keys out of mcp.json

A project .cursor/mcp.json is meant to be committed, so never put real keys in it. Cursor resolves these variables in command, args, env, url and headers:

• ${env:NAME}: an environment variable.
• ${userHome}: your home folder.
• ${workspaceFolder}: the project root (the folder that contains .cursor/mcp.json).
• ${workspaceFolderBasename}: the project folder's name.
• ${pathSeparator} or ${/}: the OS path separator.

Local (stdio) servers can also load variables from a file with envFile, for example "envFile": "${workspaceFolder}/.env". Remote servers don't support envFile, so use ${env:NAME} for them. Keep .env in .gitignore.

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Check that it works

1. Open Customize → MCPs. The server should be listed with its toggle on.
2. In the Agent chat, ask for something only that server can do, for example "Use playwright to open https://example.com and tell me the page title".
3. Approve the tool call. Cursor asks for approval before running MCP tools unless your approval settings (Cursor Settings → Agents → Approvals & Execution) let them run; click the arrow next to the tool name to see the arguments it will send.

Common errors and fixes

The server doesn't show up

• Check the path and name: the file must be mcp.json inside a .cursor folder, either in your home folder or in the project root.
• Check the JSON. A trailing comma, a missing quote or a missing closing brace makes the file invalid. Paste it into any JSON validator.
• Restart Cursor after editing the file.

Read the MCP logs

Open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux) and pick MCP Logs from the dropdown. It shows connection errors, authentication problems and server crashes, which usually name the fix.

"command not found" or the server exits immediately

• Most local servers start with npx or uvx, so install Node.js (for npx) or uv (for uvx) first, then restart Cursor.
• If Cursor still can't find it, use the full path to the program in command (run which npx on macOS/Linux or where npx on Windows to get it).
• Run the same command in a terminal (for example npx @playwright/mcp@latest). If it errors there, the message tells you what's missing. If it starts and waits silently, the server works and the problem is in the config.
• On Windows, some servers' READMEs (such as the official Filesystem server) launch npx through cmd /c: set "command": "cmd" and put "/c", "npx" at the start of args.

The server can't see my API key

If the server relies on variables set in your shell profile, make sure Cursor can see them and restart Cursor after changing the profile. For local servers, putting the key in env or an envFile avoids the problem.

Authentication fails on a remote server

• For token servers, check the header format (Authorization: Bearer <token>), that the token hasn't expired, and that it has the permissions the tool needs.
• For OAuth servers, remove the server in Customize → MCPs and add it again to restart the sign-in.

A Docker-based server won't start

Servers that run with "command": "docker" (such as the local version of the GitHub MCP Server) need Docker Desktop installed and running before Cursor starts them.

An npm-based server is stuck on an old version

Cursor's docs suggest removing the server in Customize, running npm cache clean --force, then adding it again.

Too many tools

Every server adds tools the Agent has to choose from. Switch off servers you're not using with their toggle in Customize → MCPs; disabled servers don't load or appear in chat, and you keep their config.

Stay safe with MCP servers

• Install servers from the company or project that makes them. Our listings link to each official repo or docs page.
• Use the narrowest key you can: read-only modes, restricted tokens, a single project or repository.
• Read tool calls before approving them, especially ones that write, delete or spend money.
• Be careful with servers that read outside content (web pages, issues, emails): that text can carry prompt-injection instructions.

Good servers to try first

• Context7: current, version-specific library docs in the chat.
• GitHub MCP Server: issues, pull requests and Actions runs.
• Playwright MCP or Chrome DevTools MCP: let the Agent open and check your app in a real browser.
• Figma MCP Server: design context from a Figma frame link.
• Linear MCP or Notion MCP: tickets and specs.
• Supabase MCP Server or Neon MCP Server: your database (start in read-only mode).

See every server we list in MCP Servers. Each page has setup steps checked against the official docs.

FAQ

Should I use the global or the project mcp.json?

Use ~/.cursor/mcp.json for personal tools you want everywhere, and .cursor/mcp.json for tools a project's team should share. Keep keys out of the project file with ${env:NAME}.

Which transports does Cursor support?

stdio (a local command Cursor starts), SSE and Streamable HTTP (both by URL). If a provider offers both a /sse and an /mcp endpoint, use the one its docs recommend for Cursor.

Can I turn a server off without deleting it?

Yes. Use the toggle next to it in Customize → MCPs.

Using Claude Code too?

Claude Code reads the same kind of mcpServers entries but stores them differently. See the best MCP servers for Claude Code for the claude mcp add commands.