The three scopes, and which one shares
Every server you add to Claude Code lands in a scope. The scope decides who else gets it.
| Scope | Loads in | Shared with the team | Stored in |
|---|---|---|---|
local (default) |
This project, for you | No | ~/.claude.json |
project |
This project, for everyone | Yes, through git | .mcp.json in the project root |
user |
All your projects | No | ~/.claude.json |
You choose with -s or --scope. Two commands cover most cases:
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/
claude mcp add --scope project --transport stdio mytool -- npx -y some-mcp-server
The -- separates Claude Code’s options from the command that starts a local server. SSE still works but is marked deprecated; use http for remote servers.
If the same name exists in more than one place, Claude Code takes the whole entry from the highest source, in this order: local, project, user, plugin servers, claude.ai connectors. Fields are not merged.
Sharing servers through the repo, step by step
- Add the server with
--scope project. Claude Code writes it into.mcp.json. - Keep secrets out of the file. Use
${VAR}or${VAR:-default}inurl,headers,command,argsorenv. Each developer sets the variable on their own machine. Better still, use a remote server with OAuth, so nobody needs a key at all. - Commit
.mcp.json. Colleagues get it on their next pull. - Each person approves. In an interactive session Claude Code asks for approval before using project-scoped servers. Until then
claude mcp listshows them as pending.claude mcp reset-project-choicesundoes earlier choices. - Each person signs in. For OAuth servers:
/mcpin Claude Code, orclaude mcp login <name>. Everyone signs in as themselves.
One thing to know: in non-interactive runs (claude -p), Agent SDK sessions and some cloud sessions, project-scoped servers load without asking. A .mcp.json in a repo you run headless is trusted as-is.
Organization-wide control
By default anyone running Claude Code can connect any MCP server. Anthropic’s documentation states plainly that it reviews connectors for its directory but does not security-audit or manage MCP servers. For admins there are several patterns:
| Pattern | What it does | How |
|---|---|---|
| Fixed deployment | Your fixed set loads, alongside supported managed and host-provided additions | managed-mcp.json with your servers |
| Disable MCP | User-configured servers stop loading; managed and host-provided exceptions remain | managed-mcp.json with an empty mcpServers map |
| Provided servers | Everyone gets your remote servers and keeps their own | managedMcpServers in managed settings |
| Approved catalog | Only listed servers may be added | allowedMcpServers plus allowManagedMcpServersOnly: true |
| Denylist | Block known-bad servers | deniedMcpServers |
managed-mcp.json lives at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux, %ProgramFiles%\ClaudeCode\ on Windows) and is usually pushed with device management. Match servers by serverUrl or serverCommand: Anthropic warns that a serverName entry is not a security control, because anyone can name any server “github”.
Individual rules can also be set per server in permissions. mcp__github__* matches every tool of the github server, and mcp__github__get_* only its get_ tools. Allow rules accept globs only after a literal mcp__<server>__ prefix, so an unanchored mcp__* in an allow rule auto-approves nothing, while a deny rule of mcp__* removes every MCP tool from Claude’s context. Characters such as . or spaces in a server name become _ in the rule, so a server named my.server is written mcp__my_server__*.
The common misunderstanding
“If it is in .mcp.json, the team shares the same AI setup.” The team shares the same connections. It does not share what happens inside them. Each developer’s Claude Code session still starts fresh, with that developer’s CLAUDE.md files and auto memory. What Claude learned from one person’s corrections yesterday does not reach the next person’s session. And .mcp.json only works in Claude Code: the colleague in Cursor or Codex needs the same servers in a different file. See Cursor MCP servers and Codex MCP servers.
What this means for a team
.mcp.json is the right way to give every Claude Code user the same tools: GitHub, your tracker, your docs. Pair it with clear rules on which servers may write, and with OAuth instead of shared keys. For memory and instructions, the separate question is how what one developer teaches Claude reaches the rest; read does Claude Code have memory and Claude Code memory for teams.
Where Bombos fits
Bombos plugs into Claude Code as one more MCP connection, and into Cursor, Codex, Copilot, ChatGPT and your other AI tools the same way, so they all share one memory: team knowledge, rules the AI learned from corrections, and what already sits in repos, documents and mail, with a trail of what each answer rests on. It runs in our cloud or on your own server, and one developer can try it first with their own agents.
Related questions
Where does Claude Code store MCP servers?
Local and user scope are stored in ~/.claude.json. Project scope is stored in .mcp.json in the project root, which you commit to version control.
Why does Claude Code ask for approval of servers in .mcp.json?
For security, Claude Code asks for approval in interactive sessions before using project-scoped servers. Run claude mcp reset-project-choices to reset those choices.
How do I sign in to a remote MCP server in Claude Code?
Run /mcp inside Claude Code and complete the browser login, or claude mcp login <name> from the shell. Claude Code stores and refreshes the tokens.
Can an admin block MCP servers in Claude Code?
Yes. A managed-mcp.json file gives exclusive control over which servers load, and allowedMcpServers and deniedMcpServers in managed settings filter what users add. An empty managed-mcp.json blocks user-configured servers, but managed additions and host-provided servers can still load.
What if an MCP tool returns too much text?
Claude Code warns above 10,000 tokens and limits MCP output to 25,000 tokens by default. You can raise it with MAX_MCP_OUTPUT_TOKENS.
