·

Configuring MCP In Cursor

Step-by-step setup of MCP servers in Cursor, so your AI agent can reach external tools and data from day one.

Cursor was one of the earliest editors to bolt MCP support onto Agent Mode, and it shows both in the maturity of the feature and in a few sharp edges that have persisted across releases. This guide covers the GUI panel, the raw JSON config it edits, and — because this is where most support tickets land — the specific failure modes you'll hit when a server refuses to connect.

Accessing Cursor's MCP Configuration Panel

Open Cursor Settings (Cmd+Shift+J on macOS, Ctrl+Shift+J on Windows/Linux) and navigate to Features → MCP, or in newer Cursor versions, Tools & Integrations → MCP Servers. Cursor renamed this section at least once across recent releases, so if the exact path doesn't match, search "MCP" in the settings search box — it's faster than hunting through nested menus.

The panel lists every configured server with a status indicator, a tool count once connected, and an "Enabled" toggle per server. Click + Add new global MCP server for a user-level server, available across every project, or add one scoped to the current project (details on scoping below).

Before adding anything through the GUI, confirm Cursor itself is current — MCP support has improved meaningfully release over release, and an old Cursor build with a new MCP server can produce baffling "0 tools found" results that have nothing to do with your config:

Cursor menu → Check for Updates

Cursor requires no separate CLI install; MCP configuration lives entirely inside the editor and its config files. That said, if you also use Cursor's terminal integration to run npx/uvx commands for MCP servers, make sure those binaries resolve on PATH inside Cursor's integrated terminal specifically — a PATH that works in iTerm but wasn't inherited by Cursor's terminal is a classic false lead when a stdio server "won't start."

which npx
which uvx

Tips
- Check Cursor's version before troubleshooting any MCP issue — several early rough edges (silent tool-list truncation, SSE reconnect bugs) were fixed in point releases rather than requiring a config change.
- Verify npx/uvx resolve inside Cursor's own integrated terminal, not just your system terminal — GUI-launched apps on macOS don't always inherit the same PATH as a terminal you opened yourself.

Adding MCP Servers via JSON Config in Cursor

Cursor, like Claude Code, is ultimately driven by a JSON file — you can edit it directly instead of clicking through the panel, and for managing more than a couple of servers this is faster and diff-friendly in git.

Project-scoped config: .cursor/mcp.json at the repo root. User-scoped (global) config: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/dev"
      }
    },
    "figma": {
      "url": "http://127.0.0.1:3845/sse"
    },
    "linear": {
      "url": "https://mcp.linear.app/http",
      "headers": {
        "Authorization": "Bearer ${LINEAR_MCP_TOKEN}"
      }
    }
  }
}

Cursor's schema quirks worth knowing:

  • No explicit type field for remote servers — Cursor infers SSE vs. streamable-HTTP from the URL and response headers at connect time, similar to Gemini CLI's approach but using a single url key for both (unlike Gemini's url/httpUrl split).
  • env values in project-scoped .cursor/mcp.json are not interpolated from your shell by default in all Cursor versions — some releases require literal values or Cursor-specific variable syntax rather than standard ${VAR} shell interpolation. Test this on your installed version before committing a config that assumes shell interpolation works; if it doesn't, keep secrets in the global ~/.cursor/mcp.json instead, which is more consistently treated as a local, non-shared file.
  • Cursor supports a disabled: true flag per server as an alternative to deleting the block, similar to OpenCode's enabled flag:
{
  "mcpServers": {
    "experimental-server": {
      "command": "npx",
      "args": ["-y", "some-experimental-mcp-server"],
      "disabled": true
    }
  }
}

After editing the JSON directly, return to the MCP settings panel — Cursor should hot-reload and show the new server without a full editor restart in most recent versions, though older builds sometimes need Cmd+Shift+P → Reload Window to pick up the change.

Tips
- Don't assume ${VAR} interpolation works in project-scoped .cursor/mcp.json without testing on your specific Cursor version — this has been inconsistent across releases, and a token that silently doesn't resolve is worse than an error.
- Use disabled: true rather than deleting a server block when troubleshooting — it keeps the working config nearby for quick A/B comparison as you isolate the actual problem.

Using Cursor Agent Mode with Custom MCP Tools Enabled

MCP tools only surface inside Cursor's Agent Mode (also called Composer in some UI states) — they are not available in plain autocomplete or in Ask mode's simpler chat. Switch to Agent Mode via the mode selector at the top of the chat panel before expecting tool calls to work at all; this trips up more new users than any config issue.

Once in Agent Mode, with servers connected, Cursor exposes each tool for the model to call autonomously as part of a multi-step task:

> Using the postgres MCP server, check whether the "users" table has an index on email,
> and if not, generate a migration to add one following this repo's existing migration format.

Cursor's agent will call the tool, inspect the schema, and generate a file — showing each tool invocation inline as a collapsible step you can expand to see the raw request/response, which is useful for verifying the agent isn't hallucinating tool output.

You can control which tools are available per-conversation via the tool picker (a small icon near the chat input in Agent Mode) — this lets you scope down a large registered tool set to just what's relevant for the current task, which both speeds up tool selection and reduces the chance of the model calling the wrong similarly-named tool from a different server.

For destructive operations, Cursor prompts for per-call approval by default (a confirmation dialog showing the exact tool call arguments before execution) unless you've explicitly allow-listed that tool. Managing this allow-list is a real trade-off: faster iteration versus a real safety net against a model deciding to run DROP TABLE because it misread a prompt.

Settings → Features → MCP → [server] → Auto-run: Off/On/Ask

I keep write-capable tools (database writes, file deletion, git push) on "Ask" permanently, and only allow-list clearly read-only tools (schema inspection, search, read-only API calls) for auto-run.

Tips
- Confirm you're in Agent Mode, not Ask mode, before troubleshooting "why isn't Cursor using my MCP tools" — this is the single most common false alarm.
- Use the per-conversation tool picker to scope down large tool sets for a specific task — it materially improves tool-selection accuracy, especially once you have 8+ tools registered across several servers.

Debugging MCP Connection Issues in Cursor

When a server shows red or stuck "connecting" in the MCP panel, work through these in order — this is roughly the sequence that resolves the issue fastest based on which failure mode is most common in practice.

1. Check the MCP logs panel. Cursor has a dedicated output channel for MCP:

View → Output → select "MCP Logs" from the dropdown

This shows the raw connection attempt, including the exact command Cursor tried to spawn and any stderr output from the child process — the equivalent of Claude Code's --mcp-debug flag, but always-on rather than opt-in.

2. Run the stdio command manually. Copy the command + args straight out of .cursor/mcp.json and run it in Cursor's own integrated terminal:

npx -y @modelcontextprotocol/server-postgres

If it errors here, the problem is the server or its environment, not Cursor's MCP client — fix it at this level first.

3. Check for a PATH mismatch. As noted earlier, GUI-launched Cursor doesn't always see the same PATH as your regular terminal, especially on macOS when Cursor is launched via Spotlight or the Dock rather than cursor . from a shell:

echo $PATH

4. Verify remote server reachability directly, bypassing Cursor entirely, for SSE/HTTP servers:

curl -N https://mcp.linear.app/http \
  -H "Authorization: Bearer ${LINEAR_MCP_TOKEN}"

A 401 here means the token is wrong or expired — a Cursor config issue disguised as a connection issue. A connection timeout points to network/firewall, not Cursor.

5. Check for a stale global vs. project config conflict. If the same server name exists in both ~/.cursor/mcp.json and .cursor/mcp.json with different definitions, Cursor's precedence rules (project generally overrides global) can produce a connection using settings you didn't expect:

grep -A5 "server-name" ~/.cursor/mcp.json .cursor/mcp.json

6. Restart Cursor's MCP client without restarting the whole editor, if your version exposes it:

MCP Settings panel → [server] → Restart

If not available, Reload Window is the next lightest option before a full editor restart.

Tips
- Always reproduce a stdio server failure by running the exact command manually in Cursor's own integrated terminal — it isolates "server problem" from "Cursor problem" in under a minute.
- Keep the MCP Logs output channel open in a split pane while iterating on a new server config — watching the raw connection attempt live is faster than toggling the server off/on and re-checking the status dot each time.

Tips

Tips
- Confirm you're in Agent Mode before debugging any "tool not available" issue — it's the most common false alarm with Cursor's MCP support.
- Don't assume ${VAR} shell interpolation works in project-scoped .cursor/mcp.json on every version — verify it, and fall back to global config or Cursor's own secret-handling UI for anything sensitive.
- Keep write-capable tools on manual "Ask" approval permanently; only auto-run tools you've confirmed are read-only, and revisit that list whenever a server's tool set changes.