How to Add an MCP Server to Claude Code (and Claude Desktop)

October 14, 2026

5 min readIncludes a config generator for 4 clients

If you only need the command, here it is. For a remote server (one with a URL):

claude mcp add --transport http my-server https://example.com/mcp

For a local server (one Claude Code starts on your machine):

claude mcp add my-server -- npx -y some-mcp-package

Then type /mcp inside Claude Code to check it connected. That covers most cases. The rest of this guide covers the parts that trip people up: which scope to choose, how Claude Desktop differs, authentication headers, Windows, and what each error actually means.

Generate your config

Pick your client and server type and the generator writes the exact command or JSON, with the right file location. It is pre-filled with Enrichr’s remote server as an example. Replace the URL and header with your own server’s.

Remote vs. local servers

Every MCP server is one of two kinds, and the kind decides the command.

You may see guides that use --transport sse. SSE is the older remote transport. Use http unless a server’s own docs say it only supports SSE.

The -- in the local command matters. Everything after it is passed to your server untouched, so its flags are not mistaken for Claude Code’s own.

Local, project or user scope?

Scope answers one question: who should get this server, and where? It is the part of the docs most people skip, and the reason a server “disappears” when you change folders.

Project scope has one extra safety step. The first time a teammate opens the repo, Claude Code asks them to approve the servers in .mcp.json before any of them run. If someone clicked no by mistake, claude mcp reset-project-choices brings the prompt back.

Never commit an API key in .mcp.json. The file supports environment variable expansion, so reference the key instead:

{
  "mcpServers": {
    "enrichr": {
      "type": "http",
      "url": "https://enrichr.dev/mcp",
      "headers": { "X-API-Key": "${ENRICHR_API_KEY}" }
    }
  }
}

Adding a server to Claude Desktop

Claude Desktop and Claude Code are separate apps with separate server lists. Desktop handles the two kinds of server in two different places:

• Remote servers: Settings → Connectors → Add custom connector. Paste the URL. Because connectors live on your account, they also appear on claude.ai. Some servers authenticate with OAuth (you sign in once in a popup). Others, like Enrichr, use a header. Follow the server’s own instructions for which one to pick.
• Local servers: Settings → Developer → Edit Config opens claude_desktop_config.json. On macOS it lives at ~/Library/Application Support/Claude/; on Windows at %APPDATA%\Claude\. Add your server under mcpServers, save, then fully quit the app and reopen it. Closing the window is not enough.

Already set servers up in Desktop? claude mcp add-from-claude-desktop imports them into Claude Code (on macOS and WSL) and lets you choose which ones.

Managing your servers

Troubleshooting

What to add first

Once the mechanics work, the question becomes which servers are worth it. We keep a running list in 10 MCP servers that turn Claude Code from clever into unfair, and a free-only list in 9 free MCP servers. Before installing anything from a stranger’s repo, read how not to get burned by unaudited MCP servers. A local server runs code on your machine with your permissions.

If you build websites, the one we would add first is a way for Claude Code to see the rendered web. Without it, Claude cannot read half the pages you point it at (here is why). Client-specific setup pages: Claude, Cursor, VS Code, Windsurf, Cline.

FAQ