How to add an MCP server to Claude Desktop

To add an MCP server to Claude Desktop, first check which kind you have. A remote server is a URL: open Customize, then Connectors, click + Add, then Add custom connector, paste the URL and sign in. A local server is a program on your computer: install it as a desktop extension, or add it to claude_desktop_config.json through Settings, Developer, Edit Config, then completely quit and restart the app. This guide walks through all three routes and the fixes for the errors you are most likely to hit.

Is your MCP server remote or local?

Look at what the server's docs tell you to paste. If it is an https:// address, often ending in /mcp, it is a remote server. Someone else runs it, you sign in to it, and nothing gets installed. If the docs give you a command such as npx -y some-package, it is a local server: a program Claude Desktop starts on your machine.

The difference matters beyond the setup screen. Anthropic's custom connector guide(checked November 2026) says "Claude connects to your remote MCP server from Anthropic's cloud infrastructure, rather than from your local device", and that servers behind a VPN or blocked by a firewall won't connect. The same page says local servers configured in claude_desktop_config.jsonare a separate mechanism and "aren't available in Cowork or claude.ai." So a remote connector follows you to Claude on the web, and a config-file server stays on your desktop. If you want the background first, the MCP explainer covers hosts, clients and servers in plain terms.

Which of the three setup routes should you use?

The server usually decides for you. Match what you were given to the column below.

How do you add a remote MCP server as a custom connector?

This is the route for any server that gave you a URL. These are the steps for Pro and Max accounts, as Anthropic's custom connector guidelists them (checked November 2026). The same page says "Free users are limited to one custom connector."

1. Go to Customize, then Connectors.
2. Click + Add, then Add custom connector.
3. Enter a name. This is the name you see in the connectors list.
4. Add the server's URL exactly as its docs give it, path included, and click Continue.
5. Check the auth settings Claude detected, change them if needed, and click Continue.
6. Under Authentication, choose Sign in now, Sign in when needed or No sign in.
7. Under OAuth client, choose Use Claude's published identity (Recommended), Register automatically or Use your own OAuth client. This option does not appear if you chose No sign in.
8. Only if the server wants a fixed API key or bearer token instead of OAuth, add it under Request headers.
9. Click Add.

Which OAuth client option to pick is a question for the server's docs. Take the recommended one unless they say otherwise. If they say the server supports dynamic client registration, Register automatically fits, and if the vendor gave you a client ID and secret, use your own OAuth client.

To use the connector, the guide says to enable it per conversation through the + button on the lower left of the chat, choose Connectorsand use the toggles. Tools you don't need can be switched off from the Search and tools menu.

Two things catch people out. A custom connector can't be edited: to change the URL or the auth, remove it and add it again. And because the call comes from Anthropic's cloud, a server on localhost or on your company VPN will fail here even though it loads fine in your own browser.

On Team and Enterprise plans

Per the same guide, an Owner goes to Organization settings, then Connectors, clicks Add, hovers over Custom and selects Web, then fills in the same name, URL, authentication and OAuth client fields. Members then open Customize, then Connectors, find the connector (it usually has a "Custom" label) and click Connect to sign in with their own account.

How do you install a local MCP server as a desktop extension?

Desktop extensions are local servers packed into one file, so you never touch JSON. Older guides call them .dxtfiles. Anthropic's desktop extensions post says extensions now use the .mcpb(MCP Bundle) file extension and that "existing .dxt extensions will continue to work" (checked November 2026). The steps, from Anthropic's local server guide (checked November 2026):

1. Go to Settings, then Desktop app, and click Manage next to Extensions.
2. Click Browse extensions, then Install on the one you want.
3. Enter any settings it asks for, such as an API key.

If a vendor sent you a .mcpb file instead, open the same Extensions page, click Advanced settings, find the Extension Developer section, click Install Extension… and select the file. The guide says extensions from the official directory update automatically by default, while a privately distributed file has to be reinstalled by hand when a new version comes out. Fields the extension marks as sensitive are encrypted with your OS secure store: Keychain on macOS, Credential Manager on Windows.

How do you add a local server to claude_desktop_config.json?

This is the original route and still the one most server READMEs describe. It works for anything you can start from a terminal. The steps follow the official MCP guide to local servers (checked November 2026).

1. Click the Claude menu in your system's menu bar (not the settings inside the Claude window) and select Settings…
2. Open the Developer tab and click Edit Config. This creates the file if it does not exist yet, or opens the one you have.
3. Add your server under mcpServers: a name, a command, its args, and optionally env.
4. Save, then completely quit Claude Desktop and restart it. Closing the window is not enough, because the app has to restart to load the new configuration.
5. Click the Add files, connectors, and more indicator in the bottom-left corner of the message box, hover over Connectors, click Manage connectors and select your server to see its tools.

Many older guides tell you to look for a hammer icon at step 5. The current guide uses the Add files, connectors, and more indicator instead, so look there.

macOS    ~/Library/Application Support/Claude/claude_desktop_config.json
Windows  %APPDATA%\Claude\claude_desktop_config.json
Linux    ~/.config/Claude/claude_desktop_config.json

The guide's own example uses the official filesystem server. Replace usernamewith yours. Every folder you list is one Claude can read and modify with your user account's permissions, so list only the ones you mean.

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

To add a second server, add a second key inside mcpServers. Pasting a whole second { "mcpServers": ... } block under the first one makes the file invalid, and then nothing loads.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "my-api": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/username/code/my-api-server/dist/index.js"],
      "env": {
        "MY_API_KEY": "sk-..."
      }
    }
  }
}

Anything in env is plain text in a file on your disk. That is fine for a personal key on your own laptop. For anything shared, an extension or a remote connector with OAuth keeps the secret out of the file.

Can you add a remote server through the config file?

Not as a URL. Every entry in the MCP guide's config is a program to start: a command with args. The common workaround is mcp-remote, an open-source package whose README describes it as a way to "connect an MCP Client that only supports local (stdio) servers to a Remote MCP Server." It runs locally, forwards everything to the URL, and handles the OAuth sign-in in your browser.

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": ["mcp-remote", "https://example.com/mcp"]
    }
  }
}

Per the README (checked November 2026), it needs Node 18 or higher, plain http URLs need the --allow-http flag, which it says is for trusted private networks, and it keeps credentials in ~/.mcp-auth. When a sign-in gets stuck, its fix is rm -rf ~/.mcp-auth and a restart of the client.

For a public server, the custom connector is simpler and works on the web too, so use that. The bridge is worth it when the server is only reachable from your own network, such as a tool on your office VPN, because it connects from your computer instead of from Anthropic's cloud.

Claude Code is a different story. Its MCP docs (checked November 2026) add remote servers directly with one command, and project-scoped servers are saved to a .mcp.json file at the project root.

$ claude mcp add --transport http goro https://mcp.usegoro.ai/mcp

Why is my MCP server not showing up in Claude Desktop?

The MCP guide's troubleshooting list covers most failures. Work through it in order.

1. Restart Claude Desktop completely.Quit from the menu bar or the tray, not the window's close button.
2. Check the file's syntax. One trailing comma or missing brace stops every server in the file from loading. Paste it into any JSON validator.
3. Use absolute paths. The guide says file paths in the config must be valid, absolute and not relative.
4. Run the command by hand. If it errors in a terminal, it will error in Claude too.
5. Read the logs, covered below.

$ npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

In the logs folder, mcp.log holds general logging about MCP connections and connection failures, and each mcp-server-SERVERNAME.logholds that server's stderr output, which is usually where the real error is.

# macOS
$ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Linux
$ tail -n 20 -f ~/.config/Claude/logs/mcp*.log

# Windows
> type "%APPDATA%\Claude\logs\mcp*.log"

Three more causes the logs tend to point at:

• npx or node is not found. The mcp-remote README notes that Claude Desktop uses your system version of Node, even if you have a newer one installed elsewhere. If npx works in your terminal but not in Claude, run which npx and put that full path in command.
• The server prints to stdout. Over stdio, stdout is the protocol channel. The MCP transport specsays a server "MUST NOT write anything to its stdout that is not a valid MCP message", and may log to stderr. A stray console.log breaks the connection.
• Windows logs show ${APPDATA} in an ENOENT error. The MCP guide's fix is to add the expanded value of %APPDATA% to that server's env. It also warns that npx may keep failing until npm is installed globally (npm install -g npm).

"env": {
  "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\"
}

A custom connector that won't connect fails for different reasons: a URL missing its path, a sign-in you closed before it finished, or a server that is not reachable from the public internet. Since connectors can't be edited, remove it, add it again with the exact URL, and complete the sign-in.

A worked example: adding Goro as a custom connector

Goro is a remote MCP server, so it takes the first route and needs no config file. Name the connector goro, paste https://mcp.usegoro.ai/mcp with the /mcp path (the bare host serves the web app, not the MCP endpoint), and choose Sign in now. Goro signs you in with OAuth 2.1 and supports dynamic client registration, so Register automatically works under OAuth client. There is no API key to paste for the MCP connection.

Behind that one connector is a catalog of real-world tools: web and news search, page scraping, social platform data, maps, people and company enrichment, plus image, video and voice generation. Ask Claude to find this week's coverage of a topic and summarise the most useful pages, and it picks the tools, sees the price before each call, and tells you what ran and what it cost. A web search call, for example, starts from $0.0075 per results page of about ten links.

Be honest about whether you need it. If all you want is for Claude to look things up, its built-in web search already does that with nothing to add, and the guide to real-time web data in Claude explains where built-in search stops. A gateway pays off when you would otherwise add a separate server, account and bill for every data source. Running tools needs a plan, from $19 a month with $25 of tool credit included; the details are on the pricing page.