Check one .mcp.json into the repo and every teammate's Claude Code gets the same MCP servers, secrets kept out.
WHEN TO USE IT
When a project depends on a few MCP servers and you are tired of telling each new person which commands to run.
Formats change. If a field stops working, check it against Anthropic's documentation.
Read it before you install it. A MCP server runs with your user account's permissions, on its own, every time it is triggered. That is what makes it useful, and why a stranger's should never be installed unread — this one included.
Project scope lives at the repository root. ${VAR} and ${VAR:-default} are expanded from each person's environment, so the file never needs a secret in it.
{
"mcpServers": {
"notes": {
"type": "stdio",
"command": "python",
"args": ["tools/mcp/server.py"],
"env": {
"NOTES_DIR": "${NOTES_DIR:-./docs}"
}
},
"issues": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${ISSUES_TOKEN}"
}
}
}
}--scope project writes .mcp.json for you. local (the default) and user scopes are stored in ~/.claude.json and are never committed.
claude mcp add --transport http --scope project issues https://mcp.example.com/mcp
# scopes:
# local this project, just you (default, ~/.claude.json)
# project this project, everyone (.mcp.json — commit it)
# user every project, just you (~/.claude.json)Claude Code asks each person to approve servers from a project .mcp.json before using them — a checked-in file cannot start code on someone's machine unannounced.
Before approving a project server, read its entry:
- command / args : what will run on your machine
- url : where your requests will go
- env / headers : which of your variables it readsMORE MCP SERVERS
The authority
Anthropic's documentation for MCP Servers
This template is a starting point. Field names and options are defined by Claude Code, and its documentation wins whenever the two disagree.
https://code.claude.com/docs/en/mcp