Layer managed MCP servers across matches
CHANGELOG · original
Changed policy_mode: layered in the Claude apps gateway: managed MCP servers now add up over every matching policy, match: {} included, so a gateway already on it serves more after the upgrade Open official changelog ↗ Documentation
Documentation excerpt
Apply every matching policy
A user who matches several role policies gets only the first unless you set policy_mode: layered beside policies. With layered, every policy that matches the user applies, down to the first match: {} policy.
policy_mode requires Claude Code v2.1.316 or later on the gateway server. A gateway on a version that lacks it refuses to start when it finds the key. Upgrade every replica before you add the key, and remove the key before you roll back to an earlier version. This example has one group that loses WebFetch and one that gains Opus:
managed:
policy_mode: layered
policies:
- match: { groups: [no-web] }
cli:
permissions: { deny: ["WebFetch"] }
- match: { groups: [opus-users] }
cli:
availableModels: [opus, sonnet]
- match: {}
cli:
availableModels: [sonnet]
enforceAvailableModels: true
The table shows what a user in both no-web and opus-users receives under the default, first_match, and under layered.
| Setting | first_match |
layered |
|---|---|---|
availableModels |
sonnet |
opus, sonnet |
enforceAvailableModels |
true |
true |
permissions.deny |
WebFetch |
WebFetch |
The gateway merges each matching policy onto the ones listed below it, by the same merge rules as the base layer:
- Allow-lists, single values, and blocks such as
sandbox: each comes whole from the first-listed matching policy that sets it, so two groups'availableModelslists don't add up. - Deny-lists and hook arrays: these add up across every matching policy, so a user in two groups gets both groups' deny rules.
env,modelOverrides, andskillOverrides: entries merge by name, and the first-listed matching policy that sets a name supplies its value.desktopkeys: these merge by the rules for the basedesktopblock.
[!WARNING]
Policies can add up to looser rules than any one of them gives alone. For example, the
match: {}policy setssandbox.enabled: true, one group's policy setspermissions.allow: ["Bash"], and another group's setssandbox.enabled: false. A user in both groups receivesBashallowed with the sandbox off. In this case, list the policy that allowsBashfirst, and copy thematch: {}policy's wholesandboxblock into it.
With layered, the gateway refuses to start on some settings, including these:
- A
!pattern: a!negation in aReadorEditrule in any policy'spermissions.denyorpermissions.asklist, thematch: {}policy's included - A limit on hooks outside the catch-all:
disableAllHooks,allowedHttpHookUrls, orhttpHookAllowedEnvVarsin any policy other thanmatch: {}
Documentation snapshot · 2026-11-20