How to add an MCP server to Claude: Desktop, Claude Code and claude.ai

Claude can use tools from MCP (Model Context Protocol) servers in three places, and each one is set up differently:

• Claude Desktop runs local servers on your computer, configured in claude_desktop_config.json or installed as extensions.
• claude.ai, Claude Desktop and the mobile apps connect to remote servers as custom connectors, added in settings.
• Claude Code adds both kinds with the claude mcp add command.

This guide follows Anthropic's and the MCP project's documentation as of October 2026. Menu names in the Claude apps change often, so if a label differs, look for the closest match.

Where is claude_desktop_config.json?

The easiest way to open it: click the Claude menu in your system's menu bar (not the settings inside the Claude window), choose Settings…, open the Developer tab and click Edit Config. That creates the file if it doesn't exist yet.

Add a local MCP server to Claude Desktop

A local server is a program Claude Desktop starts on your machine and talks to over stdio. Add it under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/Desktop"]
    },
    "my-api": {
      "command": "node",
      "args": ["/Users/alice/servers/my-api/index.js"],
      "env": {"API_KEY": "your-key"}
    }
  }
}

• command and args are what you would type in a terminal to start the server. Use absolute paths.
• env passes environment variables, such as API keys, to that server only.

Then quit Claude Desktop completely and start it again; closing the window isn't enough. To check that the server loaded, click the button at the bottom left of the message box, then Connectors, and look for it in the list.

Or install it as an extension

Servers packaged as MCP bundles (.mcpb files, previously .dxt) install without editing JSON: double-click the file, drag it into the Claude Desktop window, or install it from the Extensions section of Claude Desktop's settings. A bundle is a zip of the server and a manifest.json, and Claude Desktop ships its own Node.js to run it.

Add a remote MCP server to claude.ai (custom connector)

A remote server runs on the internet, so the same connector works on the web, in Claude Desktop and on mobile. Custom connectors are available on Free, Pro, Max, Team and Enterprise plans; on Free you can add one.

Pro and Max:

1. Open Customize and then Connectors.
2. Choose Add, then Add custom connector.
3. Enter a name and the server URL, for example https://mcp.example.com/mcp.
4. If the server uses OAuth, Claude opens the authorization server's sign-in page when you connect.

Team and Enterprise: an Owner adds the connector once under Organization settings and Connectors. Members then find it under Customize and Connectors, marked Custom, and click Connect to sign in with their own account.

Use it in a chat: select + in the message box, then Connectors, and turn the connector on for that conversation. When Claude wants to call a tool, it asks you to Allow once or Always allow; you can set each tool to Always allow, Needs approval or Blocked in the connector's settings.

What the remote server needs

• A public HTTPS URL. Claude connects from Anthropic's cloud, not from your computer, so localhost and hosts that resolve to private IP addresses are rejected. If you allowlist by IP, Anthropic's outbound range is 160.79.104.0/21.
• Streamable HTTP transport. The older HTTP+SSE transport still works but is being deprecated.
• Limits to design for: results of about 150,000 characters and 240 seconds per tool call on claude.ai and Desktop.

You can rename a connector or change its URL later, but not its authentication settings: to change those, remove it and add it again.

Add an MCP server to Claude Code

Claude Code uses a command instead of a settings page:

# A remote server over HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A local server over stdio; everything after -- is the command that starts it
claude mcp add --env API_KEY=your-key --transport stdio my-api -- node /path/to/index.js

# List, inspect and remove
claude mcp list
claude mcp get my-api
claude mcp remove my-api

Add --scope to choose where the server is saved:

In .mcp.json you can write ${API_KEY} or ${API_KEY:-default} so secrets come from environment variables instead of the repository. Run /mcp inside Claude Code to sign in to servers that use OAuth. If a server is slow to start, raise the startup timeout with MCP_TIMEOUT; if its output gets cut off, raise MAX_MCP_OUTPUT_TOKENS (the default limit is 25,000 tokens). On macOS and WSL, claude mcp add-from-claude-desktop copies the servers you set up in Claude Desktop.

How OAuth sign-in works for remote servers

When a remote server needs to know who the user is, Claude acts as the OAuth client, following the MCP authorization specification (versions 2025-03-26, 2025-06-18 and 2025-11-25):

1. Discovery. The MCP server returns 401 and publishes protected resource metadata (RFC 9728) naming its authorization server, whose metadata lists the endpoints.
2. Client identity. Claude prefers a client ID metadata document (CIMD), which needs no registration, but uses it only if the authorization server advertises client_id_metadata_document_supported: true and none in token_endpoint_auth_methods_supported. Otherwise it falls back to dynamic client registration (DCR). Some organizations can also enter their own client ID and secret.
3. Authorization code flow with PKCE (S256), sending the MCP server's URL in the resource parameter (RFC 8707). The redirect URI for claude.ai, Desktop and mobile is https://claude.ai/api/mcp/auth_callback; Claude Code uses a loopback address, http://localhost:<port>/callback.
4. Tool calls carry the access token, which the MCP server checks for issuer and audience.

Machine-to-machine (client_credentials) tokens aren't supported for connectors.

Troubleshooting

• The server doesn't appear in Claude Desktop. Check the JSON is valid, the paths are absolute, and you fully quit and reopened the app. Logs are in ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows: mcp.log for connections, and mcp-server-<name>.log for each server's error output.
• "Couldn't reach the MCP server". The URL must be public HTTPS, must not redirect to another host, and must not resolve to a private address; check that a firewall or WAF isn't blocking Anthropic's IP range.
• "Authorization with the MCP server failed". Usually the authorization server doesn't offer CIMD or DCR, doesn't allow the callback URL above, or issues tokens whose audience doesn't match the MCP server.

Securing your own MCP server with Casdoor

If you are building the MCP server, you need an OAuth authorization server for step 2 and 3 above. Casdoor is an open-source identity provider that works as one: it publishes the discovery metadata, supports both DCR and CIMD (it advertises CIMD and the none client authentication method when dynamic registration is turned on), PKCE and the resource parameter, and lets users sign in with passwords, passkeys, MFA, social login or their company's SSO. See the Casdoor guide for Claude Desktop, the ChatGPT version of this guide, and OAuth for AI agents. Run it yourself for free, or as a managed instance on Casdoor Cloud, from $24/month billed yearly.

FAQ

Can I put a remote server URL in claude_desktop_config.json? The documented way to add a remote server is a custom connector. claude_desktop_config.json is for local servers that Claude Desktop starts as programs. Community tools such as mcp-remote wrap a remote server as a local command, but they aren't part of Anthropic's documentation.

Do servers in claude_desktop_config.json work on claude.ai? No. Local servers run only in Claude Desktop on the machine where they are configured. To use a server on the web and on mobile, host it remotely and add it as a connector.

Does Claude support MCP prompts and resources? Connectors support tools, prompts and resources, with text and image results. Resource subscriptions and sampling aren't supported.