Server-Managed Claude Code Settings Rollout

TL;DR

Server-managed settings let Teams and Enterprise admins publish Claude Code configuration JSON from Claude.ai. Clients fetch policy at startup and poll hourly. Settings occupy the highest precedence tier. Use /permissions to verify delivery and forceRemoteSettingsRefresh when startup must block until fresh policy loads.

Prerequisites & Requirements

• {"task": "Plan eligibility", "description": "Teams or Enterprise with supported Claude Code versions"}
• {"task": "Admin role", "description": "Primary Owner or Owner can edit Managed settings"}
• {"task": "Network path", "description": "Clients reach api.anthropic.com"}
• {"task": "Pilot users", "description": "Small group validates policy before org-wide rollout"}

Core Concepts Explained

Server-managed vs endpoint-managed

Official docs compare server-managed delivery (Anthropic servers at authentication) with endpoint-managed plist/registry files for MDM-enrolled devices. MDM provides stronger OS-level enforcement.

Delivery precedence

Server-managed settings are checked before endpoint-managed sources. The first managed source delivering a non-empty configuration wins; sources do not merge.

Caching behavior

First launch without cache fetches asynchronously with a brief window before restrictions apply. Cached settings apply immediately on later launches while background refresh runs.

Step-by-Step Implementation Guide

1. Open admin console. Claude.ai → Admin Settings → Claude Code → Managed settings.

2. Draft JSON policy. Example permission deny list from official docs:

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

1. Save and communicate restart. Users receive updates on next startup or hourly polling; ask pilot users to restart and approve security dialogs for hooks or custom env vars when present.

2. Verify delivery. Have users run /permissions to view effective managed rules; use /status to see which managed source is active.

3. Optional fail-closed startup. Add "forceRemoteSettingsRefresh": true when the CLI must block until a fresh fetch succeeds (requires reliable api.anthropic.com access).

4. Document limitations. Settings apply uniformly to all org users; per-group configs are not supported yet; managed-mcp.json files are not distributed—use allowedMcpServers / deniedMcpServers keys instead.

5. Plan audit access. Request compliance API or audit log export through your Anthropic account team for change tracking.

Troubleshooting

User still has old permissions

Wait for hourly poll or restart Claude Code; check /status for active managed source.

Startup exits with forceRemoteSettingsRefresh

Confirm api.anthropic.com reachable; users can run claude auth login exempt from check per v2.1.139 docs.

Settings bypassed unexpectedly

Third-party providers (Bedrock, Vertex, Foundry, custom ANTHROPIC_BASE_URL) bypass server-managed settings per platform availability section.

Source Verification Notes

Verified against https://code.claude.com/docs/en/server-managed-settings on 2026-06-16:

• Requires Teams/Enterprise and Claude Code 2.1.38+ (Teams) or 2.1.30+ (Enterprise).
• Admin console path: Admin Settings > Claude Code > Managed settings.
• Fetch at startup with hourly polling; cached at ~/.claude/remote-settings.json.
• Hooks, shell commands, and non-allowlisted env vars trigger security approval dialogs.
• forceRemoteSettingsRefresh blocks startup until fresh fetch when enabled.
• Invalid entries are stripped with tolerant parsing on v2.1.169+.

Duplicate Check

Complements enterprise settings and permissions guides. No existing guide walks through server-managed settings admin console rollout and delivery verification using official server-managed-settings documentation.

References

• Configure server-managed settings - https://code.claude.com/docs/en/server-managed-settings