[DOCS] Contradictory logic in Managed MCP Security Policy explanation (OR vs AND evaluation)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The section Managed MCP configuration > Option 2: Policy-based control > How command-based restrictions work (and the subsequent "Important notes" section).

Current Documentation

"Name-based, command-based, and URL-based restrictions work together: a server passes if it matches either a name entry, a command entry, or a URL pattern (unless blocked by denylist)"

However, under How command-based restrictions work, it states:

"When the allowlist contains any serverCommand entries, stdio servers must match one of those commands" "Stdio servers cannot pass by name alone when command restrictions are present"

And provides this example under Example: Mixed name and command allowlist:

* Stdio server named "github" with ["node", "server.js"]: ❌ Blocked (stdio servers must match commands when command entries exist)

What's Wrong or Missing?

There is a logical contradiction between the general summary and the specific behavior rules.

1. The summary claims a Logical OR relationship ("matches either a name entry, a command entry, or a URL pattern").
2. The specific rules and examples demonstrate a conditional override/Strict Mode relationship ("Stdio servers cannot pass by name alone when command restrictions are present").

The example shows a server named "github" being blocked despite serverName: "github" being explicitly in the allowlist. This directly contradicts the statement that a server passes if it matches "either a name entry...". This is a critical security documentation issue because an administrator might rely on the "Either/OR" summary and assume name-based allowlisting is sufficient, not realizing that adding a single command restriction elsewhere in the policy invalidates name-based matching for Stdio servers.

Suggested Improvement

The "Important notes" section should be rewritten to accurately reflect the strict validation logic for Stdio servers when command restrictions are present.

Suggested text:

Important notes: Option 1 and Option 2 can be combined: If managed-mcp.json exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the managed servers themselves. Denylist takes absolute precedence: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist. Evaluation Logic: Remote Servers: Pass if they match either a name entry OR a URL pattern. * Stdio Servers: Pass if they match a name entry, UNLESS serverCommand entries exist in the allowlist. If any command restrictions are present, Stdio servers must match a specific command entry; name matching alone is ignored in this mode.

Impact

High - Prevents users from using a feature

Additional Context

This ambiguity makes it difficult to configure secure managed-settings.json files without trial and error. The current documentation implies a permissive policy that does not match the restrictive behavior described in the examples.