Claude Code MCP: how to add a server, which scope to use, and examples that work

Add an MCP server to Claude Code with claude mcp add: a URL for a remote server, or a command after -- for a local one. It goes into your local scope unless you say otherwise; --scope project writes it to .mcp.json for the whole team, --scope user makes it available in every project. /mcp inside a session shows what connected and signs you in.

Add a remote MCP server (HTTP)

Most hosted servers speak HTTP. Give the transport, a name and the URL:

A server that takes a token instead gets it in a header — GitHub's, for one:

claude mcp add --transport http github \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

SSE servers still work — --transport sse — but Anthropic marks SSE deprecated, and since 2.1.265 an http server that only speaks SSE falls back to it on its own. For OAuth, /mcp opens the browser; tokens are stored and refreshed for you, and Clear authentication in the same menu revokes them. Over SSH, claude mcp login <name> --no-browser.

Add a local MCP server (stdio)

A local server is a program Claude Code starts. Everything after -- is the command and its arguments, passed through untouched, so a server's own --port is not read as Claude Code's:

A server that needs an API key in its environment:

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

A read-only Postgres connection through DBHub:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

--env takes several values, so a name right after it is read as one more variable. Put another option, such as --transport stdio, between the two, as above.

Claude Code MCP scopes: local, project or user

Local scope is the default; local and user scope are stored in ~/.claude.json, project scope in .mcp.json at the project root.

Claude Code asks before it uses servers from a project's .mcp.json in an interactive session; claude mcp reset-project-choices asks again. Runs with -p and the SDK load them without asking — so read a repository's .mcp.json before you script against it.

.mcp.json and environment variables

A project file is plain JSON, safe to commit as long as the secrets stay in variables. ${VAR} and ${VAR:-default} expand in command, args, env, url and headers:

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

An unset variable with no default stays as written, with a warning. To add an entry without editing a file, claude mcp add-json <name> '<json>' takes the same JSON.

Manage your servers

Limits and context cost

• Output: a tool result over 10,000 tokens shows a warning; the default maximum is 25,000. Raise it with MAX_MCP_OUTPUT_TOKENS=50000.
• Start-up: MCP_TIMEOUT sets how long a server may take to start, 30 seconds by default; MCP_TIMEOUT=10000 claude sets 10.
• Tool search is on by default: only tool names and server instructions load at the start, and full definitions come in when needed, so ten servers do not fill your context. ENABLE_TOOL_SEARCH=false loads everything up front; "alwaysLoad": true exempts one server.
• Resources and prompts: reference a resource as @github:issue://123; a server's prompts appear as commands, such as /mcp__github__pr_review 456.

A company can fix the list in managed-mcp.json or allow and deny servers by URL or command; see Anthropic's managed MCP page.

What your MCP servers actually do

claude mcp list says a server is connected. It does not say whether Claude calls it, how often, or what those calls return. Each call is a tool named mcp__<server>__<tool> in the session's transcript.

On my machine, from 18 July to 4 October 2026, MCP tools made 6,554 of 97,002 tool calls in Claude Code — 7% — and one browser server made most of them. Read from Caprock's export, main threads and subagents together.

Caprock reads those calls from every session's transcript:

• Live: the Home screen describes a session calling one as "<tool> via <server>" while it happens.
• Kind of work: turns spent on MCP tools are a kind of work of their own, beside running commands, editing and reading, with what they cost.
• By tool: each MCP tool is its own row, shown as server·tool; opening one groups its calls by action.

Caprock adds no server to your setup on its own. It ships an optional, read-only one, caprock mcp, that lets Claude ask Caprock about earlier sessions, costs and CI: claude mcp add caprock -- caprock mcp. It records every session on the machine whether or not it started it; free, open source, nothing leaves your machine. Install Caprock.