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

> Add an MCP server to Cursor via one-click, the Settings UI, or .cursor/mcp.json — with remote and local examples, auth headers, and red-dot fixes.

Source: https://designrevision.com/blog/add-mcp-server-to-cursor

---

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](/blog/add-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](https://cursor.com/marketplace), [cursor.directory](https://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](/mcp)**, a server that installs [shadcn/ui components](/components) into your project:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://cursor.com/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](/blog/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](/mcp)
- [How to Add an MCP Server to Claude Code (2026 Guide)](/blog/add-mcp-server-to-claude-code)
- [How to Add an MCP Server to Codex CLI (2026 Guide)](/blog/add-mcp-server-to-codex)
- [How to Add an MCP Server to Windsurf (2026 Guide)](/blog/add-mcp-server-to-windsurf)
- [Claude Desktop MCP Config: How to Add a Server (2026)](/blog/claude-desktop-mcp-config)
- [Best MCP Servers for Cursor (2026): Tested & Ranked](/blog/best-mcp-servers-for-cursor)
- [Best MCP Servers for Claude Code (2026): Tested & Ranked](/blog/best-mcp-servers-for-claude-code)
- [Browse the shadcn/ui component registry](/components)