Claude Code MCP server setup: add, scope, share, debug

Claude Code MCP server setup in practice: add a server with claude mcp add, verify it with claude mcp list, choose a scope, share .mcp.json and fix errors.

10 October 2026

A Claude Code MCP server setup comes down to three commands: claude mcp add to register a server, claude mcp list to check it, and a scope choice that decides who gets it. This guide follows the official MCP quickstart and the MCP reference, both checked on 2026-10-10. CLI output and version requirements change between releases, so confirm against the current docs.

What an MCP server gives Claude Code

The Model Context Protocol lets Claude Code use tools beyond its built-in set, such as searching an issue tracker, querying a database or driving a browser. Those tools come from MCP servers, which run on your machine or as hosted services, per the quickstart.

One cost to keep in mind: each connected server takes space in Claude’s context window, because its tool names and server instructions load into every session. The quickstart suggests removing servers you no longer use.

MCP is one extension point among several. For deterministic automation around tool calls, see Claude Code hooks examples; for reusable instructions, see Claude Code skills.

Add and verify your first server

Run this in your terminal, not inside a claude session. It adds the hosted Claude Code docs server, which needs no sign-in (quickstart):

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude-code-docs is a name you choose; Claude Code uses it to label the server’s tools and in commands like claude mcp remove. Then check the connection:

claude mcp list

The statuses you will meet, from the quickstart:

Start claude and ask it to use the server by name, for example “Use the claude-code-docs server to look up what MCP_TIMEOUT does”. Naming the server guarantees the answer goes through it rather than another tool. Inside a session, /mcp shows and manages servers you have already added.

HTTP, SSE or stdio: pick the transport

The reference covers the transports. Choose by what the server’s documentation gives you:

• A URL (https://…): a remote server. Use --transport http.
• A launch command (npx -y …): a local stdio process.
• An sse endpoint: the SSE transport is documented as deprecated; use HTTP where available. Claude Code tries HTTP first and switches to SSE when the server does not accept it, which requires v2.1.265 or later. On earlier versions, pass --transport sse.
• A wss:// endpoint: WebSocket, configured in .mcp.json or with claude mcp add-json, since --transport does not accept ws.

A stdio server needs the -- separator, which splits Claude’s own flags from the server command (quickstart):

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

Pass environment variables with --env after the server name and before --. The Playwright example needs Node.js 18 or later because it runs through npx.

Choose a scope: local, project or user

claude mcp add writes to one of three scopes, per the quickstart:

Pick --scope user for a personal server you want everywhere, and --scope project for one the team should share. A server’s scope is fixed when you add it, so to change it, remove the entry (claude mcp remove <name> --scope local) and re-add it at the new scope.

If the same name is defined in several places, Claude Code connects once, using the highest-precedence definition, in this order: local, project, user, plugin-provided servers, claude.ai connectors. The whole entry from that source is used; fields are not merged (scope precedence). claude mcp list warns when one name has different endpoints in different scopes.

Share servers with your team through .mcp.json

Project scope writes .mcp.json, which you commit. A hand-written file looks like this (quickstart):

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Keep secrets out of the file. .mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url and headers (reference):

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Three caveats from the reference:

• An unset variable with no default does not stop the config loading. Claude Code warns in claude mcp list and uses the literal ${VAR} text.
• In a remote server’s url and headers, credential variables such as ANTHROPIC_API_KEY or NPM_TOKEN read as empty, so the server gets Bearer and usually answers 401. Copy the value into a variable with your own name.
• A url entry with no type is a configuration error, because an entry without type is read as stdio.

On first sight of a project-scoped server, Claude Code asks for approval, so a cloned repository cannot launch processes without consent. To reset those choices, run claude mcp reset-project-choices.

Servers that need sign-in

Hosted services such as Sentry, Linear and Notion put their MCP servers behind OAuth. Add the URL, then authenticate in a session (quickstart):

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp list then shows ! Needs authentication, which is expected. In a session, run /mcp, select the server and choose Authenticate; your browser opens the sign-in page. Servers that use a static token instead take it at add time with --header "Authorization: Bearer <token>"; the reference has a GitHub example.

Troubleshoot a server that will not connect

Start with claude mcp list or /mcp, then match the symptom (troubleshooting):

• No MCP servers configured. You may have added a local-scope server from a different project, or edited the wrong path. Claude Code reads only ~/.claude.json and <project>/.mcp.json; paths like ~/.claude/mcp.json are ignored. Re-add the server from the right project or with --scope user.
• Failed to connect. Read the detail on the status line or in claude mcp get <name>. For HTTP servers, curl -I <url> tells you more: 404 or 405 means the server is up, 401 or 403 means you need to authenticate. For stdio servers, run the configured command in your terminal. If claude mcp get shows a different command than you typed, you probably omitted --.
• Connection error. Claude Code adds no detail here, so go straight to the curl and command checks.
• Timed out at startup. The default startup timeout is 30 seconds. Raise it with MCP_TIMEOUT=60000 claude (milliseconds).
• Server already exists. Remove it first, or pick another name. If it exists in several scopes, add --scope to remove.
• Connects but no tools. The server is probably missing an environment variable such as an API key. Pass --env KEY=value or use the env field in .mcp.json.
• Edits to .mcp.json ignored. Restart the session, check claude mcp list for a parse warning (malformed entries are skipped), and reset project approvals if you rejected the prompt earlier.

Failure detail on Failed to connect needs v2.1.219 or later; earlier versions show the bare status.

What to change in your setup

Items 1 to 4 restate the docs; items 5 and 6 are our own judgment.

1. Add one server and confirm ✔ Connected in claude mcp list before adding more.
2. Use --scope user for servers only you need, and --scope project for ones the team shares.
3. Commit .mcp.json for shared servers, and reference secrets as ${VAR} rather than pasting them.
4. Use your own variable names for tokens, since covered credential names read as empty in remote url and headers.
5. Remove servers you do not use, to free context window space.
6. Keep a short troubleshooting note in your repo pointing at claude mcp list, claude mcp get <name> and /mcp.