Skip to content
← Back to release · 2.1.321
Improvements / v2.1.321

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' availableModels lists 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, and skillOverrides: entries merge by name, and the first-listed matching policy that sets a name supplies its value.
  • desktop keys: these merge by the rules for the base desktop block.

[!WARNING]

Policies can add up to looser rules than any one of them gives alone. For example, the match: {} policy sets sandbox.enabled: true, one group's policy sets permissions.allow: ["Bash"], and another group's sets sandbox.enabled: false. A user in both groups receives Bash allowed with the sandbox off. In this case, list the policy that allows Bash first, and copy the match: {} policy's whole sandbox block into it.

With layered, the gateway refuses to start on some settings, including these:

  • A ! pattern: a ! negation in a Read or Edit rule in any policy's permissions.deny or permissions.ask list, the match: {} policy's included
  • A limit on hooks outside the catch-all: disableAllHooks, allowedHttpHookUrls, or httpHookAllowedEnvVars in any policy other than match: {}

Documentation snapshot · 2026-11-20

Change details