How to Add an MCP Server to Cursor

Cursor is an AI-first code editor that loads MCP servers from an mcp.json file - either per project or globally. A project-level .cursor/mcp.json is checked into your repo and shared with teammates, while ~/.cursor/mcp.json applies to every project on your machine. Both use the standard mcpServers JSON structure.

Config file location

Generate a Cursor config

The tool below is pre-set to Cursor. Fill in the server and copy the JSON — it never leaves your browser.

Transport
Advanced: environment variables

Config JSON

Where this file lives

    Working example

    A Cursor project config for the filesystem server. Put this in .cursor/mcp.json at your repo root so the whole team gets the same tools.

    {
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    }
  }
}
    .cursor/mcp.json
    {
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "/Users/you/data.db"
      ]
    }
  }
}
    Project-level .cursor/mcp.json with a SQLite MCP server pointing to a local database file.

    How to add the server, step by step

    1. Decide scope: project (.cursor/mcp.json in your repo) or global (~/.cursor/mcp.json).
    2. Paste the generated mcpServers JSON, merging with existing entries.
    3. Open Cursor Settings > MCP and confirm the server shows a green status dot.
    4. If the dot is red or grey, click the refresh icon and check the output log before editing again.
    5. Ask the agent in chat to use one of the server's tools to verify end to end.

    Cursor-specific pitfalls

    Project vs global scope confusion

    A server defined only in ~/.cursor/mcp.json will not exist for teammates, and a server in .cursor/mcp.json will not load in other projects. Pick the scope deliberately: shared tooling belongs in the project file, personal API keys in the global one.

    "Client closed" almost always means the server crashed

    Cursor's "Client closed" status sounds like a Cursor bug but usually means the MCP server process died on startup - a missing npx package, a bad arg, or a command not on PATH. Open the MCP output log in Cursor's settings panel; the server's own stderr names the real problem.

    The server is added but disabled

    Cursor lists every configured server with its own on/off toggle in Settings > MCP. After pasting a config, the server can appear switched off. No config edit fixes a disabled toggle - flip it in the UI.

    One-click installs still need review

    cursor:// deep links install a base64-encoded config directly. Convenient, but you are trusting the publisher's command and args. Paste the decoded JSON into a validator before enabling it, especially when it carries env tokens.

    FAQ

    Where does Cursor store MCP settings?

    Two places: .cursor/mcp.json inside a project for shared, repo-scoped servers, and ~/.cursor/mcp.json in your home directory for servers available in every project. Both use the standard mcpServers structure.

    Why does Cursor show "Client closed" for my MCP server?

    The server process exited right after Cursor launched it. The usual causes are a missing package (add -y to npx args), a command not on Cursor's PATH, or a bad argument. The MCP log in Cursor Settings shows the server's stderr.

    Should I commit .cursor/mcp.json to git?

    Yes if it defines shared tooling, but never commit secrets. Keep tokens in the global ~/.cursor/mcp.json or inject them via your shell environment instead of hardcoding them in the project file.

    Configuring other clients too? See the guides forClaude Desktop,Cursor,VS Code,Windsurf,Zed andCline, or readhow MCP transports differ.