skip to content

How do Claude Code's managed-mcp.json file and a managed allowedMcpServers allowlist differ in controlling which MCP servers developers can use?

level: seniorimportance: should knowfreq 7%

answer

  1. fixed set versus approved catalog
  2. exclusive control from a system path
  3. a lock stops users broadening the list
  4. match on URL or command, not name
  5. the denylist always merges and wins

basics

~20 s

managed-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
json
{
  "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

for a junior

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.

for a middle

Explain exclusive control versus filtering, the three entry kinds, and the difference between an unset allowlist and an empty one.

for a senior

Write entries that actually enforce (URL or command, never name alone), lock the allowlist, and warn users before servers silently vanish.

for a principal

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.