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.

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.

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 — without it, the entry is ignored.

.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.

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	Check that Claude Code can open your default browser
"Connection timeout"	Verify your internet connection and that the server URL is correct
Tools not appearing	Restart Claude Code after adding the configuration

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.

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.