How to add an MCP server to Cursor

Cursor reads MCP servers from a JSON file, either globally for every project or checked into a single repository.

Where Cursor keeps its MCP config

Global (all projects): ~/.cursor/mcp.json
Project: .cursor/mcp.json

Pick global or project

A file at ~/.cursor/mcp.json applies to every project you open. A .cursor/mcp.json inside a repository applies only there and travels with the code if you commit it.

Project config is the better default for anything team-specific, and the only sensible choice for a server whose paths are relative to that repository.

Add the server

The shape is the same either way, under the mcpServers key. Create the file if it does not exist — Cursor does not generate it for you.

.cursor/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Check it connected

Open Cursor Settings and find the MCP section. Each configured server shows a status indicator and, once connected, the list of tools it exposes.

Toggling a server off and on again in that panel re-runs the connection, which is quicker than restarting Cursor when you are iterating on a config.

If the server does not appear

Check the JSON parses. A trailing comma is the single most common cause of a server that silently never appears — the client cannot read the file, so it falls back to no servers rather than reporting an error.

Use an absolute path to the command. Clients do not always launch with your shell's PATH, so `npx` may resolve interactively and fail on startup. `which npx` gives you the full path to paste in.

Check the server actually runs on its own. Paste the same command into a terminal: if it exits immediately, the problem is the server or its credentials, not the client config.

Frequently asked questions

Where does Cursor store its MCP config?

Globally at ~/.cursor/mcp.json, and per project at .cursor/mcp.json inside the repository. Project config wins for that project.

How do I know whether a Cursor MCP server connected?

Open Cursor Settings and go to the MCP section. Connected servers show their tool list; a server that failed shows an error state instead.

Can I commit .cursor/mcp.json?

Yes, and it is a good way to give a team the same tools. Keep credentials out of it — reference an environment variable instead of pasting a token.