# How to add an MCP server to Claude Code

> Run `claude mcp add` from your project's folder. Where the server runs decides the form. A remote server takes `--transport http`, a name and its URL. A local one takes a name, a double dash and the command that starts it. Then run `claude mcp list` to see whether it connected.

Mindket editors · Published 2026-10-19 · Updated 2026-11-03 · https://mindket.com/blog/add-mcp-server-claude-code

## In short

- On a local server's line, never put the server's name straight after `--env`.
- If a change to your team's `.mcp.json` doesn't show up, look for a local-scope entry with the same name.
- Keep `claude mcp get` output out of bug reports when the header holds a real key.
- Run `claude mcp logout` before `claude mcp remove` on any server you signed in to.

## Add a server in four steps

Check the server's README first. It gives either an address, such as `https://mcp.notion.com/mcp`, or a command, such as `npx -y airtable-mcp-server`, that Claude Code will run on your computer.

> **Anthropic's own warning**
>
> Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk.
>
> Anthropic, The warning box in its Claude Code MCP guide, [Claude Code docs: Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) (read 2026-11-03)

1. Pick the server and decide whether you trust it. [Are MCP servers safe?](https://mindket.com/blog/are-mcp-servers-safe) lists what to look at first.
2. Open a terminal in the project that should use it, since a server added without `--scope` belongs to the folder you're in. Then run the add line, for Notion `claude mcp add --transport http notion https://mcp.notion.com/mcp`.
3. Run `claude mcp list` and read the status beside the server. [What to check when a server won't connect](#check-and-fix) shows what each status meant in a real run.
4. Start `claude` and type `/mcp`. A server that needs a login sends you to your browser from there.

## Remote servers: HTTP, a key or a login, and logging out

`http` is Claude Code's name for what the MCP project calls Streamable HTTP. [Anthropic's guide](https://code.claude.com/docs/en/mcp) recommends it for remote servers and marks the older SSE transport deprecated. From v2.1.265 Claude Code falls back to SSE by itself when a server refuses HTTP.

A server with a fixed key takes it in `--header`, quoted, in the form its docs give. One that signs you in with OAuth needs the login from step 4, or `claude mcp login notion` from the shell.

`claude mcp remove` deletes the OAuth tokens Claude Code stored for a server. It doesn't revoke them at the authorization server that issued them. `claude mcp logout notion` does, where that server supports revocation, and so does Clear authentication in the `/mcp` menu. On a server you never logged in to, `logout` just prints `Signed out of "notion"`.

````bash
# A remote server over HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that takes a fixed key in a header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

````

**Three ways a server connects**

| | Remote over HTTP | Remote over SSE | Local over stdio |
| --- | --- | --- | --- |
| Runs on your computer | ✗ No | ✗ No | ✓ Yes |
| Marked deprecated in Anthropic's guide | ✗ No | ✓ Yes | ✗ No |
| What follows the name in the command | The URL | The URL | A double dash, then the start command |

Source: [Claude Code docs: MCP](https://code.claude.com/docs/en/mcp) (read 2026-11-03)

[![Anthropic's post on X: Claude Code can now connect to remote MCP servers, pulling context from your tools into Claude Code with no local setup, posted 18 June 2025](https://mindket.com/blog/shots/x-anthropicai-remote-mcp.webp?v=d8f1269cdf48)](https://x.com/AnthropicAI/status/1935367951542280239)

Anthropic on X, 18 June 2025

> A screenshot of X's own embed of the post, taken on 3 November 2026, with the time in US Pacific time. The video it carries is left out. Select it to open the post on X.

## Local servers and the double dash

Claude Code starts a local server itself and talks to it over standard input and output, the `stdio` transport described in [What is MCP?](https://mindket.com/blog/what-is-mcp). The line you type has two halves, split by `--`. Options before it, such as `--transport`, `--env` and `--scope`, are Claude Code's. Everything after it goes to the server untouched, so a server flag like `--port 8080` stays at the end.

`--env` takes several `KEY=value` pairs, so a server name placed straight after it gets read as one more, and the add stops at once with `Invalid environment variable format: airtable`. Put any other option between the two, as the guide does with `--transport stdio`, or write the name first and `-e` after it, the way `claude mcp add --help` does.

Some READMEs give a JSON block instead of a command. `claude mcp add-json` takes it as it is: pass the object that sits inside `mcpServers`, not the wrapper around it.

````bash
# Claude Code's options, then --, then the server's own command
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# The same, name first, the way claude mcp add --help writes it
claude mcp add airtable -e AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

# A server whose README gives JSON instead of a command
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

````

## Local, project or user: where each scope is stored

The default scope is called local, and the name misleads. Such a server is stored in `~/.claude.json` in your home folder, under the project's path, not in the project's own `.claude/settings.local.json`. That suits a server only you use in one project. One you want everywhere belongs in user scope.

A server the whole team should have goes in project scope. It writes `.mcp.json` at the project root, so the config travels with the repository and nobody has to copy a command. Added that way, Notion produced a file holding only `"type": "http"` and the URL.

Claude Code asks before it uses a server from that file in an interactive session, because a cloned repository can bring its own `.mcp.json`. `claude mcp reset-project-choices` clears your past answers. Keys stay out of the committed file: `.mcp.json` expands `${API_KEY}` from your environment, or uses a default written after `:-`. An unset variable with no default loads as literal text, and `claude mcp list` warns about it.

When a name is defined in two scopes, Claude Code still opens one connection and takes the whole definition from the scope that ranks higher. No fields are merged, so an old local entry hides the team's newer project one completely.

**Which definition wins when a name appears twice**

1. Local scope. Your private entry for this project, stored in `~/.claude.json`.
2. Project scope. The `.mcp.json` file your team commits.
3. User scope. Your entry for all your projects.
4. Plugin-provided servers. Servers that an installed plugin brings with it.
5. claude.ai connectors. The connectors on your claude.ai account come last.

Source: [Claude Code docs: MCP](https://code.claude.com/docs/en/mcp) (read 2026-11-03)

| Scope | Loads in | Shared with your team | Stored in |
| --- | --- | --- | --- |
| Local (default) | The current project | No | `~/.claude.json` |
| Project | The current project | Yes, through version control | `.mcp.json` at the project root |
| User | All your projects | No | `~/.claude.json` |

## What to check when a server won't connect

The output below comes from Claude Code 2.1.314 on Windows 11, on November 3, 2026. Four servers went into an empty folder: Notion's remote server, one with a made-up key at `api.example.com`, a local one pointing at a file that doesn't exist, and Notion again at project scope. All four were removed afterwards.

`claude mcp add` printed a success line for every one. It saved the fake token, showing it as `[REDACTED]`, and never tried the address. `claude mcp list` took about five seconds here. It also checks any claude.ai connectors on your account, so expect lines you never added.

`claude mcp get` showed what the add had hidden: the header, token and all, in plain text.

````text
$ claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
Invalid environment variable format: airtable, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

$ claude mcp list
Checking MCP server health…

notion-team: https://mcp.notion.com/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
notion: https://mcp.notion.com/mcp (HTTP) - ! Needs authentication
secure-api: https://api.example.com/mcp (HTTP) - ✘ Failed to connect — ENOTFOUND: getaddrinfo ENOTFOUND api.example.com
broken: node no-such-server.js - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed

$ claude mcp get secure-api
secure-api:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: ENOTFOUND: getaddrinfo ENOTFOUND api.example.com
  Type: http
  URL: https://api.example.com/mcp
  Headers:
    Authorization: Bearer your-token

````

- `! Needs authentication`: the server answered and wants a login, which is how Notion showed straight after the add. Log in as in step 4.
- `⏸ Pending approval`: a project server nobody has approved yet. Start `claude` in that folder and approve it.
- `✘ Failed to connect` with `ENOTFOUND`: the address doesn't resolve. Look for a typo in the URL.
- `✘ Failed to connect` with `CONNECTION_CLOSED`: a local server that exited. The message doesn't say why, so run the command after the double dash in a terminal and read its own error.

> Everything outside this run comes from Anthropic's Claude Code docs and the MCP project's pages, on the dates in the sources.

## Frequently asked questions

### Can I import the MCP servers I set up in Claude Desktop?

On macOS and in WSL, `claude mcp add-from-claude-desktop` reads Claude Desktop's config file and lets you pick which servers to bring over. It skips a server whose name holds a space or any character other than letters, numbers, hyphens and underscores.

### Does Claude Code load a project's .mcp.json without asking?

In scripts, yes. Nobody can answer the approval prompt in `claude -p` runs or Agent SDK sessions, so project-scoped servers load without it. Starting Claude Code with `--strict-mcp-config` keeps them out, and so does listing a server under `disabledMcpjsonServers`.

### How do I give a slow MCP server more time to start?

Set `MCP_TIMEOUT`, in milliseconds, when you start Claude Code. `MCP_TIMEOUT=10000 claude` gives servers ten seconds to start. Tool calls have a separate limit, `MCP_TOOL_TIMEOUT`.

### Do more MCP servers fill up the context window?

A session starts with only tool names and server instructions, and full tool definitions load when Claude needs them, a feature called tool search. So each extra server costs little up front. Claude Code sets no fixed cap on tools per server, and every definition it does load takes its share of the context window.

### Can Claude Code itself act as an MCP server?

`claude mcp serve` runs Claude Code as a stdio server that Claude Desktop can reach through its config file, exposing only Claude Code's own tools. A silent terminal is normal there, since the server is waiting for a client.

## Sources

- [Claude Code docs: Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) (read 2026-11-03)
- [Claude Code docs: Create a plugin](https://code.claude.com/docs/en/plugins/create) (read 2026-11-02)
- [Model Context Protocol: Architecture overview](https://modelcontextprotocol.io/docs/learn/architecture) (read 2026-11-02)
- [Model Context Protocol: What is MCP?](https://modelcontextprotocol.io/docs/getting-started/intro) (read 2026-11-02)

[Browse MCP servers](https://mindket.com/mcp-servers)