Claude Code Managed Settings: Enterprise Policy, Hooks and MCP

Claude Code Managed Settings: Enterprise Policy, Hooks and MCP

To apply one Claude Code policy across your whole company, use managed settings: a policy file that IT installs on company machines, or delivers through the admin console, and that takes precedence over user and project settings. In it you define permission rules, mandatory hooks and which MCP servers are accepted. The safest path is to start with a few rules, test with a small group and expand based on evidence.

Key takeaways

• Managed settings sit above user and project settings, so a developer cannot undo them alone.
• Permissions use three verbs: deny, ask and allow. The deny list is the part that protects the most.
• Hooks turn process rules into automatic checks, and you can restrict execution to hooks defined by the policy.
• MCP servers can be delivered as a closed list or controlled with allow and block lists.
• A good policy starts small, is tested in a pilot and grows from real friction, not from fear.

What managed settings are and why a company needs them

Claude Code reads settings from several levels: user, shared project, local project and, above all of them, the managed level. That last level exists for the organization. When a value is set there, it wins over whatever a person wrote on their own computer or in the repository.

Without that level, each developer decides alone what the agent can read, run and connect to. That works for a team of two. In a company with several teams, contractors and repositories that hold customer data (and are therefore subject to privacy law such as Brazil's LGPD), the result is a set of configurations that is impossible to audit.

The goal is not to block work. It is to set a common floor: what never happens, what always needs confirmation and what is freely allowed. Each team can add stricter rules in its own projects, but it cannot loosen the floor.

A note on method: Claude Code changes quickly. Key names, file locations and distribution options shift over time. Treat this article as a roadmap and confirm the details in the official Claude Code settings documentation before you deploy.

Where the policy lives and how it is delivered

The documentation describes two main paths. The first is a local policy file called managed-settings.json, installed in a system directory that requires administrator privileges to edit. There is one location for macOS, another for Linux and WSL, and another for Windows. The exact paths are in the documentation, and it is better to copy them from there than to memorize them.

The second path is server-side delivery through the admin console of the organization account, when your plan offers that feature. The advantage is that you do not have to install a file machine by machine. The drawback is that it depends on the feature and the plan, which you need to verify in your own account.

For the local file, the usual company pattern is to distribute it with the same tool that already manages your machines: Intune, Jamf, Ansible, Group Policy or a provisioning script. The file should have a clear owner, be versioned in an internal repository and be reviewed by at least two people, because one wrong line affects everyone.

A practical question before you start: who has the authority to change the policy? If the answer is "anyone in IT", name one owner and set up a request process. A policy without an owner turns into a pile of exceptions.

Permissions: what to deny, ask and allow

The permissions block accepts three lists: deny, ask and allow. The golden rule is that deny wins. If an action is on the deny list at the managed level, no setting below it can release it.

Start with the deny list, thinking about irreversible damage and data leaks:

• Reading secret files, such as .env files, private keys and credential directories.
• Network commands that send content out without review, such as curl and wget used to upload data.
• Destructive system operations, such as recursive deletion in broad directories.
• Writing directly to protected branches, if your workflow requires pull request review.

Then build the "ask" list: actions that are legitimate but deserve a human look, such as publishing code, changing infrastructure or running database migrations. Finally, keep the allow list short and limited to what is routine and safe, such as running the test suite and the linter.

Another point to evaluate is the mode that skips permission confirmations. The documentation provides an option to disable it at the managed level. On machines that touch customer data, turning it off makes sense. In an isolated lab, it may be acceptable. Decide by environment, not by preference.

Permissions are one layer, not the whole defense. To combine them with isolation and secrets handling, see Claude Code security: permissions, sandbox and secrets for teams. For the principle behind the deny list, the general reference is the OWASP authorization cheat sheet: least privilege and deny by default for anything sensitive.

Hooks: process rules that always run

Hooks are commands that Claude Code runs at defined moments, such as before or after using a tool. At the managed level, they become controls that nobody has to remember to trigger.

Common uses in companies:

• Before a write or command, check whether the target is in a forbidden path and block it if so.
• After editing files, run formatting and static checks to keep the repository standard.
• Record in an internal log which tools were called, for auditing and to understand real usage.
• Detect secret patterns in content before it is written.

The documentation also provides a restriction so that only hooks defined by the managed policy are executed. This matters because a hook is code running on the person's machine. If any repository can bring its own hooks, a cloned project from a doubtful source becomes a risk vector. By allowing only policy hooks, you trade flexibility for predictability, and in a corporate environment that trade is usually worth it.

Beware of excess. A slow hook, or one that fails for obscure reasons, irritates the team, which then looks for workarounds. Each hook should have a clear purpose, an understandable error message and an owner. If you also want to standardize team instructions and commands, look at Claude Code plugins for teams, which handle distribution of standards that are not security policy.

MCP servers: closed list or allow list

MCP servers give the agent access to external systems: databases, CRMs, ticketing tools, repositories. This is where risk grows fastest, because each server adds tools and data access. If the concept is new to you, the introduction to the Model Context Protocol and the Claude Code MCP documentation are the place to start.

There are two documented approaches for the managed level:

• Closed list: IT distributes a managed MCP server file (managed-mcp.json). Users receive exactly that set, and the documentation indicates this gives exclusive control, so people cannot add their own.
• Allow and block lists: the policy defines which servers can be used and which are forbidden, and users still configure whatever is permitted. A block usually takes precedence over an allow.

How to choose:

• Few systems, sensitive data, a team with little experience: closed list.
• Many technical teams with different needs: allow list, with a review of each new server.
• A server that writes to production systems: require confirmation through permissions and, if possible, start with read-only credentials.

Before approving any server for the list, audit it. How to audit an MCP server before installing it at your company offers a checklist, and Configure MCP in Claude Code: local, project and user scopes explains how scopes relate to the policy.

A staged rollout plan

A roadmap that avoids the most common mistake, which is publishing a huge policy all at once:

• Inventory: find out who uses Claude Code, in which repositories, with which MCP servers and with what kind of data. Without this, the policy is a guess.
• Minimum floor: write a file with a few denials (secrets, destructive commands), the hook restriction and the approved MCP list.
• Test on a staging machine: confirm that each rule blocks what it should and does not block normal workflow. Also test precedence by trying to override the rule in a user setting.
• Pilot with a small group: pick a team willing to report friction. Define what you will watch, such as exception requests and wrongful blocks.
• Adjust: turn each recurring exception into a deliberate decision: widen the policy, create a useful hook or keep the block.
• Gradual expansion: roll out to the other teams with a support channel and a policy owner.
• Periodic review: reassess the policy when Claude Code changes version or when a new integrated system comes in.

Illustrative scenario: a software company with three teams maintains repositories with customer data. IT publishes a policy that denies reading environment files, requires confirmation for deploy commands and accepts only two MCP servers, the ticketing server in read mode and the internal documentation server. In the first week of the pilot, the data team asks for a database server. Instead of approving it on the spot, IT audits the server, creates a read-only credential and adds it to the list. The policy grew from proven need, not from anticipation.

To follow the pilot without turning the tool into surveillance of people, read how to measure AI productivity without surveillance on your team. The hook log should serve to audit the tool and investigate incidents, not to rank developers.

How the map, limit, pilot and transfer method applies

The method we use in AI projects fits well here. Map is the inventory of usage, repositories, data and integrations. Limit is the permission floor, the hook restriction and the MCP list. Pilot is the rollout to a small group, with an agreed success criterion, for example "wrongful blocks go down and no secret is read". Transfer is handing over the policy with an owner, an exception process and a review routine, so the company can maintain it without depending on whoever wrote it.

After the pilot, the decision is simple: expand, adjust or stop. Stopping is also a valid outcome, if the environment cannot carry the risk.

Frequently asked questions

Do managed settings stop a developer from changing permissions? They take precedence over user and project settings, so the developer cannot loosen what the policy defined. They can still add stricter rules at their own level. Test precedence in staging to confirm the behavior in your version.

Do I need a file on every machine? If you use the local policy file, yes, and the best approach is to distribute it with the device management tool your company already has. If your plan offers delivery through the admin console, you avoid that distribution. Check the documentation and your account to see what is available.

Should I block all MCP servers by default? For environments with sensitive data, it is a good starting point, as long as there is a fast path to request and audit new servers. A total block with no exception process creates hidden, parallel usage. A block with a short approval queue keeps the team inside the policy.

Does the policy replace team training? No. The policy limits damage, but people still decide what to paste into a prompt and what to accept as an answer. Combine the technical configuration with short usage guidance, aligned with your company policy for employee AI tool use, and review both as the tool evolves.

Sources

• Claude Code: documentação de configurações
• Claude Code: documentação de MCP
• Model Context Protocol: introdução
• OWASP: guia de autorização