Claude Code MCP Config File Location and Settings Explained

You run claude mcp add, the server connects, and a week later a teammate asks where that setting actually went. Claude Code does not keep MCP configuration in one tidy file. It spreads it across ~/.claude.json, a project-level .mcp.json, several settings.json files and, in company setups, a managed policy file. Edit the wrong one and nothing changes. Edit the right one without knowing the precedence order and a different definition quietly wins.

This article maps each location on macOS, Windows and Linux, shows which definition wins when two files name the same server, and lists the commands, environment variables and timeout settings that matter day to day. Every path and flag below was checked against the current Claude Code documentation, so you can copy them as written.

Where the Files Actually Live

Claude Code has three scopes for servers you add yourself, plus an organization layer that sits on top of them. The scope decides two things: which projects load the server, and whether the definition travels with the repository.

Three Scopes, Three Locations

Local scope is the default. A server added without --scope loads only in the project where you ran the command and stays private to you. Claude Code writes it into ~/.claude.json under that project's path:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Copy Prompt

Project scope writes a .mcp.json file at the repository root. It is built to be committed, so everyone on the team gets the same tools. User scope keeps the definition in the same ~/.claude.json file, outside any project path, so every project you open sees it.

💡 Quick rule: a private or experimental server belongs in local scope. A shared team tool belongs in project scope. A personal tool you want in every repository belongs in user scope.

Paths on Windows, macOS, and Linux

On Windows, ~ means %USERPROFILE%, so the user-level file is %USERPROFILE%\.claude.json. The .mcp.json file is relative to your project root on every system. Only the managed file changes by operating system, because it sits in a system-wide directory that an administrator controls.

If you want the home-directory files somewhere else, set CLAUDE_CONFIG_DIR. Claude Code then stores your settings, session history and plugins there instead of in ~/.claude.

The Local Scope Naming Trap

The word "local" means two different things in Claude Code. MCP local scope lives in ~/.claude.json in your home directory. General local settings live in .claude/settings.local.json inside the project. Searching settings.local.json for an MCP server you added with the default scope finds nothing, and that single mix-up accounts for a large share of "where did my server go" questions.

💡 Server definitions go in .mcp.json or ~/.claude.json, and the claude mcp commands write them for you. The settings.json files hold approvals, allowlists and denylists, which come up again below.

Inside the .mcp.json File

When you add a server with --scope project, Claude Code creates or updates this file automatically. You can also write it by hand and commit it. It has one wrapper field, mcpServers, and one entry per server.

A Working Example

{
  "mcpServers": {
    "docs-search": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      }
    },
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/files-server"],
      "env": {
        "ROOT_DIR": "${PROJECT_ROOT:-.}"
      },
      "timeout": 600000
    }
  }
}

Copy Prompt

The type field accepts http, sse, stdio and ws. The name streamable-http works as an alias for http, which means a snippet copied from a server's own documentation usually loads without edits. A stdio entry needs command and optional args and env. A remote entry needs url and optional headers.

One detail trips people up when they paste config from another client such as Claude Desktop. The same mcpServers wrapper works inside .mcp.json, but claude mcp add-json expects only the object inside the wrapper, not the wrapper itself.

Environment Variables Instead of Secrets

Because .mcp.json is committed, tokens never belong in it. Claude Code expands two forms of variable reference:

• ${VAR} expands to the value of VAR.
• ${VAR:-default} expands to VAR when it is set, and to default otherwise.

Expansion works in command, args, env values, url and headers values. If a variable is unset and has no default, the file still loads. Claude Code prints a missing-variable warning for that server in claude mcp list and uses the raw ${VAR} text as it is, which is why a server can fail with a baffling literal string in its header.

There is also a safety rule. In the url and headers of a remote server, credential-bearing variables such as ANTHROPIC_AUTH_TOKEN and NPM_TOKEN read as empty. That stops a cloned repository from sending your Claude Code or cloud credentials to a server it names.

💡 Export the real token in your shell profile or secret manager, and commit only the ${SERVICE_TOKEN} reference.

Adding Servers From the Terminal

You rarely need to touch the JSON yourself. The claude mcp add family writes to the right file for the scope you choose, and it is the safest way to avoid a typo that breaks ~/.claude.json.

HTTP and Stdio Commands

# Remote HTTP server with a bearer token
claude mcp add --transport http docs-search https://example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server. The -- separates Claude's options from the server command
claude mcp add --transport stdio --env SERVICE_TOKEN=abc123 local-files -- npx -y @example/files-server

# Shared with the team and written to .mcp.json
claude mcp add --scope project --transport http docs-search https://example.com/mcp

Copy Prompt

For stdio servers, the double dash is not optional. Everything before it belongs to Claude Code, and everything after it is the command that launches the server.

Remote servers use http or sse, while a local process uses stdio. WebSocket servers have no dedicated flag, so you add them through JSON:

claude mcp add-json events-server '{"type":"ws","url":"wss://example.com/events"}'

Copy Prompt

Servers that use OAuth take --client-id, --client-secret and --callback-port, and claude mcp login <name> signs in from the command line.

Checking What Connected

Three commands answer most questions: claude mcp list shows every server, claude mcp get <name> shows one, and claude mcp remove <name> deletes one. Inside a session, /mcp opens the same view and lets you authenticate.

Which Definition Wins

When the same server appears in more than one place, Claude Code connects to it once and uses the highest-precedence source.

Precedence, Highest First

1. A server from the managedMcpServers managed setting (Claude Code v2.1.259 or later)
2. Local scope
3. Project scope
4. User scope
5. Plugin-provided servers
6. claude.ai connectors

Claude Code matches duplicates across the three scopes by name. It matches plugins and connectors by endpoint, so one that points at the same URL or command as an enabled server above it counts as a duplicate.

The detail that matters most: the entire entry from the winning source is used, and fields are not merged. Say docs-search exists in user scope with an Authorization header and again in project scope without one. The project definition wins whole, and the header from the user entry never appears.

Approval Prompts for Shared Servers

For security reasons, Claude Code asks for approval in interactive sessions before it uses a project-scoped server from .mcp.json. Three settings control the outcome:

{
  "enabledMcpjsonServers": ["docs-search"],
  "disabledMcpjsonServers": ["local-files"]
}

Copy Prompt

Made a choice you regret? claude mcp reset-project-choices clears the approvals.

Since v2.1.196, a cloned repository cannot approve its own servers. Approvals committed to the project's .claude/settings.json are ignored in a folder you have not trusted, and the server stays at ⏸ Pending approval. Approvals from your user settings file, ~/.claude/settings.json, from managed settings and from --settings still apply. An untracked .claude/settings.local.json works too, once the folder is trusted.

Non-interactive runs such as claude -p load project servers without prompting, unless you start them with --strict-mcp-config. That flag tells Claude Code to use only the servers passed with --mcp-config.

💡 Review .mcp.json in a pull request the way you would review a script. A stdio entry runs a command on every teammate's machine.

Settings Files and Policy Controls

Settings Files, Highest Priority First

A setting at a higher level overrides the same setting lower down. ~/.claude.json is a separate file that Claude Code writes for itself. It holds your sign-in session, your MCP server configurations, per-project state such as trust decisions, and the global options that /config changes. You do not need to edit it by hand.

Allowlists and Managed Servers

Teams that need control have four tools, ordered here from lightest to strictest:

• disabledMcpServers lets a user opt out of specific user, plugin, managed or claude.ai servers.
• allowedMcpServers and deniedMcpServers filter by server name or by a serverUrl pattern.
• managedMcpServers is a managed setting that provides servers to everyone alongside the ones users add.
• managed-mcp.json deploys a fixed set of servers from the system paths shown earlier.

Deploying managed-mcp.json has a side effect worth knowing. By default it suppresses the claude.ai connectors Claude Code fetches itself. To load them next to your managed servers, set "allowAllClaudeAiMcps": true in a managed settings source. Setting the ENABLE_CLAUDEAI_MCP_SERVERS=false environment variable turns the connectors off for a single machine.

Timeouts and Output Limits

Startup and Tool Timeouts

Two timers matter, and they are easy to confuse.

The per-server timeout overrides the MCP_TOOL_TIMEOUT environment variable for that server only. Values below 1000 are ignored and fall through to MCP_TOOL_TIMEOUT. When that variable is unset, the default is about 28 hours. Progress notifications from the server do not extend the limit.

Large Tool Output

Claude Code warns when any MCP tool returns more than 10,000 tokens and caps output at 25,000 tokens by default. Raise the cap with MAX_MCP_OUTPUT_TOKENS=50000 claude, or make it permanent through the env field of a settings file:

{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

Copy Prompt

Fixing Broken Config Fast

Symptoms and Fixes

If ~/.claude.json ever fails to parse, Claude Code copies the broken file to ~/.claude/backups/.claude.json.corrupted.<timestamp> and asks whether to exit and fix it by hand or reset to the default configuration. To bring back your earlier state, copy one of the five most recent .claude.json.backup.<timestamp> files from ~/.claude/backups/ into place.

💡 Hand edits to ~/.claude.json are rarely worth the risk. Prefer claude mcp add, add-json and remove, and keep a copy of the file before any manual change.

Make Your Own Visuals With Picasso IA

Config work ends the moment a server shows ✔ Connected, but documenting it takes longer than doing it. README screenshots, onboarding diagrams and short clips of a terminal session slow a team down. That is where Picasso IA helps, with text, image and video models in one place.

Use Claude Sonnet 5 on PicassoIA

Claude Sonnet 5 is a language model built for coding and tool-use tasks, which makes it handy for drafting a config entry or reviewing one before you commit it. The model page exposes these inputs:

1. Open the model page and paste your request into Prompt. For example: "Convert this claude mcp add command into a .mcp.json entry whose Authorization header reads from an environment variable."
2. Set Effort. The default is low, which turns thinking off for the fastest and cheapest reply. Choose high or max when a bug spans several files.
3. Add a System Prompt such as "Reply with valid JSON only, no commentary" and reuse it across the session.
4. Leave Max Tokens alone unless the output is long. The default is 8,192.
5. Attach an image if you have a screenshot of an error. The model reads it as context.
6. Run it, then verify. Paste the result into .mcp.json and run claude mcp get <name> to confirm the server connected.

💡 Treat generated config as a draft. Paths, flags and settings change between releases, so check each one against the official documentation.

For the visual side, text-to-image models such as PicassoIA Image and Seedream 5 Pro can produce header art for a docs page or a changelog post. To adjust a picture you already have, open PicassoIA Image Editor Pro. For motion, PicassoIA Video and Seedance 2.5 Lite turn a prompt or a still image into a short clip.

PicassoIA also offers MCP connections for its image and video models, managed from your account at picassoia.com/en/mcp/accounts. Once you have the connection details, an HTTP server goes in with the same claude mcp add --transport http pattern shown above.

Pick a model, write a prompt, and generate your first header image or clip for your next README. Try a few variations, compare them side by side, and keep the one that fits. Everything is waiting at picassoia.com/en/all-models.