Configure server-managed settings

​

Requirements

• Claude for Teams or Claude for Enterprise plan
• The Owner or Primary Owner role in your Claude organization, to view and edit the configuration
• Network access to api.anthropic.com

​

Choose between server-managed and endpoint-managed settings

​

Configure server-managed settings

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
        ]
      }
    ]
  }
}

​

Verify settings delivery

• The delivered settings loaded
• Your organization has no server-managed settings configured
• The fetch failed, with the cause and whether a cached policy still applies
• Claude Code skipped the fetch, with the reason. See Platform availability for the providers and configurations that skip it

​

Access control

• Primary Owner
• Owner

​

Managed-only settings

​

Current limitations

• Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.
• You can’t distribute a managed-mcp.json file through server-managed settings. Deliver the allowedMcpServers and deniedMcpServers policy keys there instead. On Claude Code v2.1.259 or later, you can also provide remote servers with managedMcpServers, which accepts http and sse servers only and doesn’t take exclusive control the way the file does. Claude Code reads a managed-mcp.json deployed at its system path separately from the managed settings tier, so the file still applies when server-managed settings are in effect.
• Settings restricted to OS-level policy sources, such as policyHelper and wslInheritsWindowsSettings, aren’t honored. Deploy them through MDM or a system managed-settings.json file instead. A policyHelper deployed that way runs only when its source is the one selected under precedence within the managed tier.

​

Settings delivery

​

Settings precedence

​

Per-key exceptions across managed sources

• Cross-source lock keys: a small set of keys, such as the sandbox allowlist locks, listed on the managed settings page. Claude Code honors them when any admin-controlled managed source sets them; the user-writable HKCU registry tier is excluded. When a policyHelper supplies managed settings, its output is the only source these checks read, apart from forceRemoteSettingsRefresh, which Claude Code reads from the admin sources directly at startup.
• The env block: apart from the telemetry unit and routing variables paired with a credential key, both covered below, it merges per key across the admin-controlled sources. For each environment variable, the highest-priority source defining it wins, and lower admin sources fill in variables the higher sources leave unset. An endpoint-managed env entry therefore applies whenever the server-managed configuration leaves that variable unset, or while a cached server value for it is withheld pending server confirmation. Requires Claude Code v2.1.223 or later. Before v2.1.223, Claude Code applies the selected source’s whole env block only.
  • Telemetry unit: the OTEL_EXPORTER_OTLP_* exporter keys, the OTEL_LOG_* content-capture toggles, OTEL_LOGS_EXPORTER, and the beta tracing variables ENABLE_BETA_TRACING_DETAILED and BETA_TRACING_ENDPOINT follow the highest source that sets any of them as a unit. A source that delivers the otelHeadersHelper credential key claims the unit too, but lands these variables only when it is the selected source: a source that isn’t selected but delivers the key contributes none of them and still blocks lower sources from filling them in. Either way, an exporter endpoint from one source can never pair with credentials from another.
  • Credential-paired routing: a source that pairs routing variables with a selected-source-only credential key, such as apiKeyHelper or otelHeadersHelper, contributes those routing variables only when it wins the slot.
• Gateway sign-in keys: Claude Code never reads forceLoginGatewayUrl or the "gateway" value of forceLoginMethod from server-managed settings, so selecting server-managed settings neither supplies a gateway sign-in nor hides one set in an MDM policy or managed settings file. The managedSourcesBehavior entry says which admin source on the machine supplies them.