Blog Guides Alternatives Compare
Back to Blog
AI

Claude Desktop MCP Config: How to Add a Server (2026)

View as Markdown Open in ChatGPT Open in Claude
DesignRevision Editorial DesignRevision Editorial · SaaS, frontend & developer tooling
• 6 min read
Human Written
Share:

To add an MCP server to Claude Desktop, open Settings → Developer → Edit Config, add the server to claude_desktop_config.json, and completely restart the app. Local servers slot straight into that file; remote servers need a small bridge, because the config is stdio-only. This guide covers the config file, local and remote servers (with a real auth-token example), the Connectors alternative, and the PATH error that trips up almost everyone.

Last updated: July 2026. Claude Desktop's MCP setup and Connectors have changed repeatedly through 2026; everything here was verified against Anthropic's docs in July 2026 — check support.claude.com if a menu has moved.

Claude Desktop vs. Claude Code: Which One Are You Configuring?

These are two different products, and the setup is different for each — a distinction the popular "claude mcp config" search blurs. Claude Desktop is the GUI app: you add MCP servers by editing claude_desktop_config.json or through its Connectors UI. Claude Code is the command-line tool: it uses the claude mcp add command and a project .mcp.json, and connects to remote servers natively. There is no claude mcp config command. If you want the CLI, see our Claude Code guide instead. This page is about the desktop app.

Where Claude Desktop Keeps Its MCP Config

The config file lives at:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

(There's no official Linux desktop app.) The reliable way to open it: click the Claude menu in your system menu bar (on macOS, this is not the in-window account settings), choose Settings → Developer → Edit Config. That button creates the file if it doesn't exist and opens it in your editor. Every server is an entry under the top-level mcpServers key.

Add a Local MCP Server (stdio)

Local servers run as a subprocess. Here's the canonical example — the Filesystem server, scoped to two folders:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Desktop",
        "/Users/you/Downloads"
      ]
    }
  }
}

When a server needs a secret, add an env block: "env": { "API_KEY": "your-key" }. Two rules the docs are strict about: paths must be absolute, not relative, and after saving you must fully restart Claude Desktop (see below).

Add a Remote MCP Server (with a Token)

Here's the part most guides get wrong: claude_desktop_config.json only understands local (stdio) servers. It has no field for a remote URL. To connect a remote HTTP server, you bridge it through the mcp-remote proxy, which Claude Desktop runs as a local process that forwards to the remote endpoint.

Here's a real example adding DesignRevision MCP, a server that installs shadcn/ui components into your project, authenticated with a bearer token:

{
  "mcpServers": {
    "design-revision": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.designrevision.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Notice the header is written as Authorization:${AUTH_HEADER} with no space around the colon, and the actual Bearer YOUR_TOKEN value lives in the env block. That's deliberate: Claude Desktop doesn't escape spaces inside args when it launches npx, so an inline "Authorization: Bearer xxx" breaks (especially on Windows). Moving the token into an environment variable is the reliable cross-platform form. Replace YOUR_TOKEN with the token from your account, save, and restart.

Or Use Connectors (for OAuth Servers)

Claude Desktop also has a Connectors UI for remote servers — Settings → Connectors → Add → Add custom connector → paste the URL → authenticate. It's cleaner than the bridge (no Node, no PATH issues, and it syncs across web and mobile), but there's a catch: Connectors authenticate over OAuth only. There's no field for a static Authorization: Bearer header, so a token-based server like the DesignRevision example above can't be added this way — use the mcp-remote bridge for those. Reach for Connectors when a remote server supports OAuth. On the free plan you get one custom connector; Pro, Max, Team, and Enterprise have no limit.

Verify It Worked — and Always Restart

MCP servers load only at startup, so completely quit Claude Desktop and reopen it — closing the window or minimizing to the menu bar/tray isn't enough. After it restarts, open the "Add files, connectors, and more" slider at the bottom-left of the message box, then Connectors → Manage connectors to see each server and the tools it exposes. A server with its tools listed is connected and ready.

Troubleshooting: When a Server Won't Show Up

  • npx/node not found (the #1 issue). Claude Desktop does not inherit your shell PATH, so a GUI launch can't see Homebrew, nvm, or a user-installed Node. Fix it by using an absolute path in command — e.g. "/usr/local/bin/npx" or your full nvm path (which npx shows it).
  • Invalid JSON. A trailing comma or an unescaped Windows backslash means the server silently never appears. Validate the file.
  • Relative paths. The docs require absolute paths in the config — no ~ or ./.
  • Read the logs. macOS: ~/Library/Logs/Claude/mcp*.log; Windows: %APPDATA%\Claude\logs\. Tail them while restarting to see the real error.
  • Still stuck? Run the exact command + args in a terminal by hand — it usually surfaces the underlying failure immediately.

Which MCP Servers Work With Claude Desktop?

Any MCP server works — local ones run as stdio processes, remote ones through the bridge or Connectors. Filesystem and GitHub are good first picks, and DesignRevision MCP adds something the others don't: installing real shadcn/ui components on request. The same servers work across every agent — we break down the most useful ones, with a verdict each, in our roundup of the best MCP servers for Claude Code; they apply to Claude Desktop too, only the config differs.

Conclusion

Configuring MCP in Claude Desktop comes down to one file — claude_desktop_config.json — opened through Settings → Developer → Edit Config. Local servers go in directly; remote servers ride the mcp-remote bridge (or Connectors, if they speak OAuth). Use absolute paths, keep tokens in env variables, fully restart after every change, and check the logs when something doesn't appear. Start with one server that fills a real gap and build from there.

Related Resources

Frequently Asked Questions

At ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows. The easiest way to open it is Claude Desktop → Settings → Developer → Edit Config, which creates the file if it doesn't exist yet. There is no official Linux desktop app.

The config file only speaks stdio, so a remote HTTP server is bridged with the mcp-remote proxy: set "command": "npx" and pass mcp-remote plus the URL and an Authorization header in "args". If the remote server uses OAuth instead of a static token, you can add it through Settings → Connectors → Add custom connector instead.

Claude Desktop is the GUI app; you add MCP servers by editing claude_desktop_config.json (stdio) or via the Connectors UI. Claude Code is the command-line tool; it uses the claude mcp add command and a .mcp.json file, and it supports remote HTTP servers natively. There is no "claude mcp config" command — that phrase mixes up the two.

The most common cause is that Claude Desktop does not inherit your shell PATH, so it can't find npx or node — use an absolute path like /usr/local/bin/npx in the config. Other causes: invalid JSON, relative file paths (they must be absolute), or forgetting to fully quit and restart the app after saving.

Yes — completely quit Claude Desktop and reopen it, not just close the window or minimize it to the tray or menu bar. MCP servers are only loaded at startup, so changes to claude_desktop_config.json won't take effect until a full restart.

Connectors are Claude Desktop's UI for adding remote MCP servers without editing the config file (Settings → Connectors → Add custom connector). They authenticate over OAuth, so they work for servers that support it. Free users get one custom connector; Pro, Max, Team, and Enterprise plans have no such limit.

No. Claude Desktop is configured through the claude_desktop_config.json file, not a command. The claude mcp subcommands (add, list, get, remove) belong to Claude Code, the separate command-line tool. If you searched "claude mcp config," decide first whether you mean the Desktop app or Claude Code.

Any MCP server works — local ones run directly as stdio processes, and remote ones connect through the mcp-remote bridge or Connectors. Good starting picks are the Filesystem and GitHub servers, plus DesignRevision MCP for installing real shadcn/ui components. Keep the set focused so the tool list stays manageable.

Join 50k+ subscribers

Web dev, SaaS, growth & marketing. Weekly.

Thanks for subscribing! Check your email.

No spam, unsubscribe anytime.

Back to all articles

Keep Learning

More articles you might find interesting.