Add a Remote MCP Server to Claude Code: claude mcp add and Fixes

One command does it:

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

Then run /mcp inside Claude Code to sign in, if the server asks for it [1]. That is the whole setup for a server on the public internet. The rest of this page covers the choices around it (scope, headers, sign-in) and what to do when claude mcp list says it failed to connect.

Everything below is checked against Anthropic's Claude Code MCP documentation on 12 October 2026 [1].

TL;DR:

• Use --transport http. SSE is deprecated, and Claude Code falls back to it on its own when a server does not accept HTTP (from v2.1.265) [1].
• The default scope is local: only you, only this project. Use --scope project to share it through .mcp.json, or --scope user for every project [1].
• Sign in with /mcp or claude mcp login <name>. If you see "does not support dynamic client registration", the server needs a client ID you register yourself [1].
• Claude Code connects from your machine. A server that works here can still fail in Claude.ai or ChatGPT, which connect from their own clouds.

Add the server

The basic form is claude mcp add --transport http <name> <url> [1]. The name is yours to choose. The URL is the MCP endpoint itself, usually ending in /mcp, not the product's homepage or docs page.

For a server that takes an API key rather than a sign-in, pass it as a header:

claude mcp add --transport http my-server https://mcp.example.com/mcp \
  --header "Authorization: Bearer your-token"

To check it worked:

claude mcp list
claude mcp get my-server

claude mcp list shows each server as connected, needing authentication, or failed to connect [1]. claude mcp remove my-server takes it out again, and for a remote server that also deletes the tokens and client registration Claude Code stored for it [1].

Pick a scope

Source: [1].

A project server is committed to git, so never put a token in it as plain text. Use an environment variable instead, which Claude Code expands in url and headers [1]:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_SERVER_KEY}"
      }
    }
  }
}

One exception catches people out. Claude Code deliberately reads its own and your cloud provider's credential variables as empty in a remote server's url and headers, so a project file cannot send them to a server it names. Bearer ${ANTHROPIC_AUTH_TOKEN} arrives as Bearer with nothing after it, and the server answers 401 [1]. Use a variable named for the server, like MY_SERVER_KEY above.

Sign in to a server that needs it

Run /mcp in Claude Code, pick the server, and finish the sign-in in your browser. From the shell, claude mcp login my-server does the same, and prints the URL instead when there is no local browser, such as over SSH [1]. claude mcp logout my-server clears it.

Before any of that can happen, Claude Code has to register itself with the server's authorization server. It does that automatically in two ways: Dynamic Client Registration, or a Client ID Metadata Document [1]. When the server offers neither, you get:

Incompatible auth server: does not support dynamic client registration

That is not a bug in your setup. It means the server only accepts clients registered in advance. Register an app in the server's developer portal with the redirect URI http://localhost:8080/callback, then add the server with your credentials [1]:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

--client-secret prompts for the secret with masked input, and it is stored in the system keychain or a credentials file, not in your config. Leave it off for a public client that has no secret [1].

How often will you hit this? Rarely. We read the authorization metadata of 169 real servers that ask for credentials, taken from our registry census on 9 October 2026. 162 offered Dynamic Client Registration and 33 accepted metadata documents, and only 6 offered neither [2]. Those 6 are the servers that need --client-id. The background on both methods is in Dynamic Client Registration.

When it fails to connect

For what each HTTP status and error code means on the server side, see MCP server errors and MCP server connection failed.

Works in Claude Code, fails everywhere else

A local Claude Code session makes its requests from your computer. So it can reach things nothing else can: localhost, a server on your VPN, a staging host behind your firewall. That is useful while you build, and it hides a problem the moment you hand the URL to anyone else.

Claude.ai, Claude Desktop's custom connectors and ChatGPT all call your server from their own cloud, not from your machine. A server that is green in claude mcp list can still be unreachable to all three. If you are publishing a server for other people, the question is whether a stranger on the internet gets an MCP answer, and Claude Code cannot tell you that.

Our MCP connection test can. It calls your server from our network, runs the handshake and tools/list, and reports what came back with a dated URL you can share. The same setup for the cloud clients is in add a remote MCP server to Claude Desktop and add an MCP server to ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. Connect Claude Code to tools via MCP, Claude Code docs
2. Dynamic Client Registration, MCP Hunter glossary