Last updated: November 12, 2026
TL;DR
Claude Code MCP servers get added at one of three scopes, shared by committing a .mcp.json file, and controlled for a whole team through managed settings. By default anyone can connect any server, and Anthropic "doesn't security-audit or manage any MCP server," so the team decision is which control pattern to deploy, not which server is best.
- ๐งฉ Add at the right scope. Local is the default and stays private to one project. Project scope writes
.mcp.json, which you commit. User scope follows you into every project. - ๐ค Share through
.mcp.json. Teammates approve each project server the first time they run Claude Code interactively. Put tokens in environment variables, not in the file. - ๐ก๏ธ Control with managed settings. Pick a pattern: disable MCP, a fixed set, servers you provide, an approved catalog, or a denylist.
- ๐ Limit the tools inside a server. Permission rules such as
mcp__github__*decide which tools run without a prompt. - ๐ก Watch what gets used. OpenTelemetry can record which servers and tools each person calls.
Before you start
You need Claude Code installed, a server's URL or start command, and, for the control steps, a way to deliver managed settings to your team's machines: server-managed settings on a Claude Team or Enterprise plan, or a managed-settings.json file pushed by your device management. Our Claude Code settings guide explains which settings file wins when they disagree.
Step 1: Add each server at the right scope
The scope decides which projects a server loads in and whether teammates get it. Anthropic's MCP docs define three:
| Scope | Loads in | Shared with the team | Stored in |
|---|---|---|---|
| Local (the default) | The current project only | No | ~/.claude.json, under that project's path |
| Project | The current project only | Yes, through version control | .mcp.json at the project root |
| User | All your projects | No | ~/.claude.json |
Run claude mcp add with the server's name and its URL or start command. It writes to local scope unless you set the scope flag to project or user. Use local for personal or experimental servers and anything carrying credentials you don't want in the repository. Use project for the servers the whole team should have. Use user for personal tools you want everywhere.
When the same name appears in more than one place, Claude Code connects once, using the highest-ranked definition: local, then project, then user, then plugin servers, then claude.ai connectors. It takes that whole entry and doesn't merge fields across scopes. A server your organization provides through managed settings outranks all of them.
Check what loaded with claude mcp list, or /mcp inside a session.
Step 2: Share project servers in .mcp.json
A committed .mcp.json gives everyone on the repository the same servers. Keep secrets out of it with environment variable expansion, which works in a server's command, args, env, url and headers:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
That example, from Anthropic's docs, reads the key from each person's own API_KEY and falls back to a default URL. If a variable is unset and has no default, the server still loads, claude mcp list warns about it, and the raw ${VAR} text is used as is.
Three rules about how teammates receive the file:
- Each person approves project servers. In an interactive session, Claude Code asks before using a server from
.mcp.json.claude mcp reset-project-choicesclears those answers. - A cloned repository can't approve itself. Approval settings committed to the project's
.claude/settings.jsonare ignored until someone trusts the folder, so the server sits at "Pending approval" instead. - Some sessions skip the prompt.
claude -pruns, Agent SDK sessions and some cloud sessions load project servers without asking. To keep one out everywhere, list it indisabledMcpjsonServers, which blocks it in every permission mode.
That third rule is the one to plan for if you run Claude Code in CI or scripts: whatever is in .mcp.json loads there unless you block it.
Step 3: Choose how much your organization controls
Reviewing .mcp.json doesn't show every server a session can load, because user and local scopes, claude.ai connectors and plugins add servers too (security docs). Control comes from managed settings. Anthropic's managed MCP guide lists the patterns:
| Pattern | What it does | How you set it |
|---|---|---|
| Disable MCP | No servers load, apart from a few built-in ones | managed-mcp.json with an empty server map |
| Fixed deployment | Everyone gets the same servers and can't add others | managed-mcp.json listing your servers |
| Provided servers | Everyone gets your remote servers and keeps their own | managedMcpServers in managed settings |
| Approved catalog | People add servers from your list; anything else is blocked | allowedMcpServers plus allowManagedMcpServersOnly: true |
| Soft allowlist | An allowlist people can widen in their own settings | allowedMcpServers alone |
| Denylist only | Block known-bad servers, allow the rest | deniedMcpServers |
| No restrictions | Anyone adds anything | Deploy nothing |
For most small teams, the approved catalog is the useful middle. This managed settings entry, adapted from the docs, allows only the listed URLs and ignores allowlists in anyone's own settings:
{
"allowManagedMcpServersOnly": true,
"allowedMcpServers": [
{ "serverUrl": "https://api.githubcopilot.com/*" },
{ "serverUrl": "https://*.internal.example.com/*" }
]
}
Four details decide whether that holds:
- Match on URL or command, never on name alone. A
serverNameentry "is not a security control," because the name is whatever label a user typed. UseserverUrlfor remote servers andserverCommandfor local ones. - The lock is a separate key. Without
allowManagedMcpServersOnly, allowlists merge from every settings scope, so a user can broaden yours.allowManagedPermissionRulesOnlydoesn't enforce the MCP allowlist. - The denylist always wins. A denylist match blocks a server from any source, and denylists merge from every scope.
managed-mcp.jsonis a file, not a setting. It lives in a system path such as/Library/Application Support/ClaudeCode/or/etc/claude-code/, goes out through device management, and can't be delivered through server-managed settings.
Claude Code has no built-in MCP registry for people to browse, so publish your approved list and its claude mcp add commands somewhere people will find them, or ship the servers as plugins through a managed plugin marketplace.
Tell people before you switch a restriction on. A server that policy now blocks simply disappears from /mcp and claude mcp list, with no message saying why.
Step 4: Limit the tools inside each server
An allowed server can still offer tools you'd rather keep behind a prompt. Permission rules cover MCP tools by their full names: mcp__github__* matches every tool from a server named github, and mcp__github__get_issue matches one. A deny rule of mcp__* blocks every MCP tool from every server.
Allow rules for MCP tools need the literal mcp__<server>__ prefix before any wildcard, and take no specifier in parentheses. Our Claude Code permissions guide covers the order the rules run in and the mistakes that make an allow rule match nothing.
Server authors have one more lever: a tool marked with anthropic/requiresUserInteraction prompts on every call, even in auto and bypass modes, and allow rules can't skip it.
Step 5: Watch which servers people use
With OpenTelemetry export turned on, set OTEL_LOG_TOOL_DETAILS=1 and Claude Code records MCP server and tool names in tool events and on the cost and token counters. Aggregate them in your collector to see which servers your team actually connects to before you write the allowlist, and to check it afterward. Our Claude Code monitoring guide covers turning OpenTelemetry on for everyone.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| A server shows "Pending approval" | A project server not yet approved, or an untrusted folder | Run claude interactively in the folder and approve it |
claude mcp list says no servers are configured | The server was added at local scope in another project | Re-add it at user or project scope |
Cannot add MCP server "<name>": not allowed by enterprise policy | The server isn't on the managed allowlist | Add its URL or command to allowedMcpServers, or pick an approved server |
| A server vanished after a policy change | Policy now blocks it | Check the allowlist and denylist; tell the team what changed |
| The same server connects to the wrong endpoint | The name is defined in two scopes with different endpoints | Remove the extra one; claude mcp list warns about the conflict |
Frequently asked questions
How do I add an MCP server to Claude Code?
Run claude mcp add with a name and the server's URL or start command. It saves to local scope, private to the current project, unless you set the scope to project or user. Check it with claude mcp list, or /mcp inside a session.
Where is the Claude Code MCP config stored?
Local and user scope servers are stored in ~/.claude.json, and project scope servers in a .mcp.json file at the project root, which you commit to share. Administrators can also deploy managed-mcp.json in a system path or list servers in managed settings.
How do I share MCP servers with my team?
Add them at project scope so they land in .mcp.json, then commit the file. Each teammate approves the servers the first time they run Claude Code interactively. Use environment variables in the file for tokens and URLs that differ by person.
Can I restrict which MCP servers my team uses in Claude Code?
Yes. In managed settings, list approved servers in allowedMcpServers by URL or command and set allowManagedMcpServersOnly to true. For a fixed set nobody can change, deploy managed-mcp.json. A denylist blocks a server whatever else allows it.
Are MCP servers safe to use with Claude Code?
Anthropic reviews directory connectors against listing criteria but doesn't security-audit or manage any MCP server. Use servers you wrote or that come from providers you trust, keep tools behind permission rules, and restrict which servers run through managed settings.
Why does my MCP server say pending approval?
It's a project server from .mcp.json that hasn't been approved on your machine, or the folder isn't trusted yet. Run claude interactively in the folder and accept the prompts. Approval settings committed to the repository are ignored until the folder is trusted.
Get Claude Code set up properly for your team
We set up Claude Team for small businesses: the seat plan, the security settings, shared Projects and skills written from your actual processes, and managed Claude Code settings for teams with developers. If you'd rather have it done once and done right, see how our Claude Team setup works or book a 30-minute call.
Stop guessing. Score your first workflow.
Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.
Related Posts

Claude Code automation: five ways to run it unattended, and what to check first
Claude Code runs without you from a claude -p script, with /goal or /loop in a session, as a cloud or desktop scheduled task, or in GitHub Actions. How to pick by what starts each run, and Anthropic's five checks before you walk away.

Claude Code on Amazon Bedrock: when a team should route through AWS
Route Claude Code through Amazon Bedrock when AWS has to process your prompts and code, or your compliance program needs it. What a team gives up on Bedrock, what it gains, and the AWS-billed middle option, Claude Platform on AWS.

Claude Code permissions: allow, ask and deny rules that hold
Claude Code permission rules run in a fixed order, deny, then ask, then allow, and the first match decides. How to write Bash, file and MCP rules that match what you meant, where a path anchors, and where a rule stops protecting you.
