How to add an MCP server to Claude Code
AutoRouter5 min read
Key facts
claude mcp addsaves 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).- Local and user servers live in
~/.claude.json; project servers live in.mcp.jsonat 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.
As of November 13, 2026, Anthropic's MCP guide 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.
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). This example adds Anthropic's own documentation server, which needs no sign-in:
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:
# 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):
# 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).
| 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 |
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). Run claude mcp get <name> to see which scope holds a server.
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):
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:
{
"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):
/mcpshows 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.jsonand<project>/.mcp.json, not~/.claude/mcp.jsonor~/.claude/.mcp.json. - A malformed
.mcp.jsonentry. Claude Code skips it and loads the rest;claude mcp listprints a warning naming the bad field. npxis still downloading. The first check of a local server can fail while the package installs; wait and runclaude mcp listagain.- Slow startup. Raise
MCP_TIMEOUTabove its 30-second default; Claude Code environment variables shows where to set it. - A project server never prompted you. Run
/mcpto 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). How to check your 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).
Sources
- Connect to MCP servers, Anthropic, checked November 13, 2026
- Connect Claude Code to tools via MCP, Anthropic, checked November 13, 2026
- Environment variables, Anthropic, checked November 13, 2026