Skip to content
Back to Guides

How to add an MCP server to Cursor

The Cursor logo joined to the Interfere logo by a line marked MCP
LG

Levi Gans

·

AI agents

Cursor’s agent already reads your code and runs your terminal. A Cursor MCP server gives it tools from other systems, like Linear, a database or your production errors.

Cursor supports the Model Context Protocol in the editor, the CLI and Cloud Agents. The editor and CLI share the same mcp.json files, so you set a server up once. Here’s how I’d show a teammate, ending with Interfere as a real example.

Install a Cursor MCP server from Customize

If the server is listed, this is quickest:

  1. Open Customize in the sidebar.
  2. Click MCPs and search for the server.
  3. Click Add to Cursor.
  4. Follow the sign-in prompts if the server asks for them.

The list comes from the Cursor Marketplace, which Cursor reviews by hand, updates included. For community servers, Cursor points to cursor.directory, a separate list. On a team marketplace, servers your admins share show up in Customize too.

Add an MCP server with mcp.json

For anything else, write the config yourself. Cursor reads two files:

FileWho gets the serverCommit it?
.cursor/mcp.json in the projectEveryone who opens this projectYes, so teammates get the same servers
~/.cursor/mcp.jsonYou, in every project you openNo, it’s personal

Cursor merges the two, and the project file wins on a name clash. Save, then restart Cursor to load the change.

Local servers over stdio

A local server is a command Cursor starts on your machine and talks to over stdio. This is Cursor’s Node.js example:

JSON
1{2  "mcpServers": {3    "server-name": {4      "command": "npx",5      "args": ["-y", "mcp-server"],6      "env": {7        "API_KEY": "value"8      }9    }10  }11}

The fields Cursor accepts for a stdio server:

FieldRequiredWhat it does
typeYesSet to "stdio"
commandYesThe executable to start. It must be on your path, or a full path.
argsNoArguments passed to the command
envNoEnvironment variables for the server
envFileNoA file to load more variables from, such as "${workspaceFolder}/.env"

Cursor’s field reference marks type as required, but its own examples leave it out. I’d add "type": "stdio" to match the reference.

A local server runs for you alone, and you handle its authentication, usually through env.

Remote servers over Streamable HTTP or SSE

A remote server runs somewhere else and Cursor connects to its URL. Both remote transports, Streamable HTTP and SSE, go through the same url field. Here’s Cursor’s example with just a URL:

JSON
1{2  "mcpServers": {3    "my-service": {4      "url": "https://mcp.example.com/sse"5    }6  }7}

If the server wants an API key or token instead, it goes under headers. More on that next.

TransportRuns onConfigured withUsersSign-in
stdioYour machineA shell commandJust youManual, through env
SSELocal or remoteA URLManyOAuth
Streamable HTTPLocal or remoteA URLManyOAuth

Keep secrets out of mcp.json

A project mcp.json ends up in git, so keys don’t belong in it. Cursor fills in variables in the command, args, env, url and headers fields:

  • ${env:NAME} reads an environment variable.
  • ${userHome} is your home folder.
  • ${workspaceFolder} is the project root, the folder that contains .cursor/mcp.json.
  • ${workspaceFolderBasename} is the name of that folder.
  • ${pathSeparator} and ${/} are your OS path separator.

A remote server with a bearer token looks like this:

JSON
1{2  "mcpServers": {3    "remote-server": {4      "url": "https://api.example.com/mcp",5      "headers": {6        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"7      }8    }9  }10}

Cursor has to see the variable, so restart Cursor after setting it in your shell profile. Here’s the part that bites. envFile only works for stdio servers. Remote servers read variables from your shell or system environment.

Sign in to a remote server with OAuth

If a remote server supports OAuth, its entry needs only the url. Cursor uses the authorization code flow with PKCE and finds the server’s authorization server from its metadata. With dynamic client registration, Cursor registers itself as a client, so you paste nothing.

In the editor, you sign in from Customize. In the CLI, run agent mcp login <name>, with the server’s key from mcp.json. Cursor renews expired access tokens with the server’s refresh token. No refresh token means you sign in again.

Some providers hand you a fixed client ID. Others, like Figma and Linear, make you register a redirect URL. For those, add an auth object next to the url:

JSON
1{2  "mcpServers": {3    "oauth-server": {4      "url": "https://api.example.com/mcp",5      "auth": {6        "CLIENT_ID": "${env:MCP_CLIENT_ID}",7        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"8      }9    }10  }11}

CLIENT_ID is required. CLIENT_SECRET and scopes are optional. Register these redirect URLs with the provider:

  • http://localhost:8787/callback for the desktop app
  • https://www.cursor.com/agents/mcp/oauth/callback for the web and Cloud Agents

Use MCP tools in Cursor’s agent

Agent uses the MCP tools under Available Tools when they fit your request, in Plan Mode too. Name a tool or just describe what you need.

To switch off one tool, click its name in the tools list at the top of the chat panel. To switch off a server, use its toggle in Customize. A disabled server doesn’t load or appear in chat.

By default, Cursor asks before each MCP tool call. Click the arrow next to the tool name to see its arguments first. MCP calls follow the same Run Modes as terminal commands, under Settings > Agents > Approvals & Execution:

Run ModeWhat happens to an MCP tool call
Auto-reviewAllowlisted tools run right away. A classifier reviews the rest.
AllowlistAllowlisted tools run without approval. Cursor asks about everything else.
Run EverythingEvery call runs automatically.

Auto-review is the default in Cursor 3.6 and later. If you’d rather keep the MCP allowlist in a file, create ~/.cursor/permissions.json for yourself or .cursor/permissions.json in the repository. This is Cursor’s example:

Plain Text
1{2  // Overrides the in-app MCP allowlist entirely.3  "mcpAllowlist": [4    "github:*",5    "linear:list_issues"6  ]7}

Each entry is server:tool. server is the key from mcp.json, and * matches anything. Once the file defines mcpAllowlist, the allowlist in Cursor Settings turns read-only. A team admin’s allowlist overrides both.

MCP in the Cursor CLI

The CLI command is agent:

CommandWhat it does
agent mcp listLists configured servers and their status
agent mcp list-tools <name>Lists a server’s tools and their argument names
agent mcp login <name>Signs in to a server from .cursor/mcp.json or ~/.cursor/mcp.json
agent mcp enable <name>Adds a server to your local approved list
agent mcp disable <name>Stops a server from loading or asking for approval

Inside a session, /mcp list and /mcp list-tools <name> do the same. CLI permissions live in ~/.cursor/cli-config.json, or .cursor/cli.json in a project, with entries like Mcp(datadog:*).

In print mode, agent -p, the CLI can’t stop to ask, so it rejects any MCP tool that isn’t allowed. The --approve-mcps flag approves every configured server without asking. Fine for a server you wrote. Risky for one you didn’t.

Example: connect Interfere to Cursor

Interfere is an AI tool for production bugs. Its MCP server lets Cursor’s agent read Interfere’s investigations with your own permissions. There are two endpoints:

ConnectionURL
Read and writehttps://mcp.interfere.com/mcp
Read-onlyhttps://mcp.interfere.com/mcp/readonly

Both use Streamable HTTP and OAuth, so no token goes in the config file. The read-only endpoint rejects any change to workspace data, and I’d start there. Fixing code only takes reads, and an agent that misreads a prompt can’t resolve or dismiss a problem.

Add it with mcp.json

Add this to .cursor/mcp.json, or merge it into the file you already have:

JSON
1{2  "mcpServers": {3    "interfere": {4      "url": "https://mcp.interfere.com/mcp/readonly"5    }6  }7}

Open Customize, sign in to Interfere and pick your workspace, or run agent mcp login interfere. The file holds only a URL, so the team can commit it and everyone signs in with their own account.

The server has two tools. search finds operations and their schemas, and execute runs them. On the read-only endpoint, adding "interfere:*" to mcpAllowlist lets both run without approval. Writes get rejected there anyway.

Or install the Interfere plugin

The plugin configures the server and adds an investigation skill:

Bash
1git clone https://github.com/interfere-inc/plugins.git interfere-plugins2mkdir -p ~/.cursor/plugins/local3cp -R interfere-plugins/plugins/interfere ~/.cursor/plugins/local/interfere

Reload Cursor and open Customize to connect it. If your company manages Cursor, an admin may need to allow local plugin imports.

One catch. The plugin connects to https://mcp.interfere.com/mcp, which can change workspace data within your permissions. For enforced read-only access, add the read-only endpoint yourself and disable the plugin’s write-enabled connection.

Ask about production

Give the agent a problem link, an app or a time range. For the first run, pick a problem you already understand, so you can judge the answer:

Plain Text
1Investigate recent checkout errors in my Interfere workspace. Identify the2release, affected sessions, and evidence supporting the likely cause.

Name the workspace and app if you have more than one. Ask for links to the problem, the affected sessions and the supporting traces, so you can check the evidence in Interfere. Then check the diff against it. The change should touch the failing code path, and a test should fail without it.

The Claude Code guide and the Codex guide cover the same setup for those agents, plus saving the fix as a reusable skill and checking it in production after the deploy.

Troubleshooting

Start with the logs. Open the Output panel with Cmd+Shift+U on a Mac or Ctrl+Shift+U on Windows and Linux, and pick MCP Logs. It shows server startup, tool calls and errors.

What happensWhat to do
A server you added doesn’t appearCheck the JSON is valid, save the file and restart Cursor.
A stdio server fails to startMake sure command is on your path, or use the full path.
${env:...} comes through emptyCursor can’t see the variable. Set it where Cursor can read it, then restart Cursor.
A server is stuck or out of dateRemove it in Customize and add it again. For npm servers, run npm cache clean --force first.
A stdio server won’t start on WindowsIf your admin turned on MCP network controls, ask for a Command entry with No sandbox.
A Cloud Agent stays signed in after you sign outCloud Agents keep separate sign-ins. Log out on the server’s Cloud row in Customize.
Interfere returns 401Reconnect from Customize, or run agent mcp login interfere.
Interfere refuses to change a problem’s statusYou’re on /mcp/readonly, which rejects writes. Use /mcp only for intended changes.
An Interfere request or response is too largeNarrow the time range or paginate. Requests are limited to 1 MiB and responses to 8 MiB.

When one server crashes or times out, Cursor marks that tool call as failed and the other servers keep working.

Security

An MCP server can reach outside services and run code on your behalf. Cursor’s advice comes down to five things:

  • Install servers only from developers and repositories you trust. Cursor reviews the marketplace; cursor.directory is a community list.
  • Check what data and APIs the server can reach.
  • Give it a restricted API key with the fewest permissions that work.
  • Read the source of anything that touches sensitive systems.
  • Keep secrets in environment variables, never in mcp.json.

I’d also keep mcpAllowlist short. Every entry is a call Cursor won’t stop to show you.

Where Interfere fits

We make Interfere, so weigh this part accordingly.

More teams now work like software factories. Coding agents like Cursor’s open pull requests all day, and people review and merge them. Shipping stops being the hard part. Knowing what broke in production, who it hit and whether the fix held is.

That’s why we built Interfere. It groups related errors into a problem, pulls in the traces, logs and session replays, and writes up the likely cause, tied to the release and the code. Cursor picks that up over MCP and writes the fix. Then Interfere watches production and reopens the problem if it comes back.

If you merge faster than you can review, that loop is how you keep your sanity.

It’s narrower than a full monitoring suite. Interfere has SDKs for Next.js, React with Vite and TanStack Start, and takes OpenTelemetry from everything else. It has no mobile SDKs, profiling, uptime checks or self-hosting, and it can’t yet keep your data in one region. Interfere vs Sentry covers the tradeoffs.

FAQ

Do MCP servers work in Cursor’s Cloud Agents?

Yes. Cloud Agents use MCP servers configured in the Cloud Agents dashboard. On a Team plan, admins can share servers under Dashboard > Plugins & MCPs.

Set up Interfere, connect it to Cursor, and try it on one problem you already understand.