Beta
Download

How to add an MCP server to Claude Code

AutoRouter5 min read

Key facts

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

ScopeFlagSaved inAvailable to
Local (default)none, or --scope local~/.claude.json, under this projectOnly you, only this project
Project--scope project.mcp.json in the project rootEveryone who clones the project, after they approve it
User--scope user~/.claude.json, top-level mcpServersOnly 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:

StatusMeaning
✔ ConnectedReady to use
! Needs authenticationReachable, but needs a browser sign-in from /mcp or a token passed with --header
! Connected · tools fetch failedConnected but couldn't list its tools; claude mcp get <name> shows the error
✘ Failed to connect or ✘ Connection errorThe server didn't start, the URL didn't answer, or it rejected your token
⏸ Pending approvalA project server from .mcp.json you haven't approved; run claude to approve
✘ Blocked by enterprise managed policyYour 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):

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