Skip to main content

Deploy Agent Monitor via MDM

Push the Agent Monitor hooks configuration for Claude Code to every developer machine through your MDM, without overwriting settings developers have already made and with each event attributed to the developer who triggered it. This page covers the pattern shared by every MDM; for a complete Kandji walkthrough with a ready-to-paste script, see Deploy Agent Monitor with Kandji MDM.

Use managed-settings.json, not settings.json​

When your MDM pushes Claude Code configuration, the file it writes must be managed-settings.json, not the user-level ~/.claude/settings.json. The two files behave differently:

FilePrecedenceEditable by usersLocation
~/.claude/settings.jsonLowest (user-level)YesUser's home directory
managed-settings.jsonHighest (wins over every other settings file)NoSystem support directory

Because managed-settings.json takes precedence over everything else, it enforces the org-wide hooks without touching any customizations a developer has made in their personal settings.json, so no append or merge logic is needed on the MDM side.

The precedence rule comes from Claude Code itself (see Anthropic's hook locations documentation).

Where to place the file​

PlatformPath
macOS/Library/Application Support/ClaudeCode/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json

Set the hooks URL for your region​

The hooks URL your MDM config points at depends on your MintMCP tenant's region:

Tenant regionHooks URL
US (default)https://app.mintmcp.com/hooks/claudecode
EUhttps://eu.mintmcp.com/hooks/claudecode

Use the URL shown on the Agent Monitor Setup page for your tenant: don't hardcode app.mintmcp.com for an EU tenant, because events won't be delivered to the right place.

Preserve per-user attribution​

By default the hooks deliver events with no user identity attached, so the Agent Monitor dashboard renders activity as $unknown. To attribute events to individual developers, set the X-MINTMCP-USER header in every hook block to an environment variable that holds the developer's username:

PlatformEnv varHeader value
macOS / Linux$USER"X-MINTMCP-USER": "$USER"
Windows$USERNAME"X-MINTMCP-USER": "$USERNAME"

The hooks payload references the variable by name and lists it in allowedEnvVars. Claude Code resolves the variable when the hook fires, so each event arrives tagged with the developer who triggered it.

Targeting both macOS and Windows​

The two native user env vars ($USER and $USERNAME) don't overlap, so a config written for one platform won't attribute users on the other:

  • Separate configs per platform: change $USER to $USERNAME in the Windows config.
  • A single managed-settings config across both: reference an environment variable that already exists consistently on both Windows and macOS machines.

Deploy with your MDM​

macOS MDMs (Kandji, Jamf, and other file-based macOS MDMs) and Windows MDMs (Intune) are all supported. The file-based approach is the same across them: only the path and the user-attribution env var differ.

Kandji​

Deploy Agent Monitor with Kandji MDM is a complete walkthrough with a ready-to-paste audit script, including the chmod 0644 and chown root:wheel calls that lock the file down so users can't edit it locally.

Intune​

Intune deployments follow the same managed-settings.json rollout pattern at the Windows path, with $USERNAME for attribution. Contact support@mintmcp.com for Intune deployment docs.

Jamf​

Jamf follows the same file-based pattern as Kandji at the macOS path. Contact support@mintmcp.com for Jamf deployment docs.

Verify the deployment​

  1. Confirm the file exists on a test device and contents look correct:

    # macOS
    cat "/Library/Application Support/ClaudeCode/managed-settings.json"
    # Windows
    Get-Content "C:\Program Files\ClaudeCode\managed-settings.json"

  2. Launch Claude Code and perform any action.

  3. Open Live Activity in MintMCP and confirm the event appears tagged with the developer's username, not $unknown.

Troubleshooting​

Activity shows $unknown. The most common cause is the X-MINTMCP-USER header missing from the hooks block, or the referenced env var not being listed in allowedEnvVars. Both must be set for the username to flow.

Next steps​