# How to add MCP servers to Cursor

> How to add MCP servers to Cursor: project and global mcp.json files, remote and local servers, OAuth sign-in, secrets from env vars and tool approvals.

Part 2 of [Using coding agents: Claude Code, Cursor, Codex and more](https://polylane.com/series/using-coding-agents/)
By Boris Tane, Founder of Polylane · Published October 17, 2026 · 3 min read
Canonical: https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-cursor/

To add an MCP server to Cursor, create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project, and add an entry under mcpServers. A remote server needs a url; a local one needs a command and args. Cursor signs in to servers that use OAuth and asks before it runs each tool.

To add an MCP server to Cursor, **create `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project, and add the server under `mcpServers`.** A remote server needs a `url`. A local server needs the `command` that starts it. Cursor signs in to servers that use OAuth and asks before it runs each tool.

MCP, the Model Context Protocol, is how Cursor's agent calls tools outside your editor: a database, an issue tracker, your production logs. The steps below follow [Cursor's MCP documentation](https://cursor.com/docs/context/mcp).

## 1. Pick project or global config

Cursor reads two files:

| File | Use it for |
| --- | --- |
| `.cursor/mcp.json` in the repository | Tools for this project. Commit it so the team gets the same servers. |
| `~/.cursor/mcp.json` in your home directory | Tools you want in every project, such as your own notes or a personal account. |

Start with the project file for anything the whole team needs. Keep personal accounts in the global file, so a teammate's checkout never tries to sign in as you.

## 2. Add a remote server

A remote server runs somewhere else and speaks Server-Sent Events or Streamable HTTP. It needs only a name and a `url`:

```json
{
  "mcpServers": {
    "polylane": {
      "url": "https://mcp.polylane.com/mcp"
    }
  }
}
```

If the server uses OAuth, Cursor opens the sign-in flow the first time the agent needs it, and you approve access in the browser. Servers that take a static key instead accept `headers`:

```json
{
  "mcpServers": {
    "internal-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:INTERNAL_API_TOKEN}"
      }
    }
  }
}
```

## 3. Add a local server

A local server is a program Cursor starts on your machine and talks to over stdio. Give it the `command`, its `args` and any `env` it needs:

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}
```

Everything in the file runs with your permissions, so only add servers you trust, from sources you can read.

## 4. Keep secrets out of the file

Cursor resolves variables in the `command`, `args`, `env`, `url` and `headers` fields. Use `${env:NAME}` for anything secret, as in the remote example above, and the file you commit holds only the variable's name. The same works in a local server's `env` block. `${workspaceFolder}` and `${userHome}` are also available, which helps when a local server needs a path inside the repository.

## 5. Check it works, and decide what runs without asking

Open **Customize** in the sidebar to see each server, whether it connected, and the tools it offers. You can turn a server off there without removing it from `mcp.json`.

By default Cursor asks before it uses any MCP tool and shows the arguments it is about to send. Read them the first few times: it is the quickest way to learn what a server does. Once you trust a read-only tool, allowlist it so it runs without a prompt in Auto-review mode, and keep anything that writes behind the prompt.

## What to connect first

The servers that pay off soonest give the agent context it cannot get from the code: the issue it is fixing, the database schema, and what the code is doing in production. Production is usually the gap. Cursor can read the function that failed, but not the logs, traces and deploys that show how it failed. [Polylane brings that into Cursor](/for/cursor/) through the single remote server shown in step 2, covering every cloud and observability tool you connect behind one sign-in.

Using Cursor? See [how to give Cursor production context with Polylane](https://polylane.com/for/cursor/).

## Common questions

**Where is Cursor's MCP config file?**

Cursor reads .cursor/mcp.json in the project for project tools and ~/.cursor/mcp.json in your home directory for tools you want everywhere.

**Which MCP transports does Cursor support?**

Cursor supports three: stdio for local servers it starts itself, and Server-Sent Events and Streamable HTTP for remote servers.

**How do I keep API keys out of mcp.json?**

Reference an environment variable with ${env:NAME}. Cursor resolves variables in the command, args, env, url and headers fields, so the file you commit holds the name and your shell holds the secret.

**Does Cursor run MCP tools without asking?**

Not by default. Cursor asks for approval before it uses an MCP tool, and shows the arguments it is about to send. Allowlisted tools can run without a prompt in Auto-review mode.

**How do I turn a server off without deleting it?**

Open Customize in the sidebar and disable it there. The entry stays in mcp.json, so you can turn it back on later.

## Sources

- [Model Context Protocol (Cursor docs)](https://cursor.com/docs/context/mcp)
- [Model Context Protocol specification: transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)

## About the author

Boris Tane is the founder of Polylane. He previously founded Baselime, observability for the future of the cloud, which Cloudflare acquired. At Cloudflare he built and led the Workers observability team.

## More in this series

[Using coding agents: Claude Code, Cursor, Codex and more](https://polylane.com/series/using-coding-agents/)

1. [How to use Claude Code: a practical guide](https://polylane.com/learn/coding-agents/how-to-use-claude-code/)
2. [How to add MCP servers to Cursor](https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-cursor/)
3. [How to use Codex CLI: install, AGENTS.md, MCP and exec](https://polylane.com/learn/coding-agents/how-to-use-codex-cli/)
4. [How to use OpenCode: install, plan and build, MCP](https://polylane.com/learn/coding-agents/how-to-use-opencode/)
5. [How to add MCP servers to GitHub Copilot in VS Code](https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-github-copilot/)
6. [How to use the Pi coding agent](https://polylane.com/learn/coding-agents/how-to-use-the-pi-coding-agent/)

Previous: [How to use Claude Code: a practical guide](https://polylane.com/learn/coding-agents/how-to-use-claude-code/)
Next: [How to use Codex CLI: install, AGENTS.md, MCP and exec](https://polylane.com/learn/coding-agents/how-to-use-codex-cli/)

## Related

- [How to keep AI coding agents from breaking production](https://polylane.com/learn/ai-in-production/how-to-keep-ai-coding-agents-from-breaking-production/): Stop AI coding agents breaking production: scoped credentials, branch protection they can't bypass, required checks that block, and production-aware review.
- [PlanetScale MCP Server: Setup and Production Permissions](https://polylane.com/learn/ai-in-production/planetscale-mcp-server/): Connect the official PlanetScale MCP Server to Claude Code, Cursor and Codex. Set narrow permissions, inspect Insights and review writes before execution.
- [Workers Issues: route Cloudflare errors to coding agents](https://polylane.com/learn/incident-response/cloudflare-workers-issues-error-monitoring-agents/): Cloudflare's new Workers Issues groups exceptions and 5xx errors and sends them to Claude Code, Cursor, Devin or a webhook. Setup, automations and limits.

Get started with one command: `curl -fsSL https://polylane.com/setup | bash` installs the CLI, connects your coding agents, and creates the account.