How do I add an MCP server to Cursor?

Add it to mcp.json — either ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project. Paste the server's config under mcpServers, save, and reload Cursor. Per-project configs keep your tool count low.

Why is my MCP server not showing up?

Almost always one of four things: the npx/uvx runtime isn't installed or on PATH, you reloaded instead of fully restarting the client, the JSON is malformed (a stray comma), or a required API key/env var is missing.

Where is the config file for each client?

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config). Cursor: ~/.cursor/mcp.json or .cursor/mcp.json. Windsurf: its mcp_config.json. Each server page shows the exact block for all three.

How to add an MCP server to Claude, Cursor & Windsurf

Three moves in every client: get the config, paste it in the right file, restart. Here are the exact paths — and why 'it's not working' is almost always one of four things.

Hua·June 24, 2026·6 min read

A programmer in a blue shirt coding on an iMac. — Photo by Lee Campbell on Pexels

Adding an MCP server is the same three moves in every client: get the config, paste it into the right file, restart. This is the exact version for Claude Desktop, Cursor and Windsurf — plus the four things that actually go wrong.

The universal pattern

Every MCP client reads a JSON config with an mcpServers object. A local (stdio) server looks like this:

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

A remote server uses a url instead of command/args. You rarely write this by hand — every server page gives you the exact block per client, and the config generator merges several servers into one.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config, or ~/Library/Application Support/Claude/ on macOS), paste the config under mcpServers, and fully restart Claude. Claude Desktop has no native remote transport, so remote servers are bridged through the mcp-remote proxy — the Claude setup page shows the exact form.

Cursor

Cursor reads mcp.json — global (~/.cursor/mcp.json) or per-project (.cursor/mcp.json). Per-project is the better habit: give each project only the servers it needs so you stay under the tool budget. Step-by-step on the Cursor setup page.

Windsurf

Windsurf uses its own mcp_config.json and the serverUrl key for remote servers. Details on the Windsurf setup page.

When it's "not working" — the four usual causes

Searches for "mcp server not working" almost always come down to one of these:

npx/uvx not found — the runtime isn't installed or isn't on PATH. Install Node (for npx) or uv (for uvx).
Didn't fully restart the client — a reload isn't enough; quit and reopen.
Wrong config file or bad JSON — a stray comma breaks the whole file. Paste from the server page rather than hand-editing.
Missing env/API key — the server needs a credential you didn't fill in. Check the server's auth type on its page.

Don't blow the tool budget

Each server adds its tools to the client's active set, and selection degrades past ~40. The average server is ~12 tools, so four servers is the realistic ceiling, not fifty — the full arithmetic is in the Cursor tool-limit trap. Paste your config into the Config Doctor and it tells you the total and what's over.

Next steps

Pick servers by capability or start from a task stack like a coding or data agent. New to all this? Read What is an MCP server? first.