How do I add an HTTP MCP server to Claude Code?

claude mcp add --transport http <name> <url>

Run it in your shell, not inside a claude session.

Answer

Run claude mcp add --transport http <name> <url> in your terminal. The name is yours to pick — it labels the server's tools in Claude's output. For a server that takes a static token, add --header "Authorization: Bearer <token>". The server registers at local scope by default, meaning you only, in this project.

What it does

An MCP server gives Claude tools beyond its built-in set — searching an issue tracker, querying a database, driving a browser. Some run as a program on your machine, others are hosted at a URL. This page is about the second kind.

claude mcp add registers a server. For a hosted one, --transport http says the server lives at a URL rather than running as a local process. The same choice appears as "type": "http" when you write the config by hand.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

The name is arbitrary. Calling it docs would work identically — it is the label on the server's tools in Claude's output and the handle for commands like claude mcp remove.

Run it in your shell, not inside a claude session: you are configuring the server before starting a conversation.

"Registers" is the operative word — the command writes a config entry and nothing more. Nothing is contacted, no process starts. Claude Code connects at the start of each session and keeps the connection for its duration, which is why a broken server shows up when you next run claude, not when you add it, and why editing .mcp.json needs a restart to take effect.

The confirmation tells you both things — the scope it chose and the file it touched:

Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config
File modified: /Users/you/.claude.json

local config here is the scope — you only, this project only — and it is the default.

Servers that run as a process on your machine, rather than answering over HTTP, take a different shape. No --transport, and everything after -- is the command Claude Code runs to start them:

claude mcp add airtable -- npx -y @mcpservers/airtable

The -- matters: without it those arguments are read as flags to claude mcp add.

When to use it

The choice that matters is scope, because it is fixed when you add the server. Changing it later means removing and re-adding.

local (default) — you, this project. Trying a server out.
user — you, every project. A server you always want.
project — everyone who clones the repository. Writes .mcp.json at the

project root, which you commit.

claude mcp add --scope user --transport http docs https://code.claude.com/docs/mcp

Each connected server takes context in every session, since its tool names and instructions load at startup. Removing servers you no longer use gets that back.

Example

Add a server that authenticates with a static token:

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer <token>"

Servers behind OAuth take no token here. Add the URL, then run /mcp in a session, select the server, and choose Authenticate to sign in through the browser.

Share a server with the team:

claude mcp add --scope project --transport http docs https://code.claude.com/docs/mcp

That writes .mcp.json, which you can also author by hand:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Claude Code reads .mcp.json at session start, so restart after editing it. The first time it sees a project-scoped server it asks you to approve — that prompt is what stops a cloned repository from launching processes on your machine unasked.

Common mistakes

Running it inside a session. claude mcp add is a shell command. Inside a session, /mcp is the equivalent surface.

Reading Added as connected. It means the entry was saved. Check with claude mcp list.

Omitting -- before a process server's command. Without it the arguments are parsed as flags to claude mcp add, and the stored command is not what you typed.

Adding at local scope from the wrong directory. Local servers are tied to the project you added them from. In another project they simply are not there.

Editing a config path Claude Code does not read. The real files are ~/.claude.json and <project>/.mcp.json. Paths like ~/.claude/mcp.json are ignored.