How to add an MCP server to Cursor

Add MCP servers to Cursor from the Customize page or by editing .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects).

Local servers: Yes; runs stdio servers
Hosted servers: Yes; connects by URL
Config: JSON; how servers are added
Picks: 5; ranked

Open Customize in the Cursor sidebar to install and manage MCP servers, or edit mcp.json yourself. Put it in .cursor/mcp.json for one project or ~/.cursor/mcp.json for every project. Cursor runs local servers over stdio and connects to remote ones over streamable HTTP or SSE, with OAuth sign-in for servers that need it. The Cursor CLI reads the same configuration.

Good for

Developers who want Cursor to reach docs, GitHub, Sentry or a browser
Teams sharing one project config in .cursor/mcp.json
Admins who need an allowlist for which MCP servers people may run
People using the Cursor CLI who want the same servers in the terminal

Install Cursor

Cursor

1
Open Customize in the Cursor sidebar.
2
Install a server from the Cursor Marketplace with "Add to Cursor", which also signs you in with OAuth.
3
Or add a server by hand in mcp.json (methods below).
4
Use the toggle next to a server to turn it on or off.

The CLI and the editor share one configuration. By default Cursor asks for approval before using an MCP tool; Run Mode can change that.

From the vendor's docs. Source.

At a glance

Config file (all projects): ~/.cursor/mcp.json
Config file (one project): .cursor/mcp.json
Top-level key: mcpServers
Transports: stdio, SSE, streamable HTTP
Sign in (OAuth): Supported; static client ID via the auth object
Protocol features: Tools, prompts, resources, roots, elicitation, MCP Apps
Variables in config: ${env:NAME}, ${userHome}, ${workspaceFolder}
Tool approval: Asks before using MCP tools by default; Run Mode applies
Debug logs: Output panel, then MCP Logs
CLI commands: agent mcp list, list-tools, login, enable, disable
Team controls: Team MCP distribution and an enterprise MCP allowlist

Add an MCP server to Cursor

1
Pick where the config lives
Create .cursor/mcp.json in your project for project-only tools. Create ~/.cursor/mcp.json in your home folder for tools you want everywhere.
2
Add a local server (stdio)
```
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}
```
Add an env object for keys. Use ${env:NAME} to read a value from your shell instead of pasting it.
Uses Context7

Or add a remote server by URL

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

If the server uses OAuth, Cursor opens the sign-in when you connect.

4
Check it loaded
Open Customize in the sidebar and look for the server and its tools. From a terminal, run agent mcp list and agent mcp list-tools <identifier>.
5
Use it in a prompt
By default Cursor asks for approval before it uses an MCP tool. Click the arrow next to the tool name to see the arguments first.
Prompt
```
Use context7 to look up the current Next.js docs for server actions, then update app/actions.ts to match.
```
Uses Context7
6
If it does not work
Open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U elsewhere), choose MCP Logs from the dropdown, and read the connection, sign-in or crash messages.

Best MCP servers for Cursor

Official servers with an approved PlugWiki page that run in Cursor over stdio or HTTP; ordered by GitHub stars, then name. Derived from data we hold.

MCP servers that work in Cursor

40 · official first, then servers with a page, then by stars

Show all 40

Common errors and fixes

Server will not connect or crashes
Cause: The cause shows up in the MCP logs: connection errors, sign-in problems or a server crash.
Fix: Open the Output panel, choose MCP Logs, and read the error for that server.
cursor Source
OAuth provider rejects the redirect (for example Figma or Linear)
Cause: The provider needs a fixed client ID and an allowed redirect URL, or does not support dynamic client registration.
Fix: Add an auth object with CLIENT_ID to the server entry, and register https://www.cursor.com/agents/mcp/oauth/callback and http://localhost:8787/callback with the provider.
cursor Source
Cursor asks you to sign in again when the token expires
Cause: The server returned an access token with an expiry but no refresh token.
Fix: If your provider issues refresh tokens only for a scope such as offline_access, add that scope to auth.scopes.
cursor Source
envFile is ignored for a remote server
Cause: envFile works only for stdio servers.
Fix: Use ${env:NAME} in the url or headers and set the variable in your shell profile or system environment.
cursor Source
Signed out locally but Cloud Agents still use the server
Cause: Cloud Agents keep their own MCP sign-ins on Cursor servers.
Fix: Open Customize and log out on the server's Cloud row.
cursor Source
An npm-based server stays on an old version
Cause: The npm cache holds the old package.
Fix: Remove the server from Customize, run npm cache clean --force, then add it again.
cursor Source

Verdict

Cursor supports stdio, SSE and streamable HTTP with OAuth, and the CLI reuses the same mcp.json. The main limit is that it asks for approval before using MCP tools by default; Run Mode, which follows the same modes as terminal commands, changes that.

Best for

Developers who want project-level and global MCP servers in one JSON file
Teams that need an admin allowlist for MCP servers

Skip it if

You need a TOML or YAML config
You do not want an approval prompt on MCP tool calls and would rather tune Run Mode

Questions

Where is the Cursor MCP config file?

~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project. Both use a top-level mcpServers object.

Does Cursor support remote (HTTP) MCP servers?

Yes. Cursor supports stdio, SSE and streamable HTTP. For a remote server, set url and optional headers instead of command.

Does Cursor support OAuth for MCP servers?

Yes. Cursor opens the sign-in for servers that need it. If a provider needs a fixed client ID, add an auth object with CLIENT_ID to the server entry.

How do I use an environment variable in mcp.json?

Write ${env:NAME} in command, args, env, url or headers. ${workspaceFolder} and ${userHome} also work.

How do I turn an MCP server off in Cursor?

Open Customize in the sidebar, find the server and flip its toggle. A disabled server does not load or show up in chat.

Can I use the same MCP servers in the Cursor CLI?

Yes. The CLI reads the same configuration as the editor. Run agent mcp list to see servers and agent mcp login <identifier> to sign in.

How do I see why an MCP server fails in Cursor?

Open the Output panel and pick MCP Logs. It shows startup, tool calls and errors.

Can admins limit which MCP servers my team can run?

Yes. Enterprise admins can set an MCP allowlist under Team Settings, by command pattern for local servers and URL pattern for remote ones.

Information

updated Nov 2, 2026

Transports: stdio, SSE, Streamable HTTP
Config file (all): .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
MCP docs: cursor.com

Docs

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

Model Context Protocol (MCP) · cursor.com
MCP (Cursor CLI) · cursor.com