What you will be able to do
- Choose an API provider for a team rollout of Claude Code and justify the choice
- Place a setting in the right scope: user, shared project, project local, or managed
- Pick a managed-settings delivery mechanism and predict which sessions it reaches and how fast changes arrive
Key concept
Managed settings tier — The organization-controlled layer of Claude Code configuration. Whatever an admin deploys there applies to every machine it reaches, and a developer's own user, project or local settings cannot override it, apart from a handful of security-sensitive exceptions.
1.First decision: where Claude Code authenticates
Configuring Claude Code for a team starts with a set of decisions, not with a config file. Anthropic's admin setup guide lists them in order: choose your API provider, decide how settings reach devices, decide what to enforce, set up usage visibility, and review data handling. This page covers the first two decisions. The enforcement controls get their own page.
The provider decides where Claude Code authenticates and how usage is billed. Anthropic recommends Claude for Teams or Enterprise by default. A team that already standardises on a cloud platform can route through that platform instead, and inherit the compliance controls and billing it already has.
| Provider | Choose this when |
|---|---|
| Claude for Teams / Enterprise | You want Claude Code and claude.ai under one per-seat subscription with no infrastructure to run (the default recommendation) |
| Claude Console | You are API-first or want pay-as-you-go billing |
| Amazon Bedrock | You want to inherit existing AWS compliance controls and billing |
| Google Cloud's Agent Platform | You want to inherit existing GCP compliance controls and billing |
| Microsoft Foundry | You want to inherit existing Azure compliance controls and billing |
The provider choice affects more than billing. As the delivery section below shows, the claude.ai admin console, one of the policy channels, requires a Claude for Teams or Enterprise plan. A team on Bedrock or the Console has to deliver policy some other way.
2.Four settings scopes and who each one reaches
Every Claude Code setting lives in a scope, and the scope decides who it affects. User settings in ~/.claude/settings.json follow one developer across every project on their machine. Shared project settings in .claude/settings.json are meant for team permissions, hooks, plugins and the environment variables the project needs. A shared project file reaches teammates and cloud sessions only when it is committed to version control. Until then it is just a file on one disk.
Project local settings in .claude/settings.local.json hold personal overrides for one project. Claude Code writes to this file itself: when a developer answers a Bash permission prompt with "Yes, and don't ask again", Claude Code saves that approval there as an allow rule. The first time it writes the file in a git repository, it also adds the file to the developer's global git excludes, so the file stays out of commits. A file created by hand has to be gitignored manually.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}The fourth scope is managed. A managed-settings.json file, an MDM policy or server-managed settings from the claude.ai console all belong to it. Developers do not create or edit it. The organization deploys it, and it reaches every project on every machine it is deployed to, plus any session where someone signs in with the organization account. Use the managed scope for security policy and compliance requirements, and the shared project file for conventions a team reviews like code.
A platform team wants every engineer's Claude Code session to inherit a shared set of Bash allow rules and MCP server configuration that the team maintains and reviews through normal code review, while still letting each engineer add personal overrides that never leave their own machine. Where should the team place the shared rules, and where should individual overrides go?
Correct answer: A — Commit the shared rules to .claude/settings.json in the project, and let engineers add personal overrides in .claude/settings.local.json
- A. Correct. Project settings at .claude/settings.json are git-committed and shared with the team, going through code review, while .claude/settings.local.json is gitignored and machine-specific, exactly matching the two requirements.
- B. Incorrect. User settings at ~/.claude/settings.json apply only to the individual who owns that home directory and are never shared through version control, so they cannot serve as the team's reviewed, shared configuration.
- C. Incorrect. Managed settings are for organization-wide policy that cannot be overridden and are deployed via IT/MDM tooling, not through the team's normal project code review workflow described in the scenario.
- D. Incorrect. .mcp.json only covers MCP server definitions, not Bash permission rules, and ~/.claude.json is a per-user file that does not track with individual projects the way settings.local.json does.
Sources3
3.Getting managed policy onto machines
Once you know a setting belongs in the managed scope, you still have to get it onto machines. There are four delivery mechanisms, and the admin setup guide ranks them by priority. Server-managed settings, configured in the claude.ai admin console or on a self-hosted Claude apps gateway, rank highest. Next come macOS plist and Windows HKLM registry policy, then file-based managed-settings.json. The Windows user registry (HKCU) ranks lowest. Each mechanism also has its own refresh cadence.
| Mechanism | How you deliver it | When Claude Code reads it | Use it when |
|---|---|---|---|
| Server-managed settings | claude.ai admin console, or a self-hosted Claude apps gateway | Fetched at startup and polled hourly | You want one place to change policy without touching each machine |
| MDM or OS-level policy | macOS configuration profile or Windows HKLM registry value via Jamf, Intune, Group Policy | Read at startup and checked for changes every 30 minutes | You already manage devices with MDM or Group Policy |
| File-based | managed-settings.json in a system directory on each machine | Read at startup and reloaded when a file changes | Machines without MDM, Linux hosts, or images you build yourself |
| HKCU registry, Windows and WSL | Windows HKCU registry value | Read at startup and checked for changes every 30 minutes | You can't write the machine-level HKLM key |
The file-based paths are fixed: /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows. Claude Code does not read the legacy C:\ProgramData path. The same system directory can also hold an optional managed-settings.d/ drop-in directory, and the files there merge: a single value in a later file replaces the earlier one, while lists such as permissions.deny combine with duplicates removed.
Server-managed settings have their own requirements: a Claude for Teams or Enterprise plan, the Owner or Primary Owner role to view and edit the configuration, and network access to api.anthropic.com. They also have a limit. Every user in the organization gets the same configuration, and per-group configurations are not supported yet.
Only server-managed settings. An Anthropic-hosted session does not read a device's MDM profile or file, so policy for cloud sessions has to be set in the claude.ai admin console (or the gateway). Cowork sessions are a separate exception in the other direction: Claude Code in Cowork never fetches server-managed settings, even for Team or Enterprise sign-ins, so Cowork policy has to be on the device or comes from nowhere.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A managed-settings.json pushed to every laptop through MDM also governs a developer's Claude Code sessions in Anthropic-hosted cloud environments.Why is that wrong?
Device policy stays on the device. Of the managed sources, only server-managed settings from the claude.ai console reach a cloud session.
Covered in Getting managed policy onto machines
2.In the claude.ai admin console, you can give the platform team looser server-managed settings than the rest of engineering.Why is that wrong?
Server-managed settings are organization-wide. Per-group configurations are not supported, so different policies per team need another mechanism, such as device policy.
Covered in Getting managed policy onto machines
3.Because a user signs in to Cowork with a Team or Enterprise account, the admin console's server-managed settings apply to their Cowork sessions.Why is that wrong?
Claude Code in a Cowork session never fetches server-managed settings. On the user's machine it reads the device's MDM policy and managed settings file, so deploy the policy there.
Covered in Getting managed policy onto machines
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/admin-setupOfficial docs
“You want Claude Code and claude.ai under one per-seat subscription with no infrastructure to run. This is the default recommendation.”
↩︎ First decision: where Claude Code authenticates“claude.ai admin console, or a self-hosted Claude apps gateway for gateway sign-ins”
↩︎ Getting managed policy onto machines - 2.
“Claude for Teams or Claude for Enterprise plan”
↩︎ First decision: where Claude Code authenticates“The Owner or Primary Owner role in your Claude organization, to view and edit the configuration”
↩︎ Getting managed policy onto machines“Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.”
↩︎ Exam trap 2 - 3.https://code.claude.com/docs/en/settingsOfficial docs
“Team permissions, hooks, plugins, and the environment variables the project needs”
↩︎ Four settings scopes and who each one reaches“It reaches your teammate’s clone and the cloud session only if you commit the file to version control”
↩︎ Four settings scopes and who each one reaches“Claude Code saves that permission approval here as an allow rule.”
↩︎ Four settings scopes and who each one reaches“Everyone your organization deploys it to; nothing you set overrides it, apart from a few security-sensitive exceptions”
↩︎ Key concept“Only server-managed settings reach the cloud session”
↩︎ Exam trap 1 - 4.https://code.claude.com/docs/en/managed-settingsOfficial docs
“Read at startup and checked for changes every 30 minutes”
↩︎ Getting managed policy onto machines“Lists, such as permissions.deny or sandbox.network.allowedDomains: the two lists combine, with duplicates removed”
↩︎ Getting managed policy onto machines“Claude Code never fetches server-managed settings from the claude.ai admin console, even when the user signs in with a Team or Enterprise account”
↩︎ Exam trap 3