The whole hunk
from line 40, old and new numbered
/
lines
from line 40
4040
4141## Exclusive control with managed-mcp.json
4242
43If you deploy a `managed-mcp.json` file, Claude Code loads only the servers that file defines, the servers you [provide through `managedMcpServers`](#provide-servers-through-managed-settings), plus any in-process servers the app that started the session registers, such as the VS Code extension's own server or the [connectors the desktop app delivers](/docs/en/mcp#how-connectors-reach-claude-code). Users can't add, modify, or use any other MCP servers, including plugin-provided servers and servers passed with the [`--mcp-config` CLI flag](/docs/en/cli-reference#cli-flags). The file also suppresses the claude.ai connectors Claude Code fetches itself unless you [allow them alongside the managed set](#allow-claude-ai-connectors-alongside-the-managed-set).
43When you deploy a `managed-mcp.json` file, Claude Code loads only these MCP servers:
4444
45* The servers the file defines
46* Servers you [provide through `managedMcpServers`](#provide-servers-through-managed-settings)
47* In-process servers that the app that started the session registers, such as the VS Code extension's own server or the [connectors the desktop app delivers](/docs/en/mcp#how-connectors-reach-claude-code)
48
49Users can't add, modify, or use any other MCP servers, including plugin-provided servers and servers passed with the [`--mcp-config` CLI flag](/docs/en/cli-reference#cli-flags). The file also suppresses the claude.ai connectors Claude Code fetches itself unless you [allow them alongside the managed set](#allow-claude-ai-connectors-alongside-the-managed-set).
50
4551### Deploy managed-mcp.json
4652
4753`managed-mcp.json` is a standalone file, so it cannot be delivered through [server-managed settings](/docs/en/server-managed-settings). To deliver servers through managed settings instead, without exclusive control, use [`managedMcpServers`](#provide-servers-through-managed-settings).
from line 117
111117
112118To confirm the file is in effect, run two checks on a managed machine:
113119
1141. `claude mcp list` shows only the servers in `managed-mcp.json`, plus any you provide through `managedMcpServers`. If a user's own servers still appear, the file isn't being read; check the path and permissions.
1201. `claude mcp list` shows only the servers in `managed-mcp.json`, plus any you provide through `managedMcpServers`. Two other results mean something is wrong:
121 * If a user's own servers still appear, Claude Code isn't reading the file, so check its path and the permissions on its parent directories.
122 * If the file's servers don't appear and the `MCP config diagnostics` section marks the enterprise config as failed to parse, Claude Code can't read or parse the file. Fix the error that section names, then have the user restart Claude Code.
1151232. `claude mcp add --transport http test https://example.com/mcp` fails with `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`. The URL doesn't need to be a real server, since the policy check rejects the command before anything is contacted.
116124
117125### Disable MCP entirely
from line 463
455463| The server is on a denylist and the user runs `claude mcp add` | `Cannot add MCP server "<name>": server is explicitly blocked by enterprise policy` |
456464| The server isn't on the allowlist and the user runs `claude mcp add` | `Cannot add MCP server "<name>": not allowed by enterprise policy` |
457465| The user runs `claude mcp remove` on a server from `managedMcpServers` | `MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.` |
458| A previously configured server is now blocked by policy | The server silently disappears from `/mcp` and `claude mcp list` with no warning |
466| A previously configured server is now blocked by policy | The server disappears from `/mcp` and `claude mcp list` |
459467| A server becomes blocked while a session is running, and the user selects **Reconnect** or turns it back on in `/mcp` | [`MCP server <name> is blocked by enterprise managed policy`](/docs/en/errors#mcp-server-is-blocked-by-enterprise-managed-policy) |
460468
461469When a server silently disappears, the user gets no signal that policy is the reason, so tell affected users which servers are blocked when you roll out a new restriction.