Claude Code MCP: add, scope, check and remove servers

Updated October 1, 2026 · 8 min read

Claude Code connects to MCP servers with claude mcp add: --transport http and a URL for a remote server, or a command after -- for a local stdio server. Servers save at local scope by default (you, this project only). --scope user adds one for every project, and --scope project writes a .mcp.json your team can commit. Check them with /mcp inside a session and remove them with claude mcp remove <name>.

The flags below come from the --help output of Claude Code 2.1.274, the version on the machine we wrote this on, checked against Anthropic’s MCP docs on 1 October 2026.

What does MCP do in Claude Code?

MCP (Model Context Protocol) is the standard way for an agent to use outside tools. Claude Code is the client, and each server you add gives Claude a set of tools: a database, Sentry errors, a browser, a wiki.

Anthropic’s features overview splits the work this way: CLAUDE.md is context that loads every session, skills are knowledge loaded on demand, and MCP connects Claude to external services. A skill or a line in CLAUDE.md can tell Claude how to use a server well.

Idle servers cost little context: with tool search, on by default, only tool names and server instructions load at session start.

How do I add an MCP server to Claude Code?

Run claude mcp add in your terminal, not inside a session. The name is yours to choose, and Claude Code labels the server’s tools with it.

A remote server over HTTP, the transport the docs recommend for hosted services:

claude mcp add --transport http notion https://mcp.notion.com/mcp

The same, with a static token instead of OAuth:

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

A local stdio server, which Claude Code starts as a process on your machine. Everything after -- is the command that runs the server, passed through untouched:

claude mcp add playwright -- npx -y @playwright/mcp@latest

claude mcp add --env AIRTABLE_API_KEY=your-key --transport stdio airtable \
  -- npx -y airtable-mcp-server

Two traps. Without --, Claude Code parses the server’s flags as its own. And --env takes several KEY=value pairs, so a server name straight after it is read as another pair and rejected; put another option, such as --transport stdio, in between.

If a server’s instructions only give an mcpServers JSON block written for another client, pass the object inside it to add-json:

claude mcp add-json example '{"type":"http","url":"https://mcp.example.com/mcp"}'

An entry with a url but no type fails, because Claude Code reads a missing type as stdio. streamable-http is accepted as an alias for http.

A successful add prints Added .... That means the configuration was written, not that the server works, so check it next.

Which flags does claude mcp add take?

From claude mcp add --help on 2.1.274:

The other subcommands are add-json, add-from-claude-desktop (macOS and WSL), list, get, remove, login, logout, reset-project-choices and serve. WebSocket servers need add-json with "type": "ws". SSE is deprecated; from v2.1.265 an http server that only speaks SSE is switched over automatically.

For scripts and CI, claude itself takes --mcp-config <configs...> to load servers from JSON files or strings, and --strict-mcp-config to use only those and ignore every other MCP configuration.

Local, project or user scope: which should I use?

Use local for experiments and your own credentials, user for tools you want everywhere, and project for servers the whole team should get.

When one name is defined in several places, Claude Code connects once, in this order of precedence: local, project, user, plugin servers, then claude.ai connectors. The whole entry comes from the winner; fields are not merged. To change a server’s scope, remove it and add it again.

How do I share MCP servers with my team in .mcp.json?

claude mcp add --scope project creates or updates .mcp.json, or you can write it by hand:

{
  "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}" }
    }
  }
}

${VAR} and ${VAR:-default} expand in command, args, env, url and headers, so each person keeps their key in their own environment and nothing secret goes into git. In a remote server’s url and headers, Claude Code’s own credentials, such as ANTHROPIC_API_KEY, read as empty, so a repository cannot send them to a server it names.

In an interactive session, Claude Code asks you to approve each project server the first time, so a cloned repository cannot start processes without your consent. claude mcp reset-project-choices clears your answers. In claude -p runs there is no prompt and project servers load without asking; --strict-mcp-config or the disabledMcpjsonServers setting keeps them out.

How do I check which MCP servers are connected?

Inside a session, /mcp lists every server with its status and tool count, and lets you authenticate, reconnect or disable one. From the shell, claude mcp list health-checks each server and claude mcp get <name> shows one, including its scope (we describe these two from the docs and did not run them for this guide).

The statuses you will see:

• ✔ Connected: ready to use.
• ! Needs authentication: reachable, but needs a browser sign-in or a token.
• ✘ Failed to connect: the server did not start or did not answer. claude mcp get <name> shows the HTTP status and the server’s error on an Issue: line.
• ⏸ Pending approval: a .mcp.json server you have not approved yet.
• ⊘ Disabled for this project: switched off in /mcp, still configured.

Claude Code reads MCP configuration when a session starts, so start a new session after adding a server or editing .mcp.json. To see how much context each server’s tools take, run /context all; the Claude Code context window guide covers the rest of that budget.

How do I sign in to an MCP server that uses OAuth?

Add the server without a header, then run /mcp, select it and choose Authenticate, and approve in your browser. From a shell, claude mcp login <name> runs the same flow; --no-browser prints the URL instead, for SSH sessions, and you paste the redirect URL back. claude mcp logout <name> clears the stored credentials.

If a server rejects a header you configured, Claude Code reports a failed connection rather than falling back to OAuth, so fix the token or remove the header.

claude -p has no /mcp panel, so it cannot run an OAuth flow. Sign in from an interactive session first, or use a server that takes a token in a header.

How do I remove or disable an MCP server?

claude mcp remove notion
claude mcp remove notion --scope local

Without --scope, remove deletes the server from whichever scope holds it; if the name is in several, it says so and you pass --scope. Removing a remote server also deletes the OAuth tokens Claude Code stored for it. To pause a server without losing its configuration, toggle it off in /mcp. The choice is recorded per project.

Why is my MCP server not working in Claude Code?

• /mcp shows no servers. You added it from another project (local scope is tied to the repository root, or the exact directory outside git), or you edited the wrong file. Claude Code reads ~/.claude.json and <project>/.mcp.json, not ~/.claude/mcp.json or ~/.claude/.mcp.json.
• Failed to connect. Read the Issue: line. Run curl -I <url>: a 404 or 405 still means the server is up (many endpoints only answer POST), a 401 or 403 means you need to authenticate, and no response means a URL or network problem. For stdio, run the command yourself; if claude mcp get shows a different command, you probably left out --.
• A whitespace warning. Usually a pasted token with a trailing newline. Claude Code uses values as written, so edit them.
• Startup timeout. The default is 30 seconds, and a first npx download can take longer. MCP_TIMEOUT=60000 claude raises it (milliseconds).
• Connected, but no tools. Usually a missing environment variable such as an API key. Pass it with --env.
• Tool output cut off. Claude Code warns above 10,000 tokens and caps MCP output at 25,000 by default. MAX_MCP_OUTPUT_TOKENS=50000 raises the cap.

Connect Claude Code to a shared wiki

Most MCP servers let Claude Code act on something. A wiki server gives it somewhere to keep what it learns, beyond one session and one machine, where CLAUDE.md and auto memory stop (the Claude Code memory guide explains both).

Dexio is a hosted wiki for AI agents. Claude Code and your other agents read, search, write and link markdown pages over MCP, and you see what they know as a page graph at https://app.dexio.wiki. It is open source (AGPL-3.0) and free for one person.

Its MCP server is remote Streamable HTTP at https://app.dexio.wiki/mcp, with an API key in a header, so it is one user-scope command:

claude mcp add --transport http --scope user dexio https://app.dexio.wiki/mcp \
  --header "Authorization: Bearer dxk_..."

Because the key travels in a header, Claude Code has no OAuth step to finish, so it works headless; we have connected Claude Code to Dexio this way without an interactive session. In a new session, /mcp shows Dexio as connected.

You do not need to fetch the key yourself. Send Claude Code this:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

It replies with a link and a code. You sign in (or create a free account) in your browser and click Allow access, and Claude Code adds the server itself. Every agent connects to the same address and names itself on each change, so page_history shows which agent wrote what. The same wiki works in Codex and Cursor, and the LLM wiki post explains the pattern behind it.

FAQ

What is the difference between Claude Code and MCP? Claude Code is the agent. MCP is the protocol it uses to reach outside tools: Claude Code is the client, and each server is a source of tools.

Where does Claude Code store MCP servers? Local and user scope in ~/.claude.json (%USERPROFILE%\.claude.json on Windows, or inside CLAUDE_CONFIG_DIR if you set it). Project scope in .mcp.json at the project root.

Can Claude Code be an MCP server itself? Yes. claude mcp serve starts it as a stdio server that another client, such as Claude Desktop, can launch. It prints nothing when it starts, which is normal.

Sources

• https://code.claude.com/docs/en/mcp
• https://code.claude.com/docs/en/mcp-quickstart
• https://code.claude.com/docs/en/features-overview
• https://dexio.wiki/agents.md
• https://dexio.wiki/docs/