CertSafari
    Anthropic Claude Certified Developer – Professional (CCDV-P)· Lessons

    Domain 8 · Lesson 25/25

    Managed settings for coding agents across an organization

    Organization-Wide Coding Agent Configuration

    20 min read
    2.5% of exam
    9 sources
    Published 19 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Explain why a managed setting holds when project files, user files and --settings JSON try to change it
    • Choose a delivery mechanism for managed policy based on how your fleet is run
    • Pick an MCP control pattern, from a fixed server set to an approved catalog, and predict which servers load
    • Route all Claude Code model traffic through a company gateway and export telemetry to your own collector using managed env values
    • Limit shared skills, agents, hooks and MCP servers to vetted plugin marketplaces

    Key concept

    Managed settings — Policy that an organization delivers to every Claude Code installation from the admin console, MDM, or a system-level file. It sits above project, user, local and command-line settings, so a developer cannot override any key it sets.

    1.Managed settings: the tier developers cannot override

    A security rule that lives in a repository only holds while nobody changes the repository. Suppose .claude/settings.json is committed with a deny on Read(./.env*). One engineer edits the file in their clone. Another starts a session with their own --settings JSON, and command-line settings override project and user files for that session. Neither person broke anything. Both used the settings stack exactly as designed. A rule that has to hold needs to sit in the one tier that stack never overrides, which is managed settings.

    Managed settings are policy your organization deploys, and they rank above every developer-controlled source. Nothing in a user's settings files or --settings JSON overrides a managed key. A flag such as --model can only choose from the models the organization allows. Agent SDK sessions load managed settings even when settingSources excludes the user, project and local files, so a headless script can't skip policy by narrowing its sources.

    A managed-settings.json that denies secret reads, disables bypass mode and makes managed rules the only source of permission rulesjson
    {
      "permissions": {
        "deny": [
          "Read(./.env)",
          "Read(./secrets/**)"
        ],
        "disableBypassPermissionsMode": "disable"
      },
      "allowManagedPermissionRulesOnly": true
    }

    That file does three jobs. The deny list blocks the reads. disableBypassPermissionsMode removes --dangerously-skip-permissions. allowManagedPermissionRulesOnly makes managed settings the only source of permission rules, so an allow rule a developer adds locally has no effect. The weaker fixes fail for the same structural reason. A nightly script that rewrites ~/.claude/settings.json still writes to a tier that --settings outranks. A CODEOWNERS rule protects the shared branch but not a developer's clone. A managed CLAUDE.md is behavioural guidance for Claude, not a rule the client enforces.

    How the policy reaches machines depends on how the fleet is run, and each mechanism picks up changes on its own schedule:

    Delivery mechanisms for managed settings
    MechanismDelivered throughWhen Claude Code reads itUse it when
    Server-managedclaude.ai admin console or a self-hosted Claude apps gatewayFetched at startup and polled hourlyYou want one place to change policy without touching each machine
    MDM / OS policymacOS com.anthropic.claudecode profile or HKLM\SOFTWARE\Policies\ClaudeCode via Jamf, Intune, Group PolicyAt startup, checked every 30 minutesYou already manage devices with MDM or Group Policy
    File-basedmanaged-settings.json in /etc/claude-code/, /Library/Application Support/ClaudeCode/, or C:\Program Files\ClaudeCode\At startup, reloaded when the file changesMachines without MDM, Linux hosts, images you build yourself
    HKCU registryHKCU\SOFTWARE\Policies\ClaudeCodeOnly when no admin document is present above itYou can't write the machine-level HKLM key

    Deploying more than one of these causes a common surprise. The sources rank in the order of the table, highest first: server-managed settings, then MDM or OS-level policy, then the managed-settings file, then the HKCU registry. The first three are admin sources. HKCU is user-writable, so Claude Code reads it only when no admin document sits above it. Under the default managedSourcesBehavior of "first-wins", Claude Code uses the highest-ranked source that delivers at least one policy key and ignores the rest, apart from a short list of keys it reads from every admin source. It shows no warning about the skipped sources. Only /status names the source it used and the ones it skipped. To combine sources, set "merge". With merge, lists union, locks take the strictest value, and on most other keys the higher-ranked source wins. Cloud sessions are a separate case. A session in an Anthropic-hosted environment doesn't read a device's MDM profile or file, so its policy must come from server-managed settings.

    Checkpoint 1 of 9· Fill the gap

    This managed-settings.json is meant to make sure that an allow rule a developer adds to their own settings has no effect. Which key completes it?

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

    Checkpoint 2 of 9· Check yourself

    An organization has no server-managed settings. It deploys a macOS MDM profile that denies Read(./secrets/**) and also a managed-settings.json that denies Read(./.env). It leaves managedSourcesBehavior unset. What does Claude Code enforce on a Mac that has both?

    Checkpoint 3 of 9· Exam question

    Kestrel Energy runs a grid-balancing platform, and its 300 engineers use Claude Code across dozens of repositories. Security committed a .claude/settings.json to every repository that denies Read(./.env*) and Bash(curl *). A quarterly audit still found engineers reading .env files that hold production credentials. Investigators traced it to two patterns: some engineers edited the file in their local clones and never pushed the change, and others start sessions with their own --settings JSON on the command line. Engineers have full control of their own home directories, and laptops are company-managed. Auditors will accept only a control that holds on every machine whatever an engineer edits, passes at launch, or sets in personal files, and that blocks the tool calls themselves rather than asking the agent to behave. What is the most direct way to make the deny rules hold?

    Sources12

    2.Controlling which MCP servers sessions can load

    MCP servers are the riskiest thing a developer can add on their own. A single claude mcp add or a line in a project .mcp.json can give the agent write access to a ticketing system or a production database. A rule asking Claude to decline unknown servers leaves the server loaded. A nightly audit only finds it after the fact. Managed MCP configuration works earlier: a server that fails policy never loads. Organizations choose from a range of patterns, from no MCP at all to no restrictions. The production lifecycle of the servers themselves is covered in production MCP and change management.

    MCP control patterns and what each one configures
    PatternEffectConfigure
    Disable MCPNo servers load except the exempt ones described belowmanaged-mcp.json with an empty server map
    Fixed deploymentEveryone gets your servers; servers users configure don't loadmanaged-mcp.json with the servers you want
    Provided serversEveryone gets your remote servers and keeps their ownmanagedMcpServers in managed settings
    Approved catalogUsers add approved servers they want; anything else is blockedallowedMcpServers + allowManagedMcpServersOnly: true
    Soft allowlistAllowlist that users can broaden in their own settingsallowedMcpServers without allowManagedMcpServersOnly
    Denylist onlyBlock known-bad servers, allow everything elsedeniedMcpServers

    Even the strictest pattern leaves a few servers loaded, because they come from the organization or the host application rather than from the user. They are the servers defined in managed-mcp.json, the servers you provide through managedMcpServers, in-process servers that the app which started the session registers (the VS Code extension's own server, or the connectors the desktop app delivers), the server Claude Code creates when a mod adds tools, and the built-in Claude in Chrome server when you allow it alongside the managed set. So an empty server map in managed-mcp.json leaves only these, and an empty allowedMcpServers array blocks every user-added server while these remain.

    The approved catalog is usually the right answer when users have added unvetted servers. It needs two keys working together. allowedMcpServers lists what is permitted. allowManagedMcpServersOnly: true makes the managed list the only one that counts. Without that lock, allowedMcpServers is a soft allowlist that any user can extend. Entries match on serverUrl (wildcards allowed), on serverCommand (the exact command and every argument, in order), or on serverName (exact match only). An empty allowedMcpServers array allows no user-added servers, only the exempt ones described above. Leaving the key unset allows every server.

    An approved catalog: only managed allowlist entries countjson
    {
      "allowManagedMcpServersOnly": true,
      "allowedMcpServers": [
        { "serverUrl": "https://api.githubcopilot.com/*" },
        { "serverUrl": "https://*.internal.example.com/*" }
      ]
    }

    deniedMcpServers merges in from every source and also applies to managed servers, so a user can block a server for themselves but can't add one the policy rejects. Users see the policy as concrete errors. claude mcp add for an unlisted server fails with not allowed by enterprise policy, and a server that is already configured but now blocked disappears from /mcp and claude mcp list. One deployment detail matters: managed-mcp.json takes exclusive control and can only be delivered as a file on the device, never through server-managed settings.

    Checkpoint 4 of 9· Match them up

    Match each managed MCP configuration to the effect it has on developers' sessions.

    Tap a term, then the definition that fits it.

    Checkpoint 5 of 9· Exam question

    Marlow Analytics runs its production revenue-reporting platform from company-managed laptops and a shared repository. Security finds that engineers have added an unvetted community MCP server with write access to the company ticketing system, declared in a project .mcp.json and through claude mcp add. On some machines the server exists only in an engineer's personal configuration, with no repository change at all. A written instruction telling Claude to use only approved integrations was already loaded, yet logs show the server connected and its write tools were called. Tickets were modified before anyone noticed, and Security requires that an unvetted server never connect at all. Security also requires a control that holds however a server is declared and that engineers cannot alter from their own or repository configuration. Which control most directly limits every session to the vetted servers?

    Sources3

    3.Routing all model traffic through a company gateway

    Finance and data-loss-prevention teams often need every model request to pass through one company LLM gateway. Two settings route Claude Code there. ANTHROPIC_BASE_URL sends API requests to the gateway instead of api.anthropic.com. A credential then authenticates each request, either apiKeyHelper, which runs a command to fetch the key, or a static ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY. How those credentials are issued and rotated belongs to identity and secrets management.

    Where the values are set decides whether they hold. A shell profile export or a committed project env block can be overridden by the developer, in the same way as the .env deny rule in the first section. Put the base URL and the helper in the managed env block and they become a managed key that user files and --settings cannot change. Two more managed controls narrow the remaining paths. allowedProviders lists which API providers a machine may use. A provider is the kind of endpoint a session talks to: anthropic (Anthropic's own API through a claude.ai or Console sign-in or an API key), bedrock, vertex, foundry, customEndpoint (the API sent to another host, such as an LLM gateway named by ANTHROPIC_BASE_URL), and gateway (a Cloud gateway sign-in). A session on an unlisted provider is refused at startup, at login, and when it next contacts the API, so a developer can't skip the gateway by signing in to Anthropic directly or switching to a cloud account. customEndpoint is admitted only for the exact URL a managed env block pins. The "gateway" value of forceLoginMethod sends people to a Cloud gateway sign-in instead of a first-party login. Under it, sessions authenticated by ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper are blocked at startup, and so is an API key saved by an earlier Console login, because a personal credential would otherwise stand in for the required sign-in. Monthly spend reconciliation and usage reports only show a bypass after it has happened. Only enforcement prevents it.

    Pointing at a gateway changes where policy comes from, and it depends on which kind of gateway the fleet uses. A Claude apps gateway is a self-hosted gateway that developers sign in to with /login. It can deliver their policy, so Claude Code still fetches remote settings through it. A third-party LLM gateway, such as LiteLLM, Kong or an internal proxy, is reached by setting ANTHROPIC_BASE_URL and supplying a key. It carries model requests, and when ANTHROPIC_BASE_URL points at it Claude Code skips the remote source and starts at the next one. If developers authenticate through a gateway sign-in screen, the fleet is in the first case. If they send a key from apiKeyHelper or an environment variable to a base URL, it is in the second, and its policy needs to be delivered by MDM or a managed file.

    Checkpoint 6 of 9· Check yourself

    A company's only managed policy is set in the claude.ai admin console. It now sets ANTHROPIC_BASE_URL on every machine to point at a third-party LLM gateway. What happens to that policy?

    Checkpoint 7 of 9· Exam question

    Nettle Bank runs its payments platform on Claude Code across roughly 300 engineers on managed laptops. Finance requires all model traffic to flow through the company LLM gateway for spend attribution and DLP. A quarterly audit found that several engineers still use personal API keys directly against the Anthropic API, both in interactive sessions and in scripts that call the SDK. Some of those sessions ran in repositories that already carry gateway settings, and others ran in scratch directories outside any company repository. Security has stated that detecting this bypass after the fact is not sufficient, because DLP inspection is skipped for every call that avoids the gateway. Which approach most directly closes that path?

    Sources452678

    4.Enterprise telemetry: your collector versus Anthropic-bound traffic

    Telemetry needs two separate decisions. The first is whether to export OpenTelemetry metrics and logs to your own collector, so you can see adoption and spend. The second is whether Claude Code may send Anthropic-bound usage metrics, error reports and surveys. Both are set through environment variables, and both belong in managed env so individual machines can't drift. What to do with the signals once they arrive is the subject of telemetry and instrumentation.

    Managed env block that turns on OpenTelemetry export to a company collectorjson
    {
      "env": {
        "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
        "OTEL_METRICS_EXPORTER": "otlp",
        "OTEL_LOGS_EXPORTER": "otlp",
        "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
        "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
      }
    }

    Setting the endpoint centrally also closes a gap. When managed settings set OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code removes every per-signal endpoint a developer has set, so nobody can send one signal to a different collector. The Anthropic-bound direction is the opposite switch, and two variables with different reach control it. DISABLE_TELEMETRY set to "1" in a managed env block is the telemetry opt-out: it stops telemetry going to Anthropic and leaves the rest of Claude Code's network behaviour alone. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is the broad switch. It turns off all nonessential network traffic, which includes auto-updates, telemetry, error reporting, the /feedback command, release notes and feature-flag fetching, and with feature flags gone, Remote Control becomes unavailable. Any non-empty value triggers it, even 0 or false. Choose DISABLE_TELEMETRY when the goal is only to stop telemetry. Choose the broad variable when the network must be quiet, and plan another update path, since auto-updates stop too.

    Checkpoint 8 of 9· Fill the gap

    Your organization wants Claude Code to stop sending telemetry to Anthropic on every machine. It does not want to change anything about exporting data to its own OpenTelemetry collector. Which environment variable completes this managed env block?

    {
      "env": {
        " ? ": "1"
      }
    }

    Sources9582

    5.A quality bar for shared skills, agents and MCP servers

    Once teams start sharing skills, subagents, hooks, slash commands and MCP servers, the governance question is which channel shared content may arrive through. Plugin marketplaces are the reviewable channel. A marketplace is a git repository or URL that the organization curates, so whatever review process you require happens before content is published there. Managed settings then make that marketplace the only way in.

    strictKnownMarketplaces limits which marketplace sources users can add and install fromjson
    {
      "strictKnownMarketplaces": [
        { "source": "github", "repo": "acme-corp/approved-plugins" },
        { "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" },
        { "source": "url", "url": "https://plugins.example.com/marketplace.json" }
      ]
    }

    Pinning a ref such as v2.0 means users install the version that was reviewed, not whatever is on the default branch. An empty strictKnownMarketplaces array blocks every marketplace, including Anthropic's official one, so the allowlist must contain the sources you actually want. Several other managed keys stop vetted content from being bypassed:

    • strictPluginOnlyCustomization blocks skills, agents, hooks and MCP servers from user and project sources. true locks all four, and an array names which ones.
    • blockedMarketplaces lists sources that are checked before download, so they never reach the filesystem.
    • disableSideloadFlags rejects --plugin-dir, --plugin-url, --agents and --mcp-config at startup, which closes the one-run sideload.
    • allowManagedHooksOnly restricts which hooks run, and allowedHttpHookUrls restricts where HTTP hooks can send data.
    • syncClaudeAiSkills and syncClaudeAiPlugins set to false stop skills and plugins that developers enabled on claude.ai from loading in Claude Code.
    • pluginTrustMessage adds your own text to the trust warning shown before a plugin installs.

    Checkpoint 9 of 9· Match them up

    Your organization reviews shared content before it publishes it to a curated marketplace. Developers must not be able to get around that review. Match each managed key to the gap it closes.

    Tap a term, then the definition that fits it.

    Sources62

    Practise it for real

    Deploy an approved MCP catalog as a managed file on a Linux test machine and confirm that Claude Code enforces it.

    1. 1.Write the approved-catalog JSON (allowManagedMcpServersOnly plus allowedMcpServers) to /etc/claude-code/managed-settings.json.

      Why: The file-based mechanism is read at startup and reloaded when the file changes, so you need no MDM to test it.

      You should see: The file exists in the system directory and only an administrator can write to it.

    2. 2.Start Claude Code and run /status.

      Why: /status names the managed source in use and any it skipped, which is how you catch a first-wins surprise.

      You should see: The setting sources list the managed settings file.

    3. 3.Run claude mcp add --transport http test https://example.com/mcp

      Why: The policy check rejects the command before any server is contacted, so the URL doesn't need to be real.

      You should see: Cannot add MCP server "test": not allowed by enterprise policy

    4. 4.Run claude mcp list.

      Why: Servers that were configured earlier but now fail policy should no longer appear.

      You should see: Only servers that match the allowlist are listed.

    Stuck? Get a nudge

    If a user's unapproved servers still appear, check the file path and the permissions on its parent directories before you change the policy.

    Sources

    (9)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Nothing in your own settings files or --settings overrides a managed key”
      ↩︎ Managed settings: the tier developers cannot override
      “A key you set there overrides the same key in your project and user settings files”
      ↩︎ Managed settings: the tier developers cannot override
      “Nothing in your own settings files or --settings overrides a managed key”
      ↩︎ Key concept
    2. 2.
      “Agent SDK sessions load managed settings even when settingSources excludes the user, project, and local files.”
      ↩︎ Managed settings: the tier developers cannot override
      “Makes managed settings the only settings source of permission rules.”
      ↩︎ Managed settings: the tier developers cannot override
      “Claude Code shows no warning for the sources it skips; /status names the source it used and the ones it skipped.”
      ↩︎ Managed settings: the tier developers cannot override
      “Admin source: one of the first three sources below. The HKCU registry is user-writable and isn’t one.”
      ↩︎ Managed settings: the tier developers cannot override
      “On other providers, or when ANTHROPIC_BASE_URL points somewhere other than Anthropic’s API, it starts at the next source”
      ↩︎ Routing all model traffic through a company gateway
      “Block skills, agents, hooks, and MCP servers from user and project sources; true locks all four, an array names which”
      ↩︎ A quality bar for shared skills, agents and MCP servers
      “Reject the --plugin-dir, --plugin-url, --agents, and --mcp-config flags at startup.”
      ↩︎ A quality bar for shared skills, agents and MCP servers
      “Claude Code uses the highest-ranked source that delivers at least one policy key and ignores the rest rather than merging them”
      ↩︎ Exam trap 2
      “Enforced as an empty allowlist until the value is fixed, so no marketplace source is admitted.”
      ↩︎ Exam trap 4
      “Claude Code uses the highest-ranked source that delivers at least one policy key and ignores the rest rather than merging them”
      ↩︎ Checkpoint
    3. 3.
      “Publish a list of approved servers; users add the ones they want, anything else is blocked”
      ↩︎ Controlling which MCP servers sessions can load
      “deniedMcpServers applies to managed servers too, so a managed server that matches an entry won’t load.”
      ↩︎ Controlling which MCP servers sessions can load
      “Cannot be set through server-managed settings”
      ↩︎ Controlling which MCP servers sessions can load
      “In-process servers that the app that started the session registers, such as the VS Code extension’s own server”
      ↩︎ Controlling which MCP servers sessions can load
      “Enforce an allowlist that users can broaden in their own settings”
      ↩︎ Exam trap 3
      “Blocked: matches both, but the denylist takes precedence”
      ↩︎ Prediction
      “Enforce an allowlist that users can broaden in their own settings | allowedMcpServers without allowManagedMcpServersOnly”
      ↩︎ Checkpoint
    4. 4.
      “Sends Claude Code’s API requests to the gateway instead of api.anthropic.com”
      ↩︎ Routing all model traffic through a company gateway
      “Authenticates each request to the gateway. The helper runs a command to fetch the key”
      ↩︎ Routing all model traffic through a company gateway
    5. 5.
      “A session on a provider that isn’t listed is refused at startup, at login, and when it next contacts the API.”
      ↩︎ Routing all model traffic through a company gateway
      “Turn off Anthropic-bound usage metrics, error reports, and surveys on every device”
      ↩︎ Enterprise telemetry: your collector versus Anthropic-bound traffic
      “Organization-wide behavioral guidance for Claude rather than a client-enforced rule”
      ↩︎ Exam trap 1
    6. 6.
      “Claude Code admits it only for the exact value a managed env block pins”
      ↩︎ Routing all model traffic through a company gateway
      “Claude Code sends people to a cloud gateway instead of a first-party login”
      ↩︎ Routing all model traffic through a company gateway
      “An empty array is a complete lockdown that blocks every marketplace source, including the official Anthropic marketplace”
      ↩︎ A quality bar for shared skills, agents and MCP servers
    7. 7.
      “under forceLoginMethod the credential would stand in for the required sign-in.”
      ↩︎ Routing all model traffic through a company gateway
    8. 8.
      “when ANTHROPIC_BASE_URL points at an Anthropic-compatible gateway such as LiteLLM, Kong, or an internal proxy”
      ↩︎ Routing all model traffic through a company gateway
      “disable nonessential network traffic: auto-updates, telemetry, error reporting, the /feedback command, Claude-drafted feedback, release notes”
      ↩︎ Enterprise telemetry: your collector versus Anthropic-bound traffic

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Professional (CCDV-P) in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.