Claude Code managed settings: enforce a team policy

Short answer: a managed policy is a settings file an administrator deploys to /etc/claude-code/managed-settings.json on Linux, /Library/Application Support/ClaudeCode/ on macOS or C:\Program Files\ClaudeCode\ on Windows. It beats every other settings file and command-line flag, so it is where rules that must hold on every machine belong.

Project settings are a suggestion: anyone can override them in their own settings.local.json. When a rule has to hold on every machine (no reading .env, only approved MCP servers, a fixed set of models), it belongs in a managed policy. That is a settings file an administrator deploys, and nothing a developer writes can override it.

#Where does managed-settings.json live?

These are system paths, so writing them needs administrator rights. That is the point: a person cannot quietly edit their own policy. Deploy the file with whatever you already use to manage machines.

#Which settings file wins?

Claude Code reads up to four settings files. Highest precedence first:

1. Managed: deployed by an administrator, cannot be overridden
2. Local: .claude/settings.local.json, this project, just you
3. Project: .claude/settings.json, this project, everyone
4. User: ~/.claude/settings.json, every project, just you

Most keys are "highest wins". Three combine across files instead: permissions, hooks and env. So a managed deny rule is added to everyone's own rules rather than replacing them. More in Where Claude Code keeps its settings, and which file wins.

#Which keys only work in a managed policy?

Some keys do nothing anywhere else. A few worth knowing:

Written in a user or project file, these are silently ignored. If a policy "does not work", check it is actually in the managed file.

Other keys an administrator reaches for, such as allowedMcpServers, deniedMcpServers, availableModels, forceLoginMethod and companyAnnouncements, work in any settings file. They belong in the managed policy all the same, because there nothing a developer writes can override them.

#How do I allowlist MCP servers?

allowedMcpServers takes a list of entries, each matching a server in exactly one way:

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-postgres"] }
  ],
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}

• serverUrl matches a remote server by URL. The strongest choice: copying the name does not let anyone serve from your host
• serverCommand matches a local server by its exact command and arguments
• serverName matches whatever the server was called. Anyone can name a server anything, so use it only when there is no other handle

Two details catch people out. An empty allowedMcpServers array means no server may load at all, which is a kill switch, not an unfinished list. And deniedMcpServers wins over the allow list and merges from every scope, so a person can always deny more for themselves.

#How do you roll it out safely?

A policy only binds on machines where the file is deployed. After rolling it out, check one machine actually picked it up: open Claude Code and confirm a denied action is refused.

#Where can you check this?

• Claude Code docs: Settings
• Claude Code docs: Server-managed settings
• Claude Code docs: Configure permissions

#How do you write the policy without mistakes?

Config Studio for Claude Code has a Managed policy surface listing every managed-only key, and an MCP allowlist builder that lints each entry as you write it (a name-only match, a missing matcher, two matchers in one entry). It also writes an APPROVED-MCP-SERVERS.md record of who approved what, which is the first thing asked in an audit.