Back to Blog

Claude Code MCP servers on a team: add, share and control them

Alex Kim
10 min read
Claude Code MCP servers on a team: add, share and control them

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:

ScopeLoads inShared with the teamStored in
Local (the default)The current project onlyNo~/.claude.json, under that project's path
ProjectThe current project onlyYes, through version control.mcp.json at the project root
UserAll your projectsNo~/.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:

  1. Each person approves project servers. In an interactive session, Claude Code asks before using a server from .mcp.json. claude mcp reset-project-choices clears those answers.
  2. A cloned repository can't approve itself. Approval settings committed to the project's .claude/settings.json are ignored until someone trusts the folder, so the server sits at "Pending approval" instead.
  3. Some sessions skip the prompt. claude -p runs, Agent SDK sessions and some cloud sessions load project servers without asking. To keep one out everywhere, list it in disabledMcpjsonServers, 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:

PatternWhat it doesHow you set it
Disable MCPNo servers load, apart from a few built-in onesmanaged-mcp.json with an empty server map
Fixed deploymentEveryone gets the same servers and can't add othersmanaged-mcp.json listing your servers
Provided serversEveryone gets your remote servers and keeps their ownmanagedMcpServers in managed settings
Approved catalogPeople add servers from your list; anything else is blockedallowedMcpServers plus allowManagedMcpServersOnly: true
Soft allowlistAn allowlist people can widen in their own settingsallowedMcpServers alone
Denylist onlyBlock known-bad servers, allow the restdeniedMcpServers
No restrictionsAnyone adds anythingDeploy 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 serverName entry "is not a security control," because the name is whatever label a user typed. Use serverUrl for remote servers and serverCommand for local ones.
  • The lock is a separate key. Without allowManagedMcpServersOnly, allowlists merge from every settings scope, so a user can broaden yours. allowManagedPermissionRulesOnly doesn'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.json is 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

SymptomLikely causeFix
A server shows "Pending approval"A project server not yet approved, or an untrusted folderRun claude interactively in the folder and approve it
claude mcp list says no servers are configuredThe server was added at local scope in another projectRe-add it at user or project scope
Cannot add MCP server "<name>": not allowed by enterprise policyThe server isn't on the managed allowlistAdd its URL or command to allowedMcpServers, or pick an approved server
A server vanished after a policy changePolicy now blocks itCheck the allowlist and denylist; tell the team what changed
The same server connects to the wrong endpointThe name is defined in two scopes with different endpointsRemove 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.

#claude-code#MCP#Team Setup#Managed Settings#guardrails
Free assessment

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.