Configure server-managed settings (public beta)

Centrally configure Claude Code for your organization through server-delivered settings, without requiring device management infrastructure.

Server-managed settings allow administrators to centrally configure Claude Code through a web-based interface on Claude.ai. Claude Code clients automatically receive these settings when users authenticate with their organization credentials.

This approach is designed for organizations that do not have device management infrastructure in place, or need to manage settings for users on unmanaged devices.

Requirements

To use server-managed settings, you need:

• Claude for Teams or Claude for Enterprise plan
• Claude Code version 2.1.38 or later for Claude for Teams, or version 2.1.30 or later for Claude for Enterprise
• Network access to api.anthropic.com

Choose between server-managed and endpoint-managed settings

Claude Code supports two approaches for centralized configuration. Server-managed settings deliver configuration from Anthropic's servers. Endpoint-managed settings deploy a managed-settings.json file to system directories via MDM (mobile device management).

If your devices are enrolled in an MDM or endpoint management solution, endpoint-managed settings provide stronger security guarantees because the settings file can be protected from user modification at the OS level.

Configure server-managed settings

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

Verify settings delivery

To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the security approval dialog, the user sees a prompt describing the managed settings on startup. You can also verify that managed permission rules are active by having a user run /permissions to view their effective permission rules.

Access control

The following roles can manage server-managed settings:

• Primary Owner
• Owner

Restrict access to trusted personnel, as settings changes apply to all users in the organization.

Current limitations

Server-managed settings have the following limitations during the beta period:

• Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.
• MCP server configurations cannot be distributed through server-managed settings.

Settings delivery

Settings precedence

Server-managed settings and endpoint-managed settings both occupy the highest tier in the Claude Code settings hierarchy, and user or project settings cannot override them. When both are present, server-managed settings take precedence and the local managed-settings.json file is not used.

Fetch and caching behavior

Claude Code fetches settings from Anthropic's servers at startup and polls for updates hourly during active sessions.

First launch without cached settings:

• Claude Code fetches settings asynchronously
• If the fetch fails, Claude Code continues without managed settings
• There is a brief window before settings load where restrictions are not yet enforced

Subsequent launches with cached settings:

• Cached settings apply immediately at startup
• Claude Code fetches fresh settings in the background
• Cached settings persist through network failures

Claude Code applies settings updates automatically without a restart, except for advanced settings like OpenTelemetry configuration, which require a full restart to take effect.

Security approval dialogs

Certain settings that could pose security risks require explicit user approval before being applied:

• Shell command settings: settings that execute shell commands
• Custom environment variables: variables not in the known safe allowlist
• Hook configurations: any hook definition

When these settings are present, users see a security dialog explaining what is being configured. Users must approve to proceed. If a user rejects the settings, Claude Code exits.

Platform availability

Server-managed settings require a direct connection to api.anthropic.com and are not available when using third-party model providers:

• Amazon Bedrock
• Google Vertex AI
• Microsoft Foundry
• Custom API endpoints via ANTHROPIC_BASE_URL or LLM gateways

Audit logging

Audit log events for settings changes are available through the compliance API or audit log export. Contact your Anthropic account team for access.

Audit events include the type of action performed, the account and device that performed the action, and references to the previous and new values.

Security considerations

Server-managed settings provide centralized policy enforcement, but they operate as a client-side control. On unmanaged devices, users with admin or sudo access can modify the Claude Code binary, filesystem, or network configuration.

To detect runtime configuration changes, use ConfigChange hooks to log modifications or block unauthorized changes before they take effect.

For stronger enforcement guarantees, use endpoint-managed settings on devices enrolled in an MDM solution.

See also

Related pages for managing Claude Code configuration:

• Settings: complete configuration reference including all available settings
• Endpoint-managed settings: file-based managed settings deployed by IT
• Authentication: set up user access to Claude Code
• Security: security safeguards and best practices