A project can ship a .mcp.json file that declares MCP servers for everyone who clones it. Claude Code asks for approval before using those servers in interactive sessions, and it ignores approval settings committed to an untrusted folder. A cloned repository cannot approve its own servers, but non interactive runs behave differently, so plan for both.
What the file does
Anthropic's Claude Code documentation describes three scopes for MCP servers. Local servers load in the current project only and are stored in the user's own config. Project servers are shared through version control in a .mcp.json file at the project root. User servers load in all your projects. Precedence runs local, then project, then user, and a server entry from one source is used whole, not merged with others.
A project .mcp.json is convenient. A team can commit a server for their issue tracker or security platform, and every new clone gets it. It is also a supply chain risk: whoever can change that file can add a server that runs a command or connects to a remote address.
The safeguards the documentation describes
- In interactive sessions Claude Code prompts for approval before using project scoped servers. A command resets those choices.
- A cloned repository cannot approve its own servers. The documentation says that approval settings committed to the project's settings file are ignored in an untrusted folder.
- Credential variables such as the Anthropic API key read as empty in a remote server's URL and headers, so a project config cannot send them to a server it names.
- A header helper, which runs a shell command to produce headers, runs only after you accept the trust dialog for the folder.
The gap to plan for
The documentation also says that in non interactive modes, such as the print mode, the Agent SDK and cloud sessions, the prompt cannot appear, so project servers load without asking. It lists ways to block a server anyway, including a deny setting, limiting setting sources and a strict config flag.
So a repository you run in an automated job can load its declared servers unless you block them. For a build pipeline, that is a decision to make on purpose.
| Mode | Project servers | Your action |
|---|---|---|
| Interactive | Prompt before use | Read the prompt, check the command or URL |
| Print mode | Load without asking | Use deny settings or a strict config |
| Agent SDK | Load without asking | Same |
| Cloud sessions | Load without asking | Same |
A worked example
This example is illustrative. A pull request adds a line to .mcp.json that points to a new remote server. The reviewer, used to dependency changes, skims past it. After merge, developers pull the change. Each one sees an approval prompt the first time, shows the URL, and most of them click yes.
A better review process treats .mcp.json like a lockfile. The reviewer asks who operates the server, what tools it exposes and what data it can reach. The team adds the file to the list of paths that need a security reviewer. A pipeline that runs the assistant non interactively uses a strict config so only an approved set of servers can load.
Step by step: using project scope safely
- Decide which servers are team wide and which are personal.
- Commit only team wide servers and keep tokens out of the file, using environment variable expansion.
- Require a security reviewer for any change to .mcp.json.
- Train people to read the approval prompt, not dismiss it.
- In automation, set a strict config or a deny list.
- Keep a register of project servers per repository.
- Reset approvals when a repository changes owner.
Why untrusted folders are special
A folder you just cloned from a stranger is untrusted. The documentation's rule means that a repository cannot arrive with its own pre approved servers. That is the correct behavior, and a good thing to demonstrate in a security training: clone a test repo that includes a server entry and watch the prompt.
Questions for your team
Who may change .mcp.json? Does your pipeline run the assistant non interactively? Which repositories declare servers, and does anyone know what they do?
Training exercise
Run a fifteen minute exercise for new developers. Give them a test repository with a harmless .mcp.json entry that points at a local script that only prints a message. Ask them to open it in an interactive session, read the approval prompt, and decide. Then ask what would have happened in a non interactive job. The contrast makes the point better than a policy document, and it costs almost nothing to run.
Where Safeguard fits
Safeguard offers an MCP Guardrail for policy on the tools agents can call, and asset discovery for inventory, which support the register above. A free scan covers dependencies in a repository. The Safeguard CLI, installed with a curl or PowerShell installer, can also write code, and the download page lists a Local agent and a Cloud agent as available.
Try it yourself
Click through it at your own pace, or open it full screen.
See how a policy can allow or block tools before an agent calls them.
Quick check
Does Claude Code always ask before using a project server?
In interactive sessions it prompts. In print mode, the Agent SDK and cloud sessions the documentation says the prompt cannot appear.
Can a repository pre approve itself?
No. The documentation says approval settings committed to an untrusted folder are ignored.
Should .mcp.json hold tokens?
No. Use environment variable expansion, and keep secrets out of version control.
Sources
Last reviewed: 19 October 2026.
