Skip to content
← Back to release · 2.1.305
Improvements / v2.1.305

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 unless allowManagedMcpServersOnly is 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; or serverUrl, 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

Change details