Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

The most common MCP question that is not really about MCP goes like this. You added a server to the repo's .mcp.json, it works when you start Claude Code at the root, and then a teammate opens a terminal in packages/api, runs claude, and the server is nowhere to be found. Or the opposite: the server appears, but with a “pending approval” label, in a headless run that nobody can approve. Or .mcp.json is there, committed, correct, and /mcp lists a different definition of the same server from somewhere else entirely.

All three are the same subject: what project scope means, where Claude Code reads .mcp.json from, and how that interacts with subfolders, monorepos and the approval step. This post is only about that. For the broader picture of the three scopes, secrets and a sane team setup, start with our MCP servers guide; for keeping big servers from eating your context, see MCP context usage.

What .mcp.json is, in one paragraph

Claude Code stores MCP servers in three scopes. Local scope is the default and lives in ~/.claude.json, keyed to the current project, so it is yours alone. User scope also lives in ~/.claude.json but applies to every project you open. Project scope is the one that travels with the code: a .mcp.json file at the project's root directory, which the docs tell you to check into version control so everyone on the team gets the same tools. The file is a plain JSON object with an mcpServers map:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@example/db-mcp"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

You do not have to write it by hand. The same CLI that adds local servers writes to .mcp.json when you pass the scope:

claude mcp add --transport http shared-server --scope project https://example.com/mcp

Subfolders: the root is where you start Claude, not where the repo is

Here is the part that trips up monorepos. “Project root” in the project-scope definition is the directory Claude Code treats as the project for this session, which is the directory you launched it from. It is not the git root, and in current versions Claude Code does not walk up the tree looking for a .mcp.json in a parent folder the way a build tool might look for a config file. Start claude in packages/api and the project is packages/api; a .mcp.json two levels up is simply not in play.

That is also why the local-scope entries in ~/.claude.json are per project directory: a server you added with the default scope while sitting at the repo root is attached to the root path, and opening a subfolder gives you a different project with its own, empty, local list. If the behaviour feels inconsistent, check what claude mcp list says from each directory before changing anything; it reports which servers are loaded and warns about unresolved variables, and /mcp inside a session shows ${VAR} references by name (v2.1.268 or later).

There are four reasonable ways to set up a monorepo, in rough order of preference:

1. Start Claude at the root and widen access, not the other way round. Launch from the repo root, where the shared .mcp.json lives, and point Claude at the package you are working in. Claude can read and edit anywhere under the root, so most of the time nothing more is needed; if you also want a directory outside the root in play, --add-dir (or permissions.additionalDirectories in settings) adds it without changing which .mcp.json is read.
2. A .mcp.json per package. If people genuinely work from inside packages/web and packages/api and the two need different servers, give each its own file. The cost is duplication of anything shared; keep the shared entries identical and let reviewers notice drift.
3. Pass the file explicitly with --mcp-config. claude --mcp-config ../../.mcp.json loads a specific file regardless of where you started. Combined with --strict-mcp-config, Claude Code uses only the servers in the files you passed and ignores every other scope, which makes it the right tool for CI and scripted runs where you want no surprises.
4. Move the shared servers to user scope. A server everyone on the team uses in every repo, such as a company docs server, arguably does not belong in any single project. User scope follows you into every directory. It is the least discoverable option for new teammates, which is the trade-off.

The same server in two scopes

When a server name appears in more than one place, Claude Code connects once and uses the highest-precedence definition: local beats project, project beats user, user beats plugin-provided servers, which beat claude.ai connectors. Managed managedMcpServers entries from an administrator outrank all of them (v2.1.259 or later). The entire entry is taken from the winning source; fields are not merged. So if your .mcp.json says url: https://staging... and a stale local entry with the same name says production, you are talking to production and the committed file is being ignored. The fix is claude mcp remove <name> for the local one, after checking claude mcp get <name> to see which definition is active.

Environment variables, and the ones that are deliberately empty

Because .mcp.json is shared, anything secret or machine-specific has to come from the environment. The file supports ${VAR} and ${VAR:-default} in command, args, env, url and headers. An unset variable with no default does not stop the file loading: Claude Code warns about the missing variable in claude mcp list and uses the literal ${VAR} text, which is why a server can appear “configured” and still fail to connect.

Two details are specific to the shared file. First, a handful of credential variables, including ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and AWS_BEARER_TOKEN_BEDROCK, read as empty when referenced in a remote server's url or headers, and a :-default on them is ignored. That is on purpose: a committed .mcp.json must not be able to send your Anthropic credentials to a server somebody added in a pull request. Second, CLAUDE_PROJECT_DIR in a project-scoped file needs a default, as in ${CLAUDE_PROJECT_DIR:-.}, when used in command or args. Plugin configs can use it bare; project files cannot.

The approval step, and why headless runs skip it

A .mcp.json is code that someone else may have committed, and an MCP server can run commands on your machine, so Claude Code prompts for approval in interactive sessions before using project-scoped servers. Your answer is remembered per project; claude mcp reset-project-choices clears it so you are asked again, which is the fix when a server you rejected weeks ago is now one you want.

The prompt cannot appear where there is nobody to answer it. In claude -p runs, Agent SDK sessions and cloud sessions, Claude Code loads project-scoped servers without asking. The same applies to a session started in bypassPermissions mode when skipDangerousModePermissionPrompt is set. If that is not what you want for a particular server, you have three documented options:

• Add it to disabledMcpjsonServers in a settings file; that blocks it in every permission mode, and an entry in any settings file is enough.
• Exclude project settings with --setting-sources, or the SDK's settingSources option.
• Start with --strict-mcp-config and pass only the servers you trust via --mcp-config.

Going the other way, teams that want no prompt at all can set enableAllProjectMcpServers: true, or list the approved names in enabledMcpjsonServers. Note the trust rule: those two keys, when committed in a project's .claude/settings.json, are ignored in a folder you have not marked as trusted, while disabledMcpjsonServers still applies. Approvals from ~/.claude/settings.json, managed settings and --settings still count in an untrusted folder; an untracked .claude/settings.local.json only counts in a trusted one (v2.1.207 or later). The claude mcp list labels tell you which case you are in: Pending approval (run claude to approve) versus Rejected (see disabledMcpjsonServers in settings).

One easy confusion: disabledMcpServers and enabledMcpServers, without the json, are different keys. They are per-project toggles stored in ~/.claude.json for turning servers on and off locally, not the approval list for the shared file.

A checklist for the next time a server goes missing

1. Which directory did you start claude in? That is the project. Run claude mcp list from there.
2. Is the server labelled pending approval, rejected, or listed with a missing-variable warning? Each has a different fix above.
3. Does claude mcp get <name> show the definition you expect, or a local or user-scope copy with the same name?
4. Is this a headless or CI run? Then there was no prompt, and the server either loaded silently or was blocked by disabledMcpjsonServers.
5. Still stuck? claude --mcp-config ./.mcp.json --strict-mcp-config removes every other variable from the experiment.

Most of the time the answer is step one. The repo is not the project; the folder you are standing in is.