[DOCS] Managed MCP allowlist and denylist docs omit `${VAR}` reference matching behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

allowedMcpServers / deniedMcpServers predicates that contain ${VAR} references

Current Documentation

The managed MCP page currently says:

"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"

It documents exact command matching and URL wildcard matching, and it separately says MCP configurations can use ${VAR} expansion for per-user credentials. The allowlist/denylist predicate section does not say how ${VAR} references inside policy entries are matched.

What's Wrong or Missing?

Claude Code v2.1.166 fixed managed-settings allowedMcpServers / deniedMcpServers predicates not matching when they use ${VAR} references. That implies ${VAR} references are a supported or at least recognized shape inside policy predicates.

The current docs tell administrators how URL, command, and name predicates match, but omit:

• whether ${VAR} is valid in serverUrl and/or serverCommand predicates
• when variable references are expanded
• whose environment supplies the value
• whether missing variables fail closed, warn, or leave the predicate unmatched
• how this differs from ${VAR} expansion inside .mcp.json server definitions

Without this, administrators cannot safely write managed policies that depend on per-user or per-machine values, and they cannot reason about why a predicate with ${VAR} did or did not match.

Suggested Improvement

Add a subsection under "Match servers by URL, command, or name":

Policy predicates may include `${VAR}` references in supported fields. Claude Code resolves them before comparing configured servers against `allowedMcpServers` and `deniedMcpServers`. Document exactly which fields support references, which environment is used, and what happens when a variable is unset.

Add examples for both allowlist and denylist policy if supported:

{
"allowedMcpServers": [
{ "serverUrl": "https://${MCP_HOST}/mcp" }
],
"deniedMcpServers": [
{ "serverCommand": ["node", "${UNAPPROVED_MCP_PATH}"] }
]
}

If ${VAR} references are intentionally allowed only in server definitions and not policy predicates, update the docs to say that explicitly and explain the v2.1.166 behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/managed-mcp | 121-151 | Defines allowlist/denylist predicate keys but not ${VAR} behavior |
| https://code.claude.com/docs/en/managed-mcp | 153-172 | Explains exact command and URL wildcard matching but not variable expansion |
| https://code.claude.com/docs/en/settings | 176, 199 | Lists allowedMcpServers and deniedMcpServers without variable-reference caveats |
| https://code.claude.com/docs/en/mcp | 496-510 | Documents MCP config environment expansion, which should be cross-referenced or distinguished |

Total scope: 3 pages affected.

Version reference: Claude Code v2.1.166 release notes state that managed-settings allowedMcpServers / deniedMcpServers predicates now match when they use ${VAR} references.