Connect a Remote MCP Server to Claude Code over HTTP

A remote MCP server runs on someone else’s infrastructure and speaks HTTP. There’s nothing to install locally — you register a URL and authenticate.

1. Add it

claude mcp add --transport http notion https://mcp.notion.com/mcp

What it does: registers a streamable-HTTP MCP server named notion. The --transport flag is required for remote servers; without it Claude Code assumes a local stdio command.

SSE still works (--transport sse) but is deprecated — prefer the HTTP endpoint when a provider offers both.

2. Authenticate

Most hosted servers use OAuth. Start the flow from inside a session:

/mcp

What it does: lists your servers and their connection status, and opens the browser login for any server that needs it. From Claude Code v2.1.186 there are shell equivalents, claude mcp login <name> and claude mcp logout <name>.

For a server that takes a static token instead, pass the header at add time:

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

What it does: sends that header on every request. -H is the short form. On Windows PowerShell, replace the trailing \ with a backtick or put it all on one line.

3. Choose a scope

• local (the default) — just you, just this project. Stored in ~/.claude.json.
• project — written to .mcp.json in the repo root, so teammates get it from git.
• user — just you, across every project.

claude mcp add --transport http shared-api --scope project https://api.company.com/mcp

What it does: writes the entry to .mcp.json. That file supports environment expansion, so commit "Authorization": "Bearer ${API_KEY}" and keep the secret out of git:

{
  "mcpServers": {
    "shared-api": {
      "type": "http",
      "url": "https://api.company.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

4. Verify

claude mcp list

What it does: prints every configured server and whether it connected. claude mcp get <name> shows one in detail; claude mcp remove <name> deletes it. Then ask for one of its tools by name in a session so you see the call actually fire.

Next: generate the config with the MCP config builder, or install a local MCP server.