How to add an MCP server to Claude Code

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.

1. Pick the server and decide whether you trust it. 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 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 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".

# 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"

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?. 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.

# 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.

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.

$ 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

Sources

1. Claude Code docs: Connect Claude Code to tools via MCP (read November 3, 2026)https://code.claude.com/docs/en/mcp
2. Claude Code docs: Create a plugin (read November 2, 2026)https://code.claude.com/docs/en/plugins/create
3. Model Context Protocol: Architecture overview (read November 2, 2026)https://modelcontextprotocol.io/docs/learn/architecture
4. Model Context Protocol: What is MCP? (read November 2, 2026)https://modelcontextprotocol.io/docs/getting-started/intro