Claude Code MCP configuration: .mcp.json, scopes and troubleshooting

The .mcp.json format

A project file with one remote server and one local server looks like this:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

The type field is required whenever url is present. A url with no type is reported as a configuration error (the message tells you to add "type": "http", or sse or ws), which replaced an older and much less helpful complaint about a missing command. The value streamable-http is accepted as an alias for http. A remote server that needs a fixed credential takes a headers object; a local one takes command, args and env. The optional timeout is a per-tool-call limit in milliseconds. WebSocket servers can only be declared in a file or through claude mcp add-json; the --transport flag does not accept ws.

The claude mcp add command with --scope project writes this file for you, so hand-editing is only needed for fields the command does not expose or when you prefer to review the change in a pull request.

Keeping secrets out of the file

Because .mcp.json is meant to be committed, tokens should not be typed into it. Claude Code expands environment variables in command, args, env, url and headers: ${VAR} takes the variable's value, and ${VAR:-default} falls back to the default when it is unset.

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

A referenced variable that is unset and has no default does not stop the server from loading; the literal ${API_KEY} text is sent as is, and claude mcp list prints a warning. That warning is the first thing to look for when a server connects but every call is rejected as unauthorized.

For a server that supports OAuth there is nothing to hide at all: leave the entry as just type and url, and each user signs in once from /mcp. The token is stored per user, outside the repository, and removed again by claude mcp remove.

Approval, precedence and managed servers

The first time Claude Code sees a server in a project's .mcp.json, an interactive session asks whether to use it; non-interactive runs (claude -p, the Agent SDK, cloud sessions) load it without asking. The decision is remembered per project; claude mcp reset-project-choices forgets it so you can re-approve after a change.

When one name is defined in several places, the order is local scope, then project scope, then user scope, then servers that plugins provide, then connectors from claude.ai. The whole winning entry is used. Organizations can push a fixed server list through a managed configuration file or the managedMcpServers setting (Claude Code 2.1.259 or later); those rank above every user-level scope, and a managed file that claims exclusive control makes claude mcp add refuse with a message saying enterprise configuration is active. Allow and deny lists (allowedMcpServers, deniedMcpServers) can also restrict which URLs or commands users may add, and a deny always wins.

Reading the status output

claude mcp list reports each server as connected, needs authentication, failed to connect, pending approval, rejected through disabledMcpjsonServers, or disabled for this project. A few less obvious warnings it prints are worth knowing: hidden leading or trailing whitespace in a value (a pasted token that ended with a newline), the same name pointing at different endpoints in two scopes, and a handful of reserved names that cannot be used for your own servers. WebSocket servers do not show in the list at all; check them with claude mcp get <name> or /mcp.

Common failures and their fixes

1. A remote server shows "needs authentication" or answers 401 or 403. Open /mcp, select the server and complete the browser sign-in, or run claude mcp login <name>. If the server uses a static token, check the header value and the warning about unexpanded variables.
2. A local server fails to connect at startup. Run its command by hand in the same shell to see the real error; the usual causes are a missing runtime, a package that needs installing, or a required environment variable. Slow-starting servers hit the startup limit, which MCP_TIMEOUT raises in milliseconds, for example MCP_TIMEOUT=10000 claude.
3. The server connects but a tool returns a truncated result. Tool output is capped at 25,000 tokens by default, with a warning from 10,000; MAX_MCP_OUTPUT_TOKENS raises the cap.
4. Tools seem missing from the conversation. Claude Code defers tool definitions until they are needed to keep context small, so only names and server instructions load at the start; the assistant still finds them when a request matches. Set "alwaysLoad": true on a server entry if you want its full definitions present from the first turn.
5. A remote server drops mid-session. Claude Code retries a dropped connection up to five times with increasing delays and a failed first HTTP connection up to three times, but not for authentication errors and not for local servers, so an auth failure will not fix itself.

Testing the configuration against a live service

The fastest way to validate a project's .mcp.json is a server whose answers you can check independently. With { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } committed and each developer signed in once through /mcp, a request such as "run an HTTP check on our staging URL from Europe and Asia" has to come back with real status codes and response times from HostTracker's checkpoints, which either proves the file is read correctly or narrows the fault to sign-in. The companion guide, how to add an MCP server to Claude Code, covers the command-line route and the scopes in more detail.