How to Add an MCP Server to Cursor (2026 Guide)

To add an MCP server to Cursor, you have three options: click an "Add to Cursor" button, use the Settings UI (Cursor Settings → Tools & Integrations → MCP), or add the server to a .cursor/mcp.json file. All three write to the same config, so pick whichever is fastest — then Cursor's Agent can call the server's tools during a task. This guide walks through each method, the exact JSON for remote and local servers, where the config lives, and how to fix a server that won't connect.

Last updated: July 2026. Cursor's MCP UI labels and config options change between releases; everything here was verified against Cursor's docs in July 2026 — check cursor.com/docs/mcp if a menu has moved.

An MCP server is a program that exposes tools; Cursor connects to it and lets its Agent call those tools. There are two kinds — remote servers you reach over HTTP, and local servers Cursor launches on your machine. Using Claude Code instead? See our companion guide on how to add an MCP server to Claude Code.

The Three Ways to Add an MCP Server to Cursor

Cursor doesn't have a claude mcp add-style command line. Instead, everything routes through one config store that you can reach three ways:

1. One-click "Add to Cursor" — a button a vendor provides; best when it exists.
2. The Settings UI — a form inside Cursor; best for a quick manual add.
3. Editing mcp.json — the config file itself; the source of truth, and the only method that gives you full control over headers, scope, and secrets.

The UI and the one-click buttons both write to mcp.json under the hood, so once you understand the file, all three make sense.

Method 1: One-Click "Add to Cursor"

Many servers publish an "Add to Cursor" button — on the Cursor Marketplace, cursor.directory, or a vendor's own docs. Clicking it fires a cursor:// deeplink that opens Cursor and pre-fills the server's configuration; you review it and approve. It's the fastest path when a server offers it, because you never touch JSON. If the button asks you to sign in (for a remote server with OAuth), Cursor opens the provider's auth flow and stores the result for you.

Method 2: The Cursor Settings UI

To add a server by hand without editing a file:

1. Open Cursor Settings (Cmd + , on macOS, Ctrl + , on Windows/Linux), or run "View: Open MCP Settings" from the Command Palette (Cmd/Ctrl + Shift + P).
2. Go to Tools & Integrations (older builds call this Features) → the MCP section.
3. Click "+ Add Custom MCP" (or "New MCP Server" — the label varies by version). Cursor opens the mcp.json file with a template, or shows fields for Name, Type, and Command/URL.
4. Fill in the details, save, and the server appears in the list with a status dot.

This is convenient, but it ultimately edits mcp.json — which is where the real control lives.

Method 3: Edit .cursor/mcp.json Yourself

This is the method worth learning, because it's exact, versionable, and works for every server. The file is a single JSON object with an mcpServers key.

Add a remote server (with an auth header)

Most hosted servers are remote: you give Cursor a URL, and it connects over HTTP. If the server needs authentication, add a headers block. Here's a real example adding DesignRevision MCP, a server that installs shadcn/ui components into your project:

{
  "mcpServers": {
    "design-revision": {
      "url": "https://mcp.designrevision.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Replace YOUR_TOKEN with the token from your account. One point competitors get wrong: Cursor detects the transport automatically — the presence of a url key means remote, and a command key means local. You do not need a "type" or "transport" key (you can add "type": "http" to be explicit, but it isn't required). For servers that use static OAuth instead of a bearer token, Cursor supports an auth block with a client ID and secret in place of headers.

Add a local server (stdio)

Local servers run as a subprocess on your machine. Use command, args, and an optional env block for secrets:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/code"]
    }
  }
}

command can be npx, uvx, python, node, or docker. On Windows, wrap npx-based servers in cmd /c if they fail to launch. The env block injects environment variables into the local process — the place to put an API key a local server needs.

Project vs. global: where the config lives

Cursor reads mcp.json from two places:

• .cursor/mcp.json in your repository root — applies to that project only. Commit it and everyone who opens the repo in Cursor gets the same servers.
• ~/.cursor/mcp.json in your home directory — applies to every project. Use it for general-purpose servers you always want.

Both load together, and the project file wins in its own workspace. After you save either file, toggle the server off and on (or click the refresh icon) in Settings → Tools & MCP so Cursor picks up the change — this is the single most common "why isn't it showing?" gotcha.

Keep your token out of the file

Don't hard-code a real token in a committed .cursor/mcp.json. Cursor supports variable interpolation, so you can reference an environment variable instead:

{
  "mcpServers": {
    "design-revision": {
      "url": "https://mcp.designrevision.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DESIGNREVISION_TOKEN}"
      }
    }
  }
}

Cursor also expands ${workspaceFolder}, ${userHome}, and ${pathSeparator} — handy for local server paths.

Verify It Worked: Status Dots and Agent Mode

Open Settings → Tools & MCP and check the dot next to your server:

• Green — connected, tools loaded. You're set.
• Red — connection failed (see troubleshooting below).
• Yellow — connected, but no tools were exposed. Usually a handshake mismatch or a server that registered nothing; click refresh.

Two things trip people up even when the dot is green. First, MCP tools only run in Agent mode — not in plain ask or edit — so switch to Agent in the chat pane. Second, Cursor asks for approval before running a tool by default; approve it (or set an auto-run rule) and the Agent will use the server.

Troubleshooting: When a Cursor MCP Server Won't Connect

Work through these in order — they cover almost every failure:

• Invalid JSON. A trailing comma or a missing brace silently breaks the whole file. Paste it into a validator if a server won't appear at all.
• Wrong URL or missing token. For remote servers, confirm the endpoint and that the Authorization header is present and current. A red dot on a remote server is almost always one of these.
• You didn't refresh. Edited the file but nothing changed? Toggle the server off/on, click refresh, or restart Cursor.
• The ~40-tool limit. Cursor only sends the Agent about 40 MCP tools total. Enable a dozen servers and some tools go silently missing. Disable the servers you're not actively using.
• Not in Agent mode. The tools exist but never fire because you're in ask/edit mode.
• Deprecated sources. The old cursor/mcp-servers GitHub repo is no longer maintained — find current servers on the Cursor Marketplace or cursor.directory instead.

Which MCP Servers Should You Add to Cursor?

Adding a server is easy; choosing a focused set is what makes the Agent genuinely more capable — especially given Cursor's 40-tool ceiling. GitHub, Playwright, Context7, and a database server cover most workflows, and DesignRevision MCP adds the one thing the others don't: installing real shadcn/ui components on request. Many of these same servers are broken down — with the exact .cursor/mcp.json config and an honest verdict each — in our roundup of the best MCP servers for Cursor.

Conclusion

Adding an MCP server to Cursor comes down to one file — .cursor/mcp.json — whether you reach it through a one-click button, the Settings UI, or your editor. Remote servers need a url (plus headers for auth); local servers need a command. Decide between project and global scope, keep tokens in environment variables, refresh after editing, and watch the status dot. Start with one server that fills a real gap, confirm it's green in Agent mode, and grow from there.

Related Resources

• DesignRevision MCP — the shadcn/ui MCP server
• How to Add an MCP Server to Claude Code (2026 Guide)
• How to Add an MCP Server to Codex CLI (2026 Guide)
• How to Add an MCP Server to Windsurf (2026 Guide)
• Claude Desktop MCP Config: How to Add a Server (2026)
• Best MCP Servers for Cursor (2026): Tested & Ranked
• Best MCP Servers for Claude Code (2026): Tested & Ranked
• Browse the shadcn/ui component registry