Loosen allowedMcpServers env-var filtering
CHANGELOG · original
Changed allowedMcpServers to stop filtering managed-mcp.json stdio servers that use ${VAR} only in env: one your allowlist left out now loads on upgrade; use deniedMcpServers to keep it off Open official changelog ↗ Documentation
Documentation excerpt
allowedMcpServers
Allowlist the MCP servers people can add. Claude Code blocks any server that doesn't match an entry wherever it's defined, including plugin servers, servers a user passes with --mcp-config, and servers from claude.ai.
Built-in servers such as Claude in Chrome, the ide server Claude Code connects to in a running VS Code or JetBrains IDE, and servers the CLI itself configures are exempt from the allowlist, and the denylist still applies to them. On Claude Code v2.1.268 or later, a Claude Tag session's Slack tools are also exempt from the allowlist, and the denylist still applies to them. In-process type: "sdk" servers are exempt from both lists; the app that started the session registers them.
Servers your organization delivers are also exempt from the allowlist, and the denylist still applies to them. The exemption covers every managedMcpServers entry, and any managed-mcp.json entry whose values use no ${VAR} expansion outside env. See How a server is evaluated for the full check order. Before v2.1.259, servers from managed-mcp.json had to match too.
- Scope:
Any file. For servers users add, entries from every file merge into one allowlist unlessallowManagedMcpServersOnlyis set. To keep users from adding entries, deploy both keys in managed settings. - Type: array of objects, each with exactly one key. Use
serverName, a string limited to letters, numbers, hyphens, and underscores;serverCommand, an array of the command and its arguments matched exactly; orserverUrl, a URL pattern with*wildcards - Default: unset, so every server is allowed; an empty merged list blocks every server users add
This example allows only the stdio server that the listed npx command starts:
{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
]
}
A deniedMcpServers entry takes precedence, so a server on both lists is blocked. Once the list contains any serverCommand entry, a stdio server must match a serverCommand entry, and once it contains any serverUrl entry, a remote server must match a serverUrl entry: a serverName match no longer admits that kind of server. See Policy-based control with allowlists and denylists.
Documentation snapshot · 2026-11-20