claude-code - 💡(How to fix) Fix [DOCS] Managed MCP policy docs omit invalid `allowedMcpServers`/`deniedMcpServers` entry behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Policy-based control with allowlists and denylists, especially invalid entries in allowedMcpServers and deniedMcpServers

Current Documentation

The managed MCP docs define the allowed entry shape:

allowedMcpServers and deniedMcpServers are lists of entries. Each entry is an object with a single key that identifies servers by their URL, their command, or their name:

They also describe the evaluation order:

Before loading a server, including one from managed-mcp.json, Claude Code runs three checks in order:

1. Merge the lists. Allowlist and denylist entries from every settings source combine into one allowlist and one denylist.

The configuration debugging page gives only generic validation guidance:

Run /doctor to validate your configuration files and surface invalid keys or schema errors.

What's Wrong or Missing?

Claude Code v2.1.154 fixed a managed-settings failure mode where a single invalid entry in allowedMcpServers or deniedMcpServers could discard all managed-settings policy. The bad entry is now dropped and claude doctor warns about it.

The docs currently explain the valid entry schema and the server evaluation flow, but they do not document what happens when one entry in either list is malformed.

A. Admins cannot tell whether invalid entries fail closed, fail open, or are skipped

For managed MCP policy, this is a security-relevant behavior. An administrator needs to know whether one malformed allowlist or denylist entry invalidates the whole policy, blocks all MCP servers, or is ignored while the rest of the managed policy remains active.

B. The claude doctor warning path is not documented for this specific policy

The troubleshooting docs say /doctor reports invalid keys or schema errors, but the managed MCP page does not tell admins that invalid allowedMcpServers or deniedMcpServers entries are reported there while valid entries continue to apply.

C. The docs do not explain partial-entry validation for list-based managed policy

Because allowedMcpServers and deniedMcpServers are arrays, users may reasonably expect array validation to be all-or-nothing. The v2.1.154 behavior is more precise: the invalid entry is dropped, not the entire policy.

Suggested Improvement

Add a short validation note near the Match servers by URL, command, or name section:

If an entry in allowedMcpServers or deniedMcpServers is invalid, Claude Code drops that entry, keeps applying the remaining valid managed MCP policy, and reports the invalid entry in claude doctor. Fix the reported entry so your intended allowlist or denylist is fully enforced.

Also add a cross-reference from debug-your-config so admins troubleshooting managed MCP policy know to run claude doctor or /doctor and check for dropped MCP policy entries.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: v2.1.154 changelog entry: "Fixed a single invalid allowedMcpServers/deniedMcpServers entry in managed settings discarding all managed-settings policy; the bad entry is now dropped with a claude doctor warning."