How do Claude Code's managed-mcp.json file and a managed allowedMcpServers allowlist differ in controlling which MCP servers developers can use?
answer
- fixed set versus approved catalog
- exclusive control from a system path
- a lock stops users broadening the list
- match on URL or command, not name
- the denylist always merges and wins
basics
~20 smanaged-mcp.json takes exclusive control: only its servers, plus organization-provided ones, load and users can't add others. A managed allowedMcpServers list, locked with allowManagedMcpServersOnly, is a catalog: users add their own servers and only matching ones load.
solid answer
~40 s`managed-mcp.json` sits in the system directory beside the managed settings file and uses the `.mcp.json` format. Deploying it gives **exclusive control**: Claude Code loads its servers, servers provided through `managedMcpServers` (2.1.259+) and a few built-ins, and nothing else — `claude mcp add` fails, plugin servers and `--mcp-config` servers are blocked, and an empty `mcpServers` map turns MCP off. It can't be pushed from the admin console. An **allowlist** instead filters what users configure: `allowedMcpServers` entries match by `serverUrl` (wildcards), exact `serverCommand` or `serverName`, and only `allowManagedMcpServersOnly: true` stops user allowlists broadening it. `deniedMcpServers` merges from every scope and always wins. Match on URL or command: a name is just a user-chosen label.
code
json · 11 lines{
"allowManagedMcpServersOnly": true,
"allowedMcpServers": [
{ "serverUrl": "https://mcp.example.com/*" },
{ "serverUrl": "https://*.internal.example.com/*" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
],
"deniedMcpServers": [
{ "serverUrl": "https://staging.example.com/*" }
]
}go deeper
Know that an organization can either fix the set of MCP servers or publish an approved list, and that blocked servers simply disappear for users.
Explain exclusive control versus filtering, the three entry kinds, and the difference between an unset allowlist and an empty one.
Write entries that actually enforce (URL or command, never name alone), lock the allowlist, and warn users before servers silently vanish.
Decide between a curated fixed set and a self-service catalog by who owns server vetting and how fast teams need new integrations.
## Two different jobs By default anyone running Claude Code can connect any **MCP server** they choose. An administrator has two main tools, and they answer different questions: - **`managed-mcp.json`** answers "which servers exist here?" — it deploys a fixed set and takes exclusive control. - **`allowedMcpServers` / `deniedMcpServers`** answer "which of the servers people add are allowed to load?" — they filter, but deploy nothing. | Pattern | Configure | | :- | :- | | Disable MCP | `managed-mcp.json` with `"mcpServers": {}` | | Fixed deployment | `managed-mcp.json` with the approved servers | | Approved catalog | `allowedMcpServers` + `allowManagedMcpServersOnly: true` | | Soft allowlist | `allowedMcpServers` without the lock | | Denylist only | `deniedMcpServers` | | Provide servers, users keep theirs | `managedMcpServers` in managed settings | ## managed-mcp.json: exclusive control The file lives at `/Library/Application Support/ClaudeCode/managed-mcp.json` on macOS, `/etc/claude-code/managed-mcp.json` on Linux and WSL, and `C:\Program Files\ClaudeCode\managed-mcp.json` on Windows. With it deployed: - Only its servers load, plus `managedMcpServers` entries, in-process servers the host app registers, and Claude in Chrome if separately allowed. - `claude mcp add` fails with an error saying enterprise MCP configuration has exclusive control; plugin servers are suppressed; on a workstation, passing `--mcp-config` makes Claude Code exit at startup. - claude.ai connectors are suppressed unless `allowAllClaudeAiMcps: true` is set in managed settings. - It is a standalone file, so it **cannot be delivered through server-managed settings**; device management or any process with administrator rights places it. - Any user on the machine can read it, so credentials belong in `${VAR}` expansion, OAuth or a `headersHelper`, never in an `env` block. ## Allowlists and denylists Entries match a server by one key: - **`serverUrl`** — a remote URL, with `*` wildcards anywhere; hostnames match case-insensitively. - **`serverCommand`** — the exact command and arguments array of a stdio server. - **`serverName`** — the label the user typed. It is **not a security control**: anyone can name any server `github`. Once the allowlist holds a `serverUrl` entry, every remote server must match a URL pattern; once it holds a `serverCommand` entry, every stdio server must match a command. Unset means all servers are allowed; an empty array `[]` means none, apart from servers that skip the check. Without `allowManagedMcpServersOnly`, allowlists from every settings scope merge, including a user's own `~/.claude/settings.json`, so a user can widen the list. With the lock, only the managed allowlist counts. The denylist always merges from every scope, so users can still block servers for themselves. ## How a server is evaluated 1. **Merge the lists**: allow and deny entries from every scope combine; with the lock on, only the managed allowlist is kept. 2. **Check the denylist**: a match by URL, command or name blocks the server, and nothing overrides it. 3. **Check the allowlist**: if one is set anywhere, the server must match by the rules above. The organization's own servers skip step 3: every `managedMcpServers` entry, and `managed-mcp.json` entries that use no `${VAR}` expansion. That exemption for the file's servers dates from Claude Code 2.1.259; before it, every managed server had to pass the allowlist. ## Providing servers without locking Since 2.1.259, `managedMcpServers` in any managed source provides remote servers to every user alongside their own. Entries must be `http` or `sse` with an `https://` URL and no `command`, so a managed document never names a program to run. Users can't remove them but can turn one off for themselves in `/mcp`. ## How restrictions look to users Policy blocks are quiet, so the rollout needs communication: - A denied server added with `claude mcp add` fails with a message saying it is explicitly blocked by enterprise policy; one missing from the allowlist fails as not allowed by enterprise policy. - A server that was already configured and is now blocked simply disappears from `/mcp` and `claude mcp list`, with no hint that policy is the reason. - On a managed machine, `claude mcp list` showing only the file's servers confirms the file is read; a user's own servers still appearing means Claude Code isn't reading it. ## Summary Use the file when the organization decides the whole server set; use a locked allowlist when users choose from a catalog. Either way, write entries by URL or command, and remember the denylist is the one list that always applies.
- Why is a `serverName` allowlist entry not a security control?The name is the label a user assigns with `claude mcp add` or in a config file, not the server itself, so anyone can call an arbitrary server `github` and match it. Enforcement needs `serverUrl` entries for remote servers and `serverCommand` entries for stdio servers; once one of those exists, a name match no longer admits that transport.
- Can an organization on server-managed settings deploy `managed-mcp.json` from the claude.ai admin console?No. The file is standalone and must be placed at its system path by device management or an administrator. From the console, deliver `allowedMcpServers` and `deniedMcpServers`, or provide remote servers with `managedMcpServers`, which accepts `http` and `sse` servers and doesn't take exclusive control. A deployed file still applies alongside server-managed settings.
managed-mcp.json is a set menu: the kitchen serves exactly the dishes printed and takes no other orders. A locked allowlist is an a-la-carte menu limited to approved dishes: diners still order for themselves, but anything off the menu is refused. The denylist is the allergy list, which overrides every order, whichever menu is in use.
- A serverName allowlist entry pins which binary or URL a server may use.
- Without allowManagedMcpServersOnly, users still can't widen the managed allowlist.
- An empty allowedMcpServers array means every server is allowed.
- managed-mcp.json can be uploaded through the claude.ai admin console.
- Developers can't block a server the organization provides.
Assumes Claude Code 2.1.286; managedMcpServers and the allowlist exemption for managed-mcp.json servers without ${VAR} expansion both arrived in 2.1.259.