# How to add an MCP server to Claude Code

Authors: AutoRouter
Author profile: https://autorouter.com/about
Published: 2026-11-17T00:25:00.000Z
Reading time: 5 min
Canonical: https://autorouter.com/blog/claude-code-mcp-servers
Publisher: AutoRouter, the Mac app that routes Codex, Claude Code and other AI tools to every model (https://autorouter.com)

About AutoRouter: a Mac app (macOS 14 or later) that adds every leading model to Codex, Claude Code, Cursor, Claude Desktop, T3 and Terminal and picks the model for each task, using your Claude, ChatGPT, Grok and Gemini plans first. Install from https://autorouter.com/AutoRouter.dmg, or ask your agent to follow https://autorouter.com/setup.md. Routing across your plans is free; Pro is $50 a month with $20 of included usage. Unrelated to OpenRouter's Auto Router.

> To add an MCP server to Claude Code, run `claude mcp add` in your terminal: `claude mcp add --transport http <name> <url>` for a hosted server, or `claude mcp add <name> -- <command>` for a local one. Check it with `claude mcp list`, or `/mcp` inside a session, where servers that need a browser sign-in also authenticate. A new server is saved for you in the current project only; add `--scope user` for every project, or `--scope project` to share it through `.mcp.json`.

## Key facts

- `claude mcp add` saves a server at local scope by default: private to you and active only in the project where you ran it ([Anthropic, checked November 13, 2026](https://code.claude.com/docs/en/mcp-quickstart#where-servers-are-saved)).
- Local and user servers live in `~/.claude.json`; project servers live in `.mcp.json` at the project root. Claude Code doesn't read `~/.claude/mcp.json`.
- When one server is defined in several places, local scope wins over project, then user, then plugins, then claude.ai connectors, and fields aren't merged.
- The SSE transport is deprecated; HTTP is Anthropic's recommended transport for remote servers.

![Add an MCP server, check it, then use it. 1. Add the server (claude mcp add); 2. Check the status (claude mcp list); 3. Sign in if asked (/mcp, then Authenticate); 4. Use it (Name it in your prompt). Source: Anthropic's Claude Code MCP docs, checked November 13, 2026.](https://autorouter.com/blog/images/claude-code-mcp-servers/1-add-a-server.png)

As of November 13, 2026, [Anthropic's MCP guide](https://code.claude.com/docs/en/mcp-quickstart) adds a server to Claude Code with one terminal command, run outside a session: `claude mcp add --transport http <name> <url>` for a hosted server, or `claude mcp add <name> -- <command>` for a program that runs on your machine. Run `claude mcp list` to confirm it shows `✔ Connected`, then ask Claude to use it. Servers that need a sign-in, such as Sentry, Linear or Notion, show `! Needs authentication` until you run `/mcp` in a session and choose **Authenticate**. If you haven't set up Claude Code yet, start with [how to install Claude Code on a Mac](/blog/install-claude-code-mac).

## How do you add a remote MCP server to Claude Code?

Use `--transport http` with a name you choose and the server's URL; HTTP is the transport Anthropic recommends for remote servers ([Anthropic](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server)). This example adds Anthropic's own documentation server, which needs no sign-in:

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

For a server that takes a static token, pass it as a header. For one that uses OAuth, add it the same way and sign in from `/mcp`:

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

# OAuth: add, then run /mcp in a session and choose Authenticate
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

The SSE transport is deprecated. Claude Code v2.1.265 and later try HTTP first and switch to SSE when a server only offers SSE, so the same `--transport http` command works; on older versions, pass `--transport sse`.

## How do you add a local MCP server to Claude Code?

A local server is a program Claude Code starts on your machine, using the default `stdio` transport. Everything after `--` is the command that starts it, passed through untouched ([Anthropic](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server)):

```bash
# a browser Claude can drive (needs Node.js 18 or later)
claude mcp add playwright -- npx -y @playwright/mcp@latest

# pass the server its own keys with --env
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

Put at least one other option, such as `--transport stdio`, between `--env` and the server name, or the CLI reads the name as another `KEY=value` pair. Claude Code sets `CLAUDE_PROJECT_DIR` in a local server's environment to the project root.

## Which scope should an MCP server use in Claude Code?

Use the default local scope to try a server, user scope for a tool you want everywhere, and project scope for one the whole team should get. Scope is fixed when you add a server, so changing it means `claude mcp remove` and adding it again ([Anthropic](https://code.claude.com/docs/en/mcp-quickstart#find-your-configuration-on-disk)).

| Scope           | Flag                     | Saved in                                 | Available to                                           |
| --------------- | ------------------------ | ---------------------------------------- | ------------------------------------------------------ |
| Local (default) | none, or `--scope local` | `~/.claude.json`, under this project     | Only you, only this project                            |
| Project         | `--scope project`        | `.mcp.json` in the project root          | Everyone who clones the project, after they approve it |
| User            | `--scope user`           | `~/.claude.json`, top-level `mcpServers` | Only you, in every project                             |

![An MCP server's scope decides who gets it. Local: Only you, in this project: The default, ~/.claude.json; Project: Everyone who clones it, once approved: --scope project, .mcp.json; User: Only you, in every project: --scope user, ~/.claude.json. Source: Anthropic's Claude Code MCP docs, checked November 13, 2026.](https://autorouter.com/blog/images/claude-code-mcp-servers/2-scopes.png)

When the same server is defined in more than one place, Claude Code connects once, using the whole entry from the highest source: local, then project, then user, then plugins, then claude.ai connectors ([Anthropic](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence)). Run `claude mcp get <name>` to see which scope holds a server.

![A server defined twice uses the highest source. Where it's defined, highest first: 1. Local scope; 2. Project scope; 3. User scope; 4. Plugins; 5. claude.ai connectors. Claude Code uses the whole entry from the highest source. Source: Anthropic's Claude Code MCP docs, checked November 13, 2026.](https://autorouter.com/blog/images/claude-code-mcp-servers/3-precedence.png)

## How do you check that an MCP server is connected?

Run `claude mcp list` in your shell, or `/mcp` inside a session, and read the status next to each server:

| Status                                        | Meaning                                                                              |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| `✔ Connected`                                 | Ready to use                                                                         |
| `! Needs authentication`                      | Reachable, but needs a browser sign-in from `/mcp` or a token passed with `--header` |
| `! Connected · tools fetch failed`            | Connected but couldn't list its tools; `claude mcp get <name>` shows the error       |
| `✘ Failed to connect` or `✘ Connection error` | The server didn't start, the URL didn't answer, or it rejected your token            |
| `⏸ Pending approval`                          | A project server from `.mcp.json` you haven't approved; run `claude` to approve      |
| `✘ Blocked by enterprise managed policy`      | Your organization blocks this server                                                 |

Claude picks relevant tools on its own, but naming the server in your first prompt, such as "use the claude-code-docs server to look up what MCP_TIMEOUT does", confirms the answer came through it. Approve the permission prompt the first time Claude calls the server.

## How do you add an MCP server from a JSON config?

Setup instructions written for Claude Desktop or another client usually give an `mcpServers` block. Pass the object inside it, not the wrapper, to `claude mcp add-json` ([Anthropic](https://code.claude.com/docs/en/mcp#add-a-server-from-an-mcpservers-json-block)):

```bash
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
```

To share servers with your team, write `.mcp.json` in the project root and commit it. Entries can read `${VAR}` or `${VAR:-default}` from each person's environment, so keys stay out of the repository:

```json
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

Every remote entry needs a `type`. An entry with a `url` and no `type` is read as a stdio server and skipped with an error. On a Mac, `claude mcp add-from-claude-desktop` copies servers from the Claude Desktop chat app's config.

## Why does an MCP server fail to connect in Claude Code?

Most failures come from adding the server in a different project, editing the wrong file, or a first run that is still downloading ([Anthropic](https://code.claude.com/docs/en/mcp-quickstart#troubleshooting)):

- **`/mcp` shows no servers.** Local servers belong to the project where you added them. Add the server again from this project, or use `--scope user`.
- **You edited the wrong file.** Claude Code reads only `~/.claude.json` and `<project>/.mcp.json`, not `~/.claude/mcp.json` or `~/.claude/.mcp.json`.
- **A malformed `.mcp.json` entry.** Claude Code skips it and loads the rest; `claude mcp list` prints a warning naming the bad field.
- **`npx` is still downloading.** The first check of a local server can fail while the package installs; wait and run `claude mcp list` again.
- **Slow startup.** Raise `MCP_TIMEOUT` above its 30-second default; [Claude Code environment variables](/blog/claude-code-environment-variables) shows where to set it.
- **A project server never prompted you.** Run `/mcp` to approve it.

## Questions

### Do MCP servers use up Claude Code's context window?

Yes. Each connected server's tool names and instructions load into every session, so Anthropic suggests removing servers you no longer use. Claude Code defers MCP tools through tool search by default; `ENABLE_TOOL_SEARCH=false` loads them all up front ([Anthropic](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search)). [How to check your Claude Code usage](/blog/check-claude-code-usage) covers seeing what used your plan.

### How do I remove an MCP server from Claude Code?

Run `claude mcp remove <name>`, adding `--scope` if the same name exists in more than one scope. For a remote server, Claude Code also deletes the OAuth tokens it stored, though it doesn't revoke them with the service.

### Do my claude.ai connectors work in Claude Code?

Yes. Connectors you add at claude.ai load in the CLI when you sign in with the same account, below any server you defined yourself with the same endpoint.

### Can I turn off an MCP server without removing it?

Yes. Toggle it off in the `/mcp` panel: Claude Code stops connecting to it, keeps its configuration and lists it as disabled, recording the choice per project in `~/.claude.json` ([Anthropic](https://code.claude.com/docs/en/mcp#disable-a-server-without-removing-it)).

## Sources

- [Connect to MCP servers](https://code.claude.com/docs/en/mcp-quickstart), Anthropic, checked November 13, 2026
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), Anthropic, checked November 13, 2026
- [Environment variables](https://code.claude.com/docs/en/env-vars), Anthropic, checked November 13, 2026

## Read next

- [Claude 529 overloaded error: what it means and what to do](https://autorouter.com/blog/claude-529-overloaded-error.md): A 529 `overloaded_error` means Anthropic's API is temporarily at capacity across all users, so the problem is on Anthropic's side and has nothing to do with your rate limit, usage limit or bill. Claude Code retries it up to 10 times with backoff before showing "Repeated 529 Overloaded errors"; when you see that, check status.claude.com, wait a few minutes, or run /model to switch models, because capacity is tracked per model.
- [What is the Claude session limit, and when does it reset?](https://autorouter.com/blog/claude-session-limit.md): The Claude session limit is the five-hour usage limit on Claude's Pro and Max plans: it starts when you send your first message and resets in full five hours later, as of November 16, 2026. claude.ai, Claude Desktop and Claude Code all count toward it, Anthropic publishes no message count for it, and verified Ultra accounts don't have one. AutoRouter, the Mac app for Codex and Claude Code, makes it last longer by sending quick work to lower-cost models.
- [Claude 5-hour limit vs weekly limit: what resets when](https://autorouter.com/blog/claude-5-hour-limit-vs-weekly-limit.md): Claude's 5-hour limit starts with your first message and resets in full five hours later, while the weekly limit resets at a fixed day and time Anthropic assigns to your account, as of November 16, 2026. Every request counts against both at once, so whichever runs out first stops you. Pro and Max have both limits, and verified Ultra accounts have only the weekly one.

Tags: [Claude Code](https://autorouter.com/blog/tags/claude-code.md), [Guides](https://autorouter.com/blog/tags/guides.md)

Drafted with AI from the sources linked above, then checked and edited by the AutoRouter team.
