[DOCS] Managed MCP policy (`allowedMcpServers`/`deniedMcpServers`) enforcement windows are not documented

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/managed-mcp

Section/Topic

The "Policy-based control with allowlists and denylists" section of the Managed MCP page, in combination with the "Fetch and caching behavior" / "Enforce fail-closed startup" sections of the Server-managed settings page. The [How a server is evaluated](#how-a-server-is-evaluated) table and the [Configuration summary](#configuration-summary) table should also reflect that managed allowlists/denylists now apply during the startup windows described in the v2.1.169 fix.

Current Documentation

The Managed MCP page documents the policy in the abstract, including the [How a server is evaluated](#how-a-server-is-evaluated) check order and the [Configuration summary](#configuration-summary) table. It says:

"Allowlists and denylists filter which configured servers are allowed to load. They aren't a registry: a server still has to be added by a user, a plugin, or managed-mcp.json before the allowlist or denylist applies to it."

It does not state when the allowlist/denylist is evaluated during session lifecycle (e.g. at session start, after a /mcp reconnect, after a remote-settings fetch, or on the first session after install), nor does it cover IDE-typed MCP server definitions.

The Server-managed settings page (https://code.claude.com/docs/en/server-managed-settings) currently describes the startup model as:

"First launch without cached settings: Claude Code fetches settings asynchronously If the fetch fails, Claude Code continues without managed settings There is a brief window before settings load where restrictions are not yet enforced Subsequent launches with cached settings: Cached settings apply immediately at startup Claude Code fetches fresh settings in the background Cached settings persist through network failures"

The page also documents forceRemoteSettingsRefresh for environments where "this brief unenforced window is unacceptable" but does not address the related cold-start latency for orgs without server-managed settings at all.

What's Wrong or Missing?

The v2.1.169 changelog (https://code.claude.com/docs/en/changelog) states:

"Fixed enterprise managed MCP policies (allowedMcpServers/deniedMcpServers) not being enforced on reconnect, IDE-typed configs, --mcp-config servers during the first session after install, or before remote settings loaded; also fixed slow cold starts for orgs without remote settings"

The Managed MCP and Server-managed settings pages do not document any of these four enforcement windows, so an administrator reading the docs cannot tell when their allowlist/denylist is actually applied to a given server source. The four gaps that the fix closes are:

A. Reconnect window

The "How a server is evaluated" check order is only described in the context of the initial load. The docs do not say that allowedMcpServers/deniedMcpServers are re-applied when MCP servers are re-evaluated after a /mcp reconnect or an automatic reconnection of an HTTP/SSE server. This matters because the re-evaluation step was not enforcing managed policy before v2.1.169.

B. IDE-typed configs

MCP servers configured from the IDE (e.g. VS Code's native MCP management dialog at https://code.claude.com/docs/en/vs-code) are not mentioned on the Managed MCP page. An administrator who configures allowedMcpServers cannot tell from the current docs whether an MCP server added through the IDE is subject to the same allowlist/denylist.

C. --mcp-config servers during the first session after install

The docs mention --mcp-config (https://code.claude.com/docs/en/cli-reference) and document at the changelog level that the flag is now subject to managed policy (entry added in v2.1.85), but the Managed MCP page does not address the first-session-after-install window — i.e. when no remote-settings cache exists yet, the docs do not state whether --mcp-config servers are evaluated against the local managed-settings.json allowlist/denylist at startup. They are now, but the page is silent.

D. Enforcement before remote settings loaded

The Server-managed settings page acknowledges "a brief window before settings load where restrictions are not yet enforced" and offers forceRemoteSettingsRefresh as the fail-closed alternative. It does not state whether locally-deployed allowedMcpServers/deniedMcpServers (in MDM-deployed plist/registry, system managed-settings.json, or ~/.claude/managed-settings.json) close that window for MCP policy during the same startup. Per the v2.1.169 fix, they do, but the page still implies that only forceRemoteSettingsRefresh addresses the unenforced window.

E. Cold starts for orgs without remote settings

The Server-managed settings page is silent on cold-start latency for organizations that use endpoint-managed or file-based settings and have no server-managed settings. The v2.1.169 fix removed a slow path in this case, but no version note, callout, or forceRemoteSettingsRefresh guidance in the docs acknowledges the regression-and-fix history or recommends caching the settings.

Suggested Improvement

Add a new subsection to the Managed MCP page titled "When allowlists and denylists are evaluated" that documents the four startup/reconnect windows now enforced in v2.1.169, and update the related Server-managed settings page so administrators can see the full picture without joining the changelog to the docs themselves.

Option A: Comprehensive fix

Add to https://code.claude.com/docs/en/managed-mcp after the "How a server is evaluated" section:

## When allowlists and denylists are evaluated Allowlists and denylists are evaluated at every point the server list is recomputed, not only at session start: Session start — the check order on this page runs once for every server before it connects. This includes servers declared in managed-mcp.json, in user/project .mcp.json, in --mcp-config, and in plugin or claude.ai connector sources. First session after install — if no remote-settings cache exists, locally-deployed allowedMcpServers and deniedMcpServers (in MDM-managed plist/registry, system managed-settings.json, or ~/.claude/managed-settings.json) are applied before any MCP server connects. --mcp-config servers are subject to the same evaluation. IDE-typed configs — servers added through the VS Code MCP management dialog (https://code.claude.com/docs/en/vs-code) are evaluated against the same allowlist/denylist before they connect. Reconnect — the check order re-runs on every automatic HTTP/SSE reconnect (https://code.claude.com/docs/en/mcp#automatic-reconnection), on /mcp reconnect, and on IDE-triggered reconnects. A server that was allowed at session start can become blocked if the policy changes; conversely, a server that was blocked at startup can become allowed. Local sources are always available at startup, so a deniedMcpServers entry in a system managed-settings.json blocks the server even before remote settings load. To close the same window when policy is delivered from Anthropic's servers, use forceRemoteSettingsRefresh (https://code.claude.com/docs/en/server-managed-settings#enforce-fail-closed-startup).

Update the "Fetch and caching behavior" section of https://code.claude.com/docs/en/server-managed-settings to replace the "There is a brief window before settings load where restrictions are not yet enforced" sentence with:

"Locally-deployed MCP policy keys (allowedMcpServers, deniedMcpServers) are applied at startup before any MCP server connects, so the unenforced window only affects keys that Anthropic delivers from its servers."

Add a callout noting that the v2.1.169 release fixed slow cold starts for orgs without server-managed settings, and that no setting is required to benefit from the change.

Option B: Minimum fix

Add a single sentence to the "Configuration summary" table footnote on https://code.claude.com/docs/en/managed-mcp:

"Allowlists and denylists are applied at session start (including --mcp-config servers on the first session after install and servers added from the IDE MCP dialog) and re-applied on reconnect."

And add a one-line note in the "Enforce fail-closed startup" section of https://code.claude.com/docs/en/server-managed-settings:

"Local MCP policy keys (in a system managed-settings.json, MDM-deployed plist/registry, or ~/.claude/managed-settings.json) are applied at startup before any server connects, so the unenforced window for MCP restrictions only affects keys that Anthropic delivers remotely."

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/managed-mcp | 120–158 | "Policy-based control with allowlists and denylists" / "How a server is evaluated" — no mention of evaluation windows |
| https://code.claude.com/docs/en/managed-mcp | 330–340 | "Configuration summary" table — does not note when settings are applied |
| https://code.claude.com/docs/en/server-managed-settings | 139–155 | "Fetch and caching behavior" — claims a brief unenforced window for all restrictions, which is no longer accurate for local MCP policy keys after v2.1.169 |
| https://code.claude.com/docs/en/server-managed-settings | 157–173 | "Enforce fail-closed startup" — no mention of cold-start latency fix for orgs without server-managed settings |
| https://code.claude.com/docs/en/vs-code | 380 | IDE MCP management dialog — does not state that servers added from the dialog are subject to managed MCP policy |
| https://code.claude.com/docs/en/mcp | 173–175 | "Automatic reconnection" — does not state that allowlist/denylist is re-evaluated on reconnect |
| https://code.claude.com/docs/en/cli-reference | 87 | --mcp-config flag — does not state that the flag is subject to managed MCP policy at first-session-after-install startup |

Total scope: 7 pages affected.

Changelog version: v2.1.169 (June 8, 2026).