# Connect a Remote MCP Server to Claude Code over HTTP

> Add a hosted MCP server with claude mcp add --transport http, authenticate with OAuth or a header, and pick the right scope for your team.

- Canonical: https://guides-ai.pages.dev/guides/claude-code-remote-mcp-servers/
- Plate 05.08 · Topic: MCP (https://guides-ai.pages.dev/topics/mcp/)
- Published: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

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

```bash
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:

```text
/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:

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

```bash
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:

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

## 4. Verify

```bash
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](/tools/mcp-config/), or
[install a local MCP server](/guides/install-mcp-server-claude-code/).