skip to content

A teammate commits a `.mcp.json` to a repository — what does Claude Code do before connecting its servers on a fresh clone, and when does that check not apply?

level: seniorimportance: should knowfreq 7%

answer

  1. a cloned repo launching processes
  2. first-use prompt, per server
  3. the repo can't approve itself
  4. headless runs can't ask
  5. rejection beats any approval

basics

~20 s

An interactive session asks you to approve each .mcp.json server on first use, and approvals committed in the repository are ignored until you trust the folder. claude -p, SDK and cloud sessions cannot ask, so they load project servers unprompted.

solid answer

~40 s

Project servers can launch processes or send requests on your behalf, so Claude Code prompts in an interactive session before using each `.mcp.json` server; your answer is written to `.claude/settings.local.json` as `enabledMcpjsonServers`, `enableAllProjectMcpServers` or `disabledMcpjsonServers`. A clone can't approve itself: in a folder whose trust dialog you haven't accepted, those keys in the committed `.claude/settings.json` are ignored, and `claude mcp list` shows `⏸ Pending approval`. A `headersHelper` from `.mcp.json` doesn't run until the folder is trusted either. The gap is non-interactive use: `claude -p`, Agent SDK and cloud sessions can't show the prompt and load project servers without asking. To keep one out there, use `disabledMcpjsonServers` (it beats every approval), drop project settings with `--setting-sources`, or run with `--strict-mcp-config --mcp-config`. `claude mcp reset-project-choices` clears earlier answers.

code

bash · 8 lines
bash
# Which project servers are approved, pending or rejected here?
claude mcp list

# Ask again for every .mcp.json server in this project
claude mcp reset-project-choices

# CI: claude -p cannot prompt, so load only the servers this job names
claude -p --strict-mcp-config --mcp-config ./ci/mcp.json "Summarise the failing tests"

go deeper

for a junior

Know that Claude Code asks before using a server from a cloned repository's .mcp.json, and that /mcp shows what is pending.

for a middle

Explain where approvals are stored, the three keys involved, and why the committed project settings file cannot approve servers in an untrusted folder.

for a senior

Show that headless, SDK and cloud runs skip the prompt, and pick the right control there: disabledMcpjsonServers, --setting-sources or --strict-mcp-config with --mcp-config.

for a principal

Decide how far per-user approval can carry a team and when the risk of repositories declaring servers calls for organisation-level policy instead.

## The risk a committed `.mcp.json` carries `.mcp.json` is **project scope**: a file at the repository root that every clone gets. A stdio entry in it names a command to run on your machine; a remote entry names a server that will receive requests from your session. If Claude Code simply connected whatever a repository declares, cloning an unfamiliar repository and starting a session would be enough to run its code. So project servers sit behind an **approval** step, and that approval interacts with **workspace trust** — the dialog Claude Code shows the first time you open a folder interactively. ## What happens in an interactive session 1. Claude Code reads `.mcp.json` at startup. 2. The first time it sees a project server, it **asks you to approve it**. If you miss the prompt, approve later from `/mcp`. 3. Your choice is recorded in `.claude/settings.local.json`: - approving one server adds it to `enabledMcpjsonServers`; - approving all writes `enableAllProjectMcpServers: true`; - rejecting adds the name to `disabledMcpjsonServers`. 4. Until approved, `claude mcp list` and `claude mcp get` show the server as `⏸ Pending approval (run claude to approve)` without connecting it. `claude mcp reset-project-choices` resets those answers so you are asked again. ## A repository cannot approve its own servers The approval keys are ordinary settings, so a repository could try to commit `enableAllProjectMcpServers: true` or `enabledMcpjsonServers` in its shared `.claude/settings.json`. In a folder whose trust dialog you haven't accepted, Claude Code **ignores those keys in the shared project file** — in the session and in `claude mcp list` / `get` — and keeps the server pending. Since 2.1.196, `claude mcp list` and `get` no longer spawn servers that a repository self-approved this way. Approvals still honoured in an untrusted folder: - your user `~/.claude/settings.json`; - managed settings; - settings passed with `--settings`; - an untracked `.claude/settings.local.json`, once Claude Code can confirm with git that it is untracked, which it checks only in a trusted folder. `disabledMcpjsonServers` in **any** settings file, including a committed one, still rejects a server; rejection takes precedence over both approval keys. ## `headersHelper` waits for trust A `headersHelper` is a shell command that mints request headers. For a server in a project `.mcp.json` (or at local scope), Claude Code runs it only after you accept the trust dialog for the folder the server is declared in. Until then it connects with the static `headers` alone; in a `claude -p` or SDK session it prints a `headersHelper not run` line per server to stderr. Since 2.1.238 this applies under `claude -p` too. A helper from a repository also runs without the credential-like variables from your environment. ## Where the prompt cannot protect you | Session | Project servers from `.mcp.json` | |---|---| | Interactive, folder trusted | Asked per server on first use | | Interactive, only a parent folder trusted | Asked; the repository's own approvals don't count | | `claude -p`, Agent SDK, cloud session | **Loaded without asking**, approved or not (the SDK only when its `settingSources` include project settings) | | `bypassPermissions` with `skipDangerousModePermissionPrompt` in user or managed settings | Prompt skipped | In those non-interactive runs, keep a server out with: - `disabledMcpjsonServers`, which blocks it in every permission mode; - `--setting-sources` (or the SDK's `settingSources`) without `project`; - `--strict-mcp-config` with `--mcp-config`, so only the servers you pass load. Since 2.1.246 a strict session no longer waits on approval for project servers it isn't loading. Administrators who need an organisation-wide allow or deny list use managed MCP configuration, which is a separate policy layer. ## Common mistakes - Believing project servers "load silently" everywhere, or that they are always prompted — both are wrong; it depends on whether the session can ask. - Treating a committed `enableAllProjectMcpServers` as a convenience for the team; in an untrusted clone it does nothing. - Using a `permissions.deny` rule on `mcp__server` to stop a server: that blocks its tool calls, but the server still connects.

  • Your CI job runs `claude -p` in a repository whose `.mcp.json` declares a server you don't want in CI. What are your options?
    `claude -p` loads project servers without asking, so the approval prompt won't protect you. Reject the server with `disabledMcpjsonServers`, exclude project settings with `--setting-sources user` (or another list without `project`), or pass `--strict-mcp-config` with `--mcp-config` so only the servers you list load.
  • Does a `permissions.deny` rule on `mcp__tracker` stop the `tracker` server from connecting?
    No. Permission rules govern tool calls, so the denied tools can't be used, but the server still connects and its process still runs. To stop the connection itself for a `.mcp.json` server, reject it with `disabledMcpjsonServers` or leave it unapproved.
  • You approved a project server by mistake. How do you undo it?
    Run `claude mcp reset-project-choices` to clear the recorded answers so Claude Code asks again, or edit `.claude/settings.local.json` and move the name from `enabledMcpjsonServers` to `disabledMcpjsonServers`.

  • Project MCP servers load silently in every kind of session
  • Committing enableAllProjectMcpServers saves teammates the approval prompt
  • claude -p waits for someone to approve .mcp.json servers
  • A permissions.deny rule on the server stops it from connecting
  • Once trusted, a repository's headersHelper runs with all your credentials

Assumes Claude Code 2.1.286; repository self-approval stopped working in claude mcp list/get in 2.1.196, headersHelper trust under claude -p arrived in 2.1.238, and strict sessions stopped waiting on approval in 2.1.246.