Claude Code MCP: add servers, scopes and config file paths

In brief

To use MCP in Claude Code, run claude mcp add --transport http <name> <url> for a hosted server or claude mcp add <name> -- <command> for a local one. As of November 2026 the server saves to ~/.claude.json by default, or to .mcp.json in your repo when you add --scope project.

Whizi doesn’t connect to Claude Code.

How do you add an MCP server to Claude Code?

You add one with claude mcp add, typed in your terminal before you start a session. Anthropic's reference, read on 15 November 2026, gives four ways in. Pick the one that matches where the server runs. These are copied from the docs, so swap in your own name, URL and key.

A terracotta power strip with three different sockets on a charcoal plinth, a glass cable plugged into the middle socket, and a small rainbow glass cube resting beside it under a warm rim light.
ServerCommand from the docs
Hosted, no keyclaude mcp add --transport http notion https://mcp.notion.com/mcp
Hosted, with a tokenclaude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"
Local, started by Claude Codeclaude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server
You already have the JSONclaude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

The steps, from the MCP quickstart and reference:

  1. Install Claude Code and sign in. Anthropic says most surfaces need a Claude subscription or an Anthropic Console account, and the terminal CLI also supports third-party providers.
  2. Open a normal terminal in your project. Don't type the command inside a claude session.
  3. Run one of the commands above. A line starting Added means the settings were written. It does not mean the server works.
  4. Run claude mcp list. A healthy server shows ✔ Connected. A local npx server can show ✘ Failed to connect on the first check while it downloads, so wait a moment and run it again.
  5. Start claude and ask for the server by name, such as "Use the notion server to find the Q3 plan". Approve the permission prompt the first time.
  6. Inside a session, /mcp shows every server and its status. To drop a server, run claude mcp remove <name>.

Two details trip people up. For a local server, the -- separates Claude Code's own options from the command that starts the server, and the docs say everything after it "is passed to the server untouched." And --env takes several KEY=value pairs, so if the server name comes right after it, the CLI reads the name as another pair. Put --transport stdio between them, as the Airtable example does.

Which transport? The docs put it plainly: "HTTP servers are the recommended option for connecting to remote MCP servers." SSE still works, but "The SSE (Server-Sent Events) transport is deprecated." Add an SSE-only endpoint with the same --transport http command and Claude Code tries HTTP first, then switches to SSE on v2.1.265 or later. WebSocket servers can't use the flag at all. They go in .mcp.json or through add-json with "type":"ws".

Once a server is added, a handful of clocks decide how long a call can run. The chart shows the defaults in Anthropic's reference on 15 November 2026, on a log axis because they span almost three orders of magnitude. Section 4 has the output limits and the variables that change them.

A silent MCP tool call is cut off after 5 minutes on a remote server, 30 on a local one
1 min10 min100 min1,000 minLong calls move to a background taskIdle timeout, HTTP and SSE serversIdle timeout, local stdio serversDefault hard cap per call (about 28 hours)

Where does Claude Code save MCP servers, and which scope should you use?

It saves them to one of two files, chosen by the --scope flag, and the default is local. That gives the page its odd fact: three scopes, two files, because local and user scope both write to ~/.claude.json. Only project scope puts anything in your repository. This table is compiled from the docs on 15 November 2026.

ScopeFlagLoads inShared with the teamWhere it is stored
Local (default)--scope localCurrent project onlyNo~/.claude.json, under that project's path
Project--scope projectCurrent project onlyYes, through version control.mcp.json in the project root
User--scope userAll your projectsNo~/.claude.json, under the top-level mcpServers key

On Windows, ~/.claude.json is %USERPROFILE%\.claude.json, typically C:\Users\YourName\.claude.json. If you set CLAUDE_CONFIG_DIR, Claude Code reads .claude.json from inside that folder instead. Don't confuse local scope with local settings. The docs warn that the term "differs from general local settings," which live in .claude/settings.local.json inside the project.

Use local for a personal experiment or a server with a key you don't want committed. Use user for a tool you want everywhere, such as claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic. Use project for a server the whole team should have: claude mcp add --transport http shared-server --scope project https://example.com/mcp writes this .mcp.json, which you commit.

{"mcpServers": {"shared-server": {"type": "http", "url": "https://example.com/mcp"}}}

A scope is fixed when you add the server. To move one, remove it and add it again at the new scope. If the same name exists in several places, Claude Code connects once and uses the highest-ranked entry whole, with no merging of fields. The order is local, then project, then user, then plugin servers, then claude.ai connectors.

Teammates who clone the repo get a prompt to approve each .mcp.json server before it runs. Run claude mcp reset-project-choices to wipe those answers. A shared file can also keep secrets out of git: .mcp.json accepts ${VAR} and ${VAR:-default} in command, args, env, url and headers, so "Authorization": "Bearer ${API_KEY}" pulls the token from each person's environment.

How do you sign in to, check and manage MCP servers?

For a hosted server that wants OAuth, add it normally, open /mcp in a session and follow the browser steps. Or skip the session and run claude mcp login sentry in your shell, after adding it with claude mcp add --transport http sentry https://mcp.sentry.dev/mcp. Tokens are stored and refreshed for you. claude mcp logout <name> clears them. On a remote machine, add --no-browser and paste the redirect URL back.

The management commands are short. claude mcp list shows every server with a status. claude mcp get <name> shows one server, including which scope holds it. claude mcp remove <name> deletes it and its stored OAuth tokens. Inside Claude Code, /mcp does the same job in a panel, and /mcp reconnect all retries every failed server on v2.1.284 or later.

The statuses to know: ✔ Connected, ! Needs authentication, ✘ Failed to connect, and for project servers a pending approval that clears when you run claude and say yes. Anthropic's warning sits at the top of its reference: "Verify you trust each server before connecting it." A server that fetches outside content can carry a prompt injection into your session, and what is MCP explains why the approval step is the whole security model.

You can also reuse servers you already set up elsewhere. Run claude mcp add-from-claude-desktop to import from Claude Desktop, which works on macOS and Windows Subsystem for Linux only. If you sign in to Claude Code with a claude.ai account, connectors you added at claude.ai/customize/connectors show up in /mcp with no command. On Team and Enterprise plans, only admins can add them.

What limits and timeouts does Claude Code put on MCP tools?

Claude Code cuts off a silent tool call after 5 minutes on a remote server and 30 minutes on a local one, as the chart in section 1 shows. A server that sends progress notifications keeps the call alive past that idle window. The per-server timeout field is different: it is a hard wall-clock limit that progress notifications don't extend.

Output has its own limits. Claude Code warns when one tool result passes 10,000 tokens and stops the result at 25,000 by default. A bigger successful result is saved to a file under ~/.claude/projects/ and the chat gets the path, so Claude reads it only if it needs to. Text over 50,000 characters is saved the same way whatever its token count. Raise the token limit with export MAX_MCP_OUTPUT_TOKENS=50000. The warning threshold is fixed.

Three environment variables tune the clocks. MCP_TIMEOUT=10000 claude sets a 10-second startup timeout. MCP_TOOL_TIMEOUT caps a call across all servers, and a per-server timeout field in milliseconds does it for one. CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes the idle window, and 0 turns the check off. Values under 1000 in the per-server field are ignored.

More servers cost less context than you'd expect. With tool search, Claude Code loads only tool names at session start and fetches full definitions when Claude needs them. That is the default on Claude Opus 4, Sonnet 4, Haiku 4.5 and later models. ENABLE_TOOL_SEARCH=false claude loads everything up front, and auto:5 loads tools until they would use 5% of the context window. A dropped remote server gets five reconnect attempts, starting at a one-second delay and doubling each time.

Which plans can use MCP in Claude Code, and what if you only want Claude's answers?

Claude Code itself needs an account, and the MCP pages name no separate MCP plan. Anthropic's overview says most surfaces "require a Claude subscription or Anthropic Console account." So whichever plan runs Claude Code is the one that runs a server, and Claude Code pricing has the plan prices and Claude Code usage limits covers the caps that decide how much a server's output can cost you. One catch: claude.ai connectors load only when you sign in with a claude.ai subscription. An ANTHROPIC_API_KEY, a Bedrock login or claude setup-token leaves them out, and /status shows which method is active.

You can also go the other way and make Claude Code the server. claude mcp serve starts it over standard input and output, and a Claude Desktop config with "command": "claude" and "args": ["mcp", "serve"] connects to it.

Whizi, which publishes this page, doesn't run Claude Code and doesn't expose MCP servers or a developer API, so this guide won't help you there. What it covers is the reader who hit the paid-plan wall and mostly wants Claude's answers in a chat. Whizi Pro puts Claude, GPT and Gemini in one app, with a first week of $1.99. The free plan gives 10 messages a day on Whizi AI, Auto and Claude Haiku 5.5, with no card. For terminal work on a repo, Claude Code stays the tool.

Why won't my Claude Code MCP server connect?

Most failures are one of nine messages, and the docs name the cause of each. The table pairs what you see with the fix, as read on 15 November 2026.

What you seeCauseFix
MCP server sentry already exists in local configSame name, same scopePick a new name or run claude mcp remove sentry first
has a "url" but no "type"A JSON entry with a URL and no type is read as stdioAdd "type": "http", "sse" or "ws"
✘ Failed to connect, right after adding an npx serverThe package is still downloadingWait and run claude mcp list again
⏸ Pending approvalA .mcp.json server you haven't approvedRun claude and approve it
Failed with a 401 or 403 and an Authorization header setThe token is wrong. Claude Code won't fall back to OAuthFix the token, or delete the header to use OAuth
Server receives "Bearer " with nothing after it${ANTHROPIC_AUTH_TOKEN}-style variables read as empty in remote headersCopy the value into a variable with your own name
needs you to sign in again (run /mcp to re-authenticate)The token expired or was revokedOpen /mcp, pick the server, sign in
Connector missing from /mcpAn API key or cloud login is activeCheck /status, unset it, run /login
Leading or trailing whitespace in: headers.AuthorizationA pasted token carried a newlineAdd the server again with the clean value

One trap is worth a line. The docs say claude mcp add "saves the configuration without validating credentials," so a placeholder token is accepted today and the server fails later. Always run claude mcp list after adding.

Workflow checklist
  • Run claude mcp add in a normal terminal, then confirm with claude mcp list rather than trusting the Added line
  • Choose the scope on purpose: local is the default, --scope user is for every project, --scope project writes .mcp.json for the team
  • Keep secrets out of a committed .mcp.json by writing ${VAR} references instead of tokens
  • Prefer --transport http over SSE, and use -- before any local command that has its own flags
  • Raise MAX_MCP_OUTPUT_TOKENS only when a tool's results are truncated; the default is 25,000 tokens
  • Add only servers you trust, since a server that reads outside text can carry a prompt injection
Common questions

Frequently asked questions

Where is the Claude Code MCP config file?

There are two. Local and user servers live in ~/.claude.json, which on Windows is %USERPROFILE%\.claude.json, or inside CLAUDE_CONFIG_DIR if you set it. Project servers live in .mcp.json at your project root. Run claude mcp get <name> to see which scope holds a given server.

How do I add an MCP server to Claude Code for all my projects?

Add --scope user to the command, for example claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic. The default scope is local, which loads only in the project where you ran the command. A scope can't be edited later, so remove the server and add it again to change it.

Can Claude Code act as an MCP server?

Yes. claude mcp serve starts Claude Code as a stdio MCP server and prints nothing while it waits for a client. In Claude Desktop, add an entry with "command": "claude" and "args": ["mcp", "serve"] to claude_desktop_config.json.

Does Whizi support MCP servers?

No. Whizi is a chat workspace with built-in tools such as web search, and it doesn't run Claude Code or expose MCP servers or a developer API. Use Claude Code or another MCP-capable client for that, and see what is MCP for how the protocol works.