Where is Cursor's MCP config file?

`.cursor/mcp.json` inside a project, or `~/.cursor/mcp.json` in your home directory for a global server. Both use `mcpServers` as the top-level key, so definitions are portable to and from other surfaces that use the same shape.

Can a Cursor admin restrict which MCP servers engineers connect?

Yes. Enterprise administrators manage MCP policy in team settings, including server allowlists and per-server tool restriction, and can distribute approved servers from the dashboard so there is a compliant option available.

What is the difference between an allowlist and a network denylist here?

An allowlist decides which servers may be connected at all. A network denylist decides where user-configured servers may talk once connected. The first is approval, the second is blast radius, and a mature setup uses both because approval alone assumes nothing slips through.

Is the Cursor config format the same as Claude Code's?

Close enough to copy in most cases — both use `mcpServers` with `command`/`args`/`env` for local servers and `url`/`headers` for remote ones. The differences are in scope model and admin controls rather than in the JSON, which is convenient and is also why one unreviewed server tends to spread across several tools.

MCP setup · Anysphere

How to add an MCP server to Cursor

Cursor uses the same two-file pattern most editors settled on — one in the project, one in your home directory — and layers a genuinely detailed set of team and enterprise controls on top. If you are governing Cursor at scale, the second half of this page matters more than the first.

How this surface handles MCP

The file layout is the easy part. A project file lives at `.cursor/mcp.json` and travels with the repository; a global file at `~/.cursor/mcp.json` applies wherever you open Cursor. Both use `mcpServers` as the top-level key, which means definitions move between Cursor, Claude Code and Gemini CLI with very little editing — convenient, and also why the same server tends to end up connected to three surfaces without anyone deciding that it should.

The per-server fields cover both shapes of server. A local process takes `command`, `args`, `env` and optionally `envFile`; a remote server takes `url` and `headers`, with an `auth` object for OAuth credentials and a `type` field naming the connection. Nothing here is unusual, and that is the point: the format is not where the governance question lives.

Where Cursor does something distinctive is the administrative layer. Team admins can distribute shared MCP servers from the dashboard, which is the difference between publishing an approved server and hoping engineers find the right one. Enterprise admins get a policy surface covering server allowlists, per-server tool restriction, and network access modes — and, separately, a denylist for network destinations that user-configured servers may not reach.

That last control is worth dwelling on, because it is the rarest one in this category. Allowlisting servers governs what may connect; restricting where user-configured servers may talk governs blast radius when something gets connected anyway. Most surfaces give you the first and not the second.

Where servers are stored

Project.cursor/mcp.json

reaches Anyone who opens this repository in Cursor.

Committed like any other file, so it is reviewable — and, like `.mcp.json` in Claude Code, it is capability arriving through a pull request.

Global~/.cursor/mcp.json

reaches You, in every project on this machine.

The scope where personal servers accumulate. It follows you into repositories whose owners never reviewed it.

The config shape

JSON. Servers live under `mcpServers`. A local process uses `command`/`args`/`env`; a remote server uses `url`/`headers`, with `auth` for OAuth and `envFile` available for stdio servers.

Cursor — MCP server definition

{
  "mcpServers": {
    "example-remote": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${EXAMPLE_TOKEN}" }
    },
    "example-local": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server@1.4.2"],
      "env": { "EXAMPLE_MODE": "read-only" }
    }
  }
}

Adding a server

Create the file at the right scope
`.cursor/mcp.json` in the repository if the team should have it; `~/.cursor/mcp.json` if it is genuinely personal. Choosing global because it is quicker is how a server ends up in projects nobody reviewed it for.
Pin the version for stdio servers
Write `@example/mcp-server@1.4.2` rather than the bare package name. An unpinned launcher resolves to whatever is published at the moment the agent starts, which means the thing you reviewed and the thing that runs are different objects.
Keep secrets out of the committed file
Use `envFile` for stdio servers or environment expansion for headers. A token committed into `.cursor/mcp.json` is a token in your git history, on every clone, forever.
Check whether an approved server already exists
If your team admin distributes shared servers from the dashboard, the approved definition is already there. Hand-writing a second copy is how two versions of the same server end up in one company.

Confirming it actually connected

Open Cursor's MCP settings and confirm the server appears and reports connected rather than errored. A malformed JSON file usually fails silently from the editor's point of view.
Check the tool list the server exposes and read the descriptions. If a tool you did not expect appears, that is the review, not a formality.
If your organisation runs an allowlist, confirm the server is on it before assuming a connection failure is a config problem — a blocked server and a broken server look similar from the editor.

Review this before you connect anything

the part the vendor docs will not tell you

A connected MCP server can read what its credential can read and do what its tools can do, and its tool descriptions reach the model as instructions. None of that is visible from a configuration file that parses correctly.

Read the tool descriptions as instructions
Descriptions reach the model as text it acts on. A benign-looking tool whose description instructs the agent to read a file and include it in every call is an injection that survives every permission prompt, because each individual action is permitted.
Assume the same server is connected elsewhere
Because `mcpServers` is a near-universal format, a definition pasted into Cursor is usually also pasted into a terminal agent. Review it once for the company rather than once per editor.
Scope the token before scoping the server
The credential decides the damage. A server with a read-only token that reaches one project is a different risk object from the same server with an org-wide token, and the config file looks identical either way.
Prefer an allowlist you actually maintain
An allowlist that nobody updates becomes the thing engineers route around. Pair it with a published, distributed set of approved servers so the compliant path is also the fast one.

Organisational controls

Team-distributed servers
Team admins can distribute shared MCP servers through the dashboard and configure marketplace access and installation modes, which turns 'the approved server' from a wiki page into something engineers actually receive.
Enterprise MCP policy
Enterprise administrators manage MCP policy in team settings, covering server allowlists and restriction of which tools a given server may expose.
Network access modes
Network access for MCP is configurable across modes including allow-all, allowlist and deny-all, which is a blast-radius control rather than an approval control — the two are complementary.
User MCP network denylist
Admins can permit user-configured servers outside approved patterns while denying specific network destinations to them. This is the pragmatic middle path between locking everything down and seeing nothing.

What this cannot tell you

Cursor's enterprise controls are among the strongest here, and they still describe policy rather than state. They constrain what may be connected; they do not produce an inventory of what is connected across every machine right now, at which version, alongside the same server's presence in the other AI tools your company runs.

Frequently asked

Where is Cursor's MCP config file?: `.cursor/mcp.json` inside a project, or `~/.cursor/mcp.json` in your home directory for a global server. Both use `mcpServers` as the top-level key, so definitions are portable to and from other surfaces that use the same shape.
Can a Cursor admin restrict which MCP servers engineers connect?: Yes. Enterprise administrators manage MCP policy in team settings, including server allowlists and per-server tool restriction, and can distribute approved servers from the dashboard so there is a compliant option available.
What is the difference between an allowlist and a network denylist here?: An allowlist decides which servers may be connected at all. A network denylist decides where user-configured servers may talk once connected. The first is approval, the second is blast radius, and a mature setup uses both because approval alone assumes nothing slips through.
Is the Cursor config format the same as Claude Code's?: Close enough to copy in most cases — both use `mcpServers` with `command`/`args`/`env` for local servers and `url`/`headers` for remote ones. The differences are in scope model and admin controls rather than in the JSON, which is convenient and is also why one unreviewed server tends to spread across several tools.

Sources

Every path, key, table and flag on this page was read from Anysphere's own documentation on 2026-07-26. Where a control varies by plan or is changing quickly, this page describes the mechanism rather than asserting a current state.