How to Add a Remote MCP Server to Claude Code

How do I add a remote MCP server to Claude Code?

Run one command:

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

Then run /mcp inside Claude Code to complete the browser OAuth. Add --scope user to the command to make the server available across all your projects rather than just the one you ran it in. That is the entire setup.

Already added the server as a connector at claude.ai? If Claude Code is signed in with that claude.ai account, you may not need to add anything. See "Already connected it in claude.ai?" below.

The scope decision

claude mcp add without a scope flag configures the server for the current project. That is a reasonable default for a project-specific tool and the wrong one for anything you want everywhere.

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

Decide this up front. The symptom of getting it wrong is a server that works in the repo where you set it up and is silently absent everywhere else — which reads as a broken connection rather than a scoping choice.

Already connected it in claude.ai?

If you sign in to Claude Code with a claude.ai account, servers you've added as connectors at claude.ai/customize/connectors are available in Claude Code automatically. They appear in /mcp marked as coming from claude.ai. They don't load when Claude Code is using an API key, apiKeyHelper, or a cloud provider such as Amazon Bedrock; run /status to see which sign-in is active. A server you add with claude mcp add takes precedence over a connector pointing at the same URL.

Connectors you've never signed in to are collapsed behind a Show unused connectors row at the end of the claude.ai section in /mcp, so check there before assuming one is missing. To stop Claude Code from loading claude.ai connectors, set "disableClaudeAiConnectors": true in any Claude Code settings file, or start a single session with ENABLE_CLAUDEAI_MCP_SERVERS=false claude.

Configuring by file instead

Claude Code reads remote MCP servers from a .mcp.json file:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

The "type": "http" line is required. It tells Claude Code this is a remote Streamable HTTP server rather than a local command to run. On current builds the mistake is at least loud: since v2.1.202, an entry with a url but no type is skipped with an explicit message — MCP server "<name>" has a "url" but no "type"; add "type": "http" — where older builds surfaced a confusing command: expected string, received undefined. Claude Code also accepts "type": "streamable-http" as an alias for http, so configs copied from server docs that use the MCP spec's transport name work unmodified.

.mcp.json is the project-scoped file, and it lives in the project directory. Claude Code treats it as team-shared — anyone who clones the project gets the server, and Claude Code prompts for approval before using a project-scoped server it has not seen before.

There is no home-directory .mcp.json. User scope is a different file: ~/.claude.json, written for you by claude mcp add --scope user. Claude Code does not read ~/.mcp.json, ~/.claude/mcp.json, or similar paths, so hand-placing a config there produces a server that silently never appears. Use the command rather than editing ~/.claude.json by hand.

Authorization

The first time Claude Code connects, it opens a browser window for authorization:

1. The browser opens with the server's consent screen
2. Sign in if prompted
3. Review and approve

After approving, Claude Code stores the authorization token and reconnects automatically in future sessions. Run /mcp at any time to check server status or re-run the flow. If the browser doesn't open, copy the link Claude Code shows and open it yourself. You can also sign in from your terminal with claude mcp login <name>.

Verifying

Start a session and ask what tools it has access to. If the server's tools are listed, you are connected.

What usually goes wrong

Problem	Fix
.mcp.json not being picked up	Confirm the file is valid JSON, in the correct directory, and that the entry has "type": "http"
The server works in one project only	It was added at project scope. Re-add with claude mcp add --scope user, which writes it to ~/.claude.json
Added by hand to ~/.mcp.json and nothing appears	Claude Code does not read that path. Run claude mcp add --scope user instead
A project-scoped server never loads	Claude Code asks for approval before using a project's .mcp.json servers. Run /mcp and approve it
Browser doesn't open for auth	Copy the link Claude Code shows and open it yourself, or run claude mcp login <name> from your terminal
"Connection timeout"	Verify your internet connection and that the server URL is correct
Tools not appearing	Restart Claude Code after adding the configuration
A connector from claude.ai isn't in /mcp	Run /status. Connectors from claude.ai load only under a claude.ai account sign-in, not an API key, apiKeyHelper, or cloud provider. Switch with /login, or add the server with claude mcp add. Also check the Show unused connectors row
/mcp lists a claude.ai connector as hidden	You also added that server in Claude Code, which takes precedence over a connector at the same URL. /mcp shows how to remove the duplicate if you'd rather use the connector

Running a different model underneath

Claude Code can be pointed at other providers' Anthropic-compatible endpoints, which makes it a common harness for open models. This does not affect your MCP setup at all: MCP lives in the harness, so a server configured here keeps working when the model underneath changes, and the model's API key never authorizes the server.

One exception: servers Claude Code inherits from your claude.ai connectors don't load once ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is set, and that is how these endpoints are configured. If you plan to switch models this way, add the server with claude mcp add so it stays connected.

If you are going that route, the GLM guide covers the environment block in detail.

A worked example

With a real server — Tempreon, a hosted MCP server that gives your coding sessions a persistent memory of your architecture decisions and conventions:

claude mcp add --transport http --scope user tempreon https://api.tempreon.com/functions/v1/tempreon-mcp/mcp

Then /mcp and approve in the browser. The account-holder walkthrough is in the Claude Code setup doc.