Skip to main content

Claude Code + AxonFlow Integration

Governance coverage
  • Interception point: Claude Code hooks — PreToolUse (before a tool runs) and PostToolUse (after), registered in the plugin's hooks.json with the matcher Bash | Write | Edit | NotebookEdit | mcp__*.
  • Governs: every matching tool call — native tools (Bash, Write, Edit, NotebookEdit) and all MCP tools (mcp__*) — plus a post-tool output scan and an audit record. Because hooks see native tools, this reaches more than MCP-only governance.
  • Does not govern: prompt content. The plugin registers no prompt hook (e.g. UserPromptSubmit), so the model's prompt and completion text are not policy-checked on this surface.

See Governance Architecture & Coverage for how this fits the five runtime modes.

Privacy notice​

Read before installing. AxonFlow Community SaaS at try.getaxonflow.com is the zero-config endpoint the plugin uses if neither AXONFLOW_ENDPOINT nor AXONFLOW_AUTH is configured. In that mode, governed tool inputs (tool name + arguments) and outbound message bodies are checked by AxonFlow's policy enforcement endpoint and recorded for audit. Community SaaS is offered in two tiers — Free (3-day audit retention, 200 events/day) and Plugin Pro ($9.99 / 90 days, 30-day retention, 2,000 events/day). Both tiers are suitable for individual use within their documented limits. Neither tier is designed for regulated industries, real user data of third parties, or workloads requiring contractual SLOs — see the Privacy Policy for the full scope of what we commit to and what we don't.

For any serious use, choose one of the following instead:

  1. Self-host AxonFlow Community Edition — runs entirely on your infrastructure and keeps data within your boundary. Recommended for any real workload.
  2. Community Edition with an Evaluation License — for production use with real users or clients on the open core; adds production-fit limits and license-gated features. Free 90-day evaluation license.
  3. AxonFlow Enterprise — production-grade governance, regulatory-grade controls, SLOs, and contractual commitments suitable for regulated industries. Contact [email protected].

Setting AXONFLOW_ENDPOINT to a self-hosted AxonFlow URL flips the plugin into self-hosted mode. For a Community Edition self-hosted agent that is enough — no credential is required. For an Enterprise / in-VPC agent you must also set AXONFLOW_AUTH (see Self-hosted / Enterprise authentication), or the agent rejects every call. For air-gapped operation, set AXONFLOW_COMMUNITY_SAAS=0 to suppress the bootstrap attempt and AXONFLOW_TELEMETRY=off to disable the anonymous 7-day heartbeat.

Plugin Pro — paid upgrade for individual developers​

$9.99 USD for 90 days. One-time payment, no auto-renewal.

If you're using this plugin against try.getaxonflow.com and outgrowing the Free tier's caps — daily quota, burst limit, audit retention, the custom-policy and HITL-approval limits, or the lack of LLM cost pre-flight — Plugin Pro raises them:

  • 30-day audit retention (10× Free)
  • 2,000 governed events per day (10× Free)
  • 200 governed write events per minute (Free: 25/min)
  • 50 active custom tenant policies (Free: 4 active max)
  • 20 HITL approvals per rolling 7 days (Free: 2 per rolling 7d)
  • LLM cost pre-flight — see what a multi-step plan costs before it runs (Pro only)
  • Email support, 2 business-day response
  • 14-day refund window — no questions asked

Buy at getaxonflow.com/pricing → paste your cs_<uuid> tenant ID at Stripe Checkout → receive your AXON-… token by email → install with the bundled /axonflow-login AXON-… slash command (writes ~/.config/axonflow/license-token.json, mode 0600), or set AXONFLOW_LICENSE_TOKEN in your shell profile. The next governed action surfaces tier: Pro in the plugin's log lines. Full guide: Plugin Pro install.

Pro is for individual-developer use only. For team/production workloads, self-host Community Edition or contact us about Enterprise.

What This Integration Enables During Real Coding Work​

Claude Code users can now do more than just absorb a block and try again blindly. That is a meaningful change for real engineering teams because a blocked tool call is usually the start of an investigation, not the end of one. When a command is denied during a debugging session, an infrastructure change, or an MCP-backed data access flow, developers need to know what policy triggered, whether the block is expected, and what the approved path forward looks like.

  • deny responses can include decision_id, risk_level, and override availability, so a blocked command carries the context needed to understand the governance decision
  • Claude can call explain_decision, create_override, delete_override, and list_overrides through the same MCP connection it already uses for governed workflows
  • the result is a practical unblock path inside the terminal session: inspect the decision, decide whether a temporary exception is appropriate, and continue with the same audited context

For teams running Claude Code in regulated or tightly controlled environments, that means fewer dead-end denials and a much cleaner operator workflow around Decision Explainability and Session Overrides. A developer can hit a block on a shell command or MCP action, ask Claude to explain the decision, determine whether the action is eligible for a temporary exception, and proceed with the same terminal context instead of opening a separate platform UI and manually correlating logs.

The Claude Code-specific value is that this context lands inline in the same pre-check hook path the developer is already watching. A block can surface the decision_id, risk_level, and override hint directly in the REPL flow, so the developer does not have to infer what happened from a generic hook failure. Security and platform teams usually want developers to stay productive without normalizing unmanaged exceptions. These newer capabilities let Claude Code behave more like a governed engineering tool: blocks are inspectable, exceptions are explicit and time-bounded, and the full path from deny to override remains visible in audit.

What Claude Code Does Well​

Claude Code is Anthropic's official CLI for Claude—an agentic coding assistant that operates directly in your terminal. Its strengths are substantial:

Agentic Coding: Claude understands your codebase, makes edits, runs commands, and iterates on feedback. Natural language to working code.

Tool Execution: Built-in tools for file operations, bash commands, web fetching, and more. Extended via MCP servers for databases, APIs, and enterprise systems.

Lifecycle Hooks: Pre and post hooks for tool calls, notifications, and custom integrations. Control what happens before and after tool execution.

Context Awareness: Understands project structure through CLAUDE.md files and codebase exploration. Maintains context across sessions.

MCP Integration: Connect to external data sources via Model Context Protocol servers. Query databases, call APIs, access enterprise systems.

Local Execution: Runs entirely in your terminal. No cloud dependency for core functionality.

What Claude Code Doesn't Provide​

Claude Code focuses on developer productivity. These concerns are explicitly out of scope:

Production RequirementClaude Code's Position
Policy enforcement before tool executionHooks available—governance logic not provided
PII detection in queries/responsesNot addressed—developer responsibility
Audit trails for complianceSession logs exist—not compliance-formatted
SQL injection preventionNot provided—MCP servers handle their own security
Per-user/team cost controlsNot provided—usage is per-account
Data residency enforcementNot addressed—follows Anthropic API routing
Multi-tenant isolationNot applicable—single-user tool

This isn't a criticism—it's a design choice. Claude Code is a developer productivity tool. Enterprise governance is a separate concern.

Where Teams Hit Production Friction​

Based on real enterprise deployments, here are the blockers that appear when Claude Code moves beyond individual developer use:

1. The MCP Data Exposure​

A developer configures an MCP server connected to production databases. Claude Code queries customer records as part of debugging. The query results—including PII—flow through the conversation. No filtering, no audit.

2. The "What Did It Access?" Question​

Security asks:

  • What database queries did Claude Code execute?
  • What data was returned?
  • Was any PII included in prompts?
  • What commands were run?

Session logs exist but aren't formatted for compliance audits.

3. The Accidental Production Change​

Claude Code has bash access. A developer asks it to "fix the database issue." It runs a command that modifies production data. The command was allowed—there was no policy preventing it.

4. The Security Review Block​

Security review: BLOCKED
- No policy enforcement on MCP queries
- PII can flow through conversations unchecked
- Bash commands not governed
- Audit trail not compliance-ready
- No approval gates for sensitive operations

Claude Code works perfectly for development. Governance gaps block production use.

How AxonFlow Plugs In​

AxonFlow integrates with Claude Code through the AxonFlow plugin — a standard Claude Code plugin that provides automatic governance via lifecycle hooks and MCP tools.

Claude Code selects a tool (Bash, Write, MCP, etc.)
    │
    ▼
PreToolUse hook fires automatically
    │ → check_policy("claude_code.Bash", "rm -rf /")
    │
    ├─ BLOCKED → Claude receives denial, tool never runs
    │
    └─ ALLOWED → Tool executes normally
                      │
                      ▼
                 PostToolUse hook fires automatically
                      │ → audit_tool_call(tool, input, output)
                      │ → check_output(tool result for PII/secrets)
                      │
                      ├─ PII found → Claude instructed to use redacted version
                      └─ Clean → Silent, no interruption

What AxonFlow adds:

  • Automatic policy enforcement before every governed tool call
  • Dangerous command blocking: reverse shells, rm -rf /, curl|bash, cloud metadata SSRF, credential file access, path traversal
  • Sensitive-data detection in tool outputs, with Claude instructed to use a redacted version when policy requires it
  • SQL injection prevention for MCP database queries
  • Compliance-grade audit trails for both allowed and blocked attempts
  • Individual audit event search for debugging and compliance evidence

Quick Start: Plugin Installation​

The fastest way to add AxonFlow governance to Claude Code:

# 1. Start AxonFlow (if not already running)
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow && docker compose up -d

# 2. Point the plugin at your agent (and authenticate — see below)
export AXONFLOW_ENDPOINT=http://localhost:8080
export AXONFLOW_TIMEOUT_SECONDS=12  # optional override for remote deployments

3. Install the plugin from the AxonFlow marketplace (recommended). Run these two commands inside Claude Code, then /reload-plugins (or restart):

/plugin marketplace add getaxonflow/axonflow-claude-plugin
/plugin install axonflow@axonflow

This is the recommended path: it always pulls the current released plugin (no manual git checkout) and updates in place via /plugin, so you stay on the latest fix without re-cloning.

Use the marketplace, not a stale local clone

Loading the plugin from a local source directory with --plugin-dir gives you whatever commit you cloned — an out-of-date copy can hit issues that newer releases already fix (e.g. the MCP headersHelper auth fix in v1.5.3, which makes list_policies and other MCP tool calls authenticate correctly on self-hosted / Enterprise agents). The marketplace install above avoids that; --plugin-dir is best kept for plugin development.

Alternative: load from a local source directory (plugin development)
claude --plugin-dir /path/to/axonflow-claude-plugin

Keep the directory current — git -C /path/to/axonflow-claude-plugin fetch && git checkout v1.6.0 (or main) — or you may run an older plugin than the latest release.

The plugin has also been submitted to the official Anthropic marketplace (/plugin > Discover) and is in Anthropic's review queue; until it appears there, use the AxonFlow marketplace above.

No LLM provider keys needed — Claude Code handles all LLM calls, AxonFlow only enforces policies and records audit trails.

Self-hosted / Enterprise authentication​

Whether you need a credential depends on which edition your agent runs:

  • Community Edition self-hosted (DEPLOYMENT_MODE=community) — the agent accepts unauthenticated governance calls, so you can leave AXONFLOW_AUTH unset. Setting AXONFLOW_ENDPOINT alone is enough.
  • Enterprise / in-VPC agents (DEPLOYMENT_MODE=enterprise / in-vpc-*) — the agent requires HTTP Basic auth on every call, including the MCP server connection. You must set AXONFLOW_AUTH, or /mcp shows "axonflow failed" and every governed tool call is blocked (fail-closed). The Basic credential for an Enterprise/in-VPC agent is base64(org_id:license_key) — the same credential your working policy-checks already use:
export AXONFLOW_ENDPOINT=https://your-agent.internal:8080
# org_id:license_key — NOT a per-user secret; an org-scoped license key is fine fleet-wide.
export AXONFLOW_AUTH=$(printf '%s:%s' "<org_id>" "<license_key>" | base64 | tr -d '\n')
claude --plugin-dir /path/to/axonflow-claude-plugin

The plugin adds the Basic prefix itself, so AXONFLOW_AUTH is the bare base64 string (do not include Basic ). Restart Claude Code after setting it, then run /mcp — axonflow should show connected. If a tool call is denied with an authentication error, the deny reason names exactly these two variables; as a last-resort break-glass you can set AXONFLOW_FAIL_OPEN_ON_AUTH_ERROR=1 to keep working ungoverned while you fix the credential (not recommended).

Plugin repo: getaxonflow/axonflow-claude-plugin

What Gets Governed Automatically​

EventHookAction
Before governed tool callPreToolUsecheck_policy evaluates tool inputs against governance policies
After governed tool callPostToolUseaudit_tool_call records execution in compliance audit trail
After governed tool callPostToolUsecheck_output scans output for PII/secrets

Governed tools: Bash, Write, Edit, NotebookEdit, and all MCP tools (mcp__*).

Fail behavior:

  • AxonFlow unreachable (network failure) → fail-open, tool execution continues
  • AxonFlow auth/config error → fail-closed, tool call denied until configuration is fixed
  • PostToolUse failures → never block (audit and PII scan are best-effort)

MCP Tools​

In addition to automatic hooks, the plugin exposes 10 MCP tools that Claude can call explicitly. All tools are served by the agent's MCP server at /api/v1/mcp-server (not by the plugin itself — the plugin's .mcp.json points Claude Code at the agent endpoint). Adding new tools to the platform makes them immediately available in every plugin that targets the same agent.

Governance (6):

ToolPurpose
check_policyEvaluate specific inputs against policies
check_outputScan specific content for PII/secrets
audit_tool_callRecord additional audit entries
list_policiesList active governance policies (static + dynamic)
get_policy_statsGet governance activity summary
search_audit_eventsSearch individual audit records for debugging and compliance

Session overrides and explainability (4):

ToolPurpose
explain_decisionReturn the full DecisionExplanation for a decision ID
create_overrideCreate a time-bounded, audit-logged session override (mandatory justification)
delete_overrideRevoke an active session override
list_overridesList active overrides scoped to the caller's tenant

When a user hits a policy block, Claude Code surfaces the decision ID in the block reason. The user can ask Claude to call explain_decision with that ID, and — if the decision is overridable — create_override to unblock themselves.

All 4 new tools require an authenticated user identity (X-User-Email / X-User-ID) which the agent populates from the MCP session; plugins never need to configure these themselves.

Integration-Specific Policies​

AxonFlow supports integration-scoped policies that activate automatically when a specific integration is detected. Set AXONFLOW_INTEGRATIONS=claude-code to enable Claude Code-specific protections:

  • .claude/settings.json write protection
  • .claude/hooks/*.json modification warnings

These policies are pre-loaded as disabled and activated on first detection or via the AXONFLOW_INTEGRATIONS environment variable. See Integration Policy Activation for details.

Custom Integration Alternative​

If you cannot load a Claude Code plugin directly, you can reproduce the same pattern with custom PreToolUse / PostToolUse hooks that call AxonFlow's MCP server. The official plugin is still the recommended path because it already handles:

  • governed-tool matching
  • network failure fail-open behavior
  • auth/config fail-closed behavior
  • blocked-attempt auditing
  • post-tool output scanning guidance

For custom setups, use the same six MCP tools listed above over /api/v1/mcp-server. The reference implementation lives in the AxonFlow Claude Code plugin repo, and Anthropic's latest hook wiring is documented in the Claude Code hooks guide.

Plugin Configuration​

Whether you use the packaged plugin or a custom wrapper, the runtime configuration is intentionally small:

# AxonFlow Agent endpoint (defaults to localhost in the packaged plugin)
export AXONFLOW_ENDPOINT=http://localhost:8080

# Base64(client_id:client_secret)
# In community mode, you can leave this unset if your Agent is running without licensed auth.
export AXONFLOW_AUTH=$(echo -n "your-client-id:your-client-secret" | base64)

# Optional: increase hook HTTP timeout for remote or high-latency AxonFlow deployments
export AXONFLOW_TIMEOUT_SECONDS=12

The packaged plugin then wires:

  • PreToolUse for Bash, Write, Edit, NotebookEdit, and mcp__*
  • PostToolUse for the same governed tool set
  • check_policy before execution
  • audit_tool_call and check_output after execution

Timeout Tuning​

Use AXONFLOW_TIMEOUT_SECONDS to tune how long the packaged Claude Code hooks wait for AxonFlow:

  • PreToolUse defaults to 8 seconds when unset
  • PostToolUse defaults to 5 seconds when unset
  • setting AXONFLOW_TIMEOUT_SECONDS applies the same timeout to all hook HTTP calls

Raw MCP Example​

If you are building your own hook wrapper, this is the core JSON-RPC call the packaged plugin pattern relies on:

curl -X POST http://localhost:8080/api/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Basic $AXONFLOW_AUTH" \
  -H "Mcp-Session-Id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "check-1",
    "method": "tools/call",
    "params": {
      "name": "check_policy",
      "arguments": {
        "connector_type": "claude_code.Bash",
        "statement": "rm -rf /",
        "operation": "execute"
      }
    }
  }'

The same session can then call check_output, audit_tool_call, list_policies, get_policy_stats, and search_audit_events.

AxonFlow Policies for Claude Code​

AxonFlow ships with 80+ built-in system policies that automatically apply to Claude Code requests:

  • SQL Injection Detection — 30+ patterns including UNION injection, stacked queries, auth bypass, and encoding tricks
  • Dangerous Command Blocking — Reverse shells, rm -rf /, dd if=, curl|bash, cloud metadata SSRF, credential file access, path traversal
  • PII Detection — SSN, credit cards, Aadhaar, PAN, email, phone, NRIC/FIN (Singapore), and more
  • Code Security — API key exposure, secrets in code, unsafe code patterns
  • Prompt Injection — Ignore-instruction patterns, jailbreak attempts, role hijacking

For custom policies, use the Agent API or Customer Portal (Enterprise):

# Create a custom policy via API
curl -X POST http://localhost:8080/api/v1/dynamic-policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code-production-block",
    "description": "Block production database access from Claude Code",
    "policy_type": "content",
    "conditions": [
      {"field": "query", "operator": "contains", "value": "production"}
    ],
    "actions": [
      {"type": "block", "message": "Production access blocked"}
    ]
  }'

See Policy Documentation for the full policy API reference.

What Gets Logged​

Every governed Claude Code action can be inspected through AxonFlow's audit trail and the search_audit_events MCP tool. In practice that gives you:

  • tool name and connector type
  • whether the action was allowed or blocked
  • summarized input and output
  • matched policies and block reason when present
  • timestamps and duration for debugging and compliance evidence

If the governed tool is itself an AxonFlow MCP connector, connector-level request and response audits are also available through AxonFlow's MCP auditing surfaces.

Typical audit searches answer questions like:

  • Which Bash commands were blocked in the last hour?
  • Which MCP tools returned content that triggered PII policies?
  • What edits were attempted against protected Claude configuration files?
  • Which developer session generated the most governance events today?

Example: Governed Database Query​

Here is the runtime path when Claude Code uses a governed MCP database tool:

  1. Claude selects mcp__postgres to answer a developer request.
  2. The PreToolUse hook calls check_policy with the tool input and connector type claude_code.mcp__postgres.
  3. If policy allows the action, the MCP tool executes normally.
  4. The PostToolUse hook records audit_tool_call in the background.
  5. The same PostToolUse hook calls check_output on the tool result.
  6. If the result contains sensitive data, Claude is instructed to use a redacted version in its follow-up response.

Latency Considerations​

OperationTypical Latency
Policy pre-check2-5ms
PII detection1-3ms
SQL injection scan1-2ms
Audit write (async)0ms (non-blocking)
Total overhead3-10ms

For interactive Claude Code usage, this overhead is imperceptible.

Best Practices​

1. Start in Observe Mode​

AxonFlow supports observe-only mode where policies log but don't block:

# Set PII detection to log-only mode
export PII_ACTION=log

# Or per-policy via API
curl -X PUT http://localhost:8080/api/v1/dynamic-policies/{id} \
  -d '{"actions": [{"type": "log"}]}'

Review logs before enabling enforcement.

2. Govern Sensitive Tools Only​

Don't add overhead to read-only operations:

GOVERNED_TOOLS=("Bash" "mcp__postgres" "mcp__mysql" "Write" "Edit")
# Skip: Read, Glob, Grep, WebFetch

3. Use Context for Better Policies​

Pass Claude Code context to AxonFlow for smarter decisions:

{
  "context": {
    "tool": "Bash",
    "working_directory": "/home/user/project",
    "session_id": "claude-session-123",
    "project": "customer-portal"
  }
}

4. Configure Approval Workflows (Enterprise)​

For high-risk operations, require human approval via HITL (Human-in-the-Loop):

# Create a policy requiring approval
curl -X POST http://localhost:8080/api/v1/dynamic-policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "name": "production-approval-required",
    "conditions": [
      {"field": "query", "operator": "matches", "value": ".*production.*"}
    ],
    "actions": [
      {"type": "require_approval", "approvers": ["security-team"]}
    ]
  }'

See HITL Documentation for approval workflow configuration.

Workflow Example​

A typical governed Claude Code workflow for a development team:

# 1. Developer starts Claude Code with governance hooks configured
claude --project /path/to/project

# 2. Developer asks Claude Code to query production data
> "Show me the last 10 orders for customer 42"

# 3. Pre-hook fires: AxonFlow checks the governed tool input
#    - SQL injection scan: PASS
#    - Sensitive-operation policies: PASS

# 4. Claude Code executes the MCP query
#    - Tool runs normally after policy approval
#    - Post-hook writes an audit entry in the background
#    - Output scan checks for PII/secrets
#    - If sensitive data is found, Claude is instructed to use the sanitized version

# 5. Developer asks Claude Code to modify a file
> "Update the config to point to the new database endpoint"

# 6. Pre-hook fires: AxonFlow checks policy
#    - Content scan: PASS (no credentials in the edit)
#    - File path protection policies: PASS
#    - If blocked, Claude receives a denial and the edit never runs

# 7. End of session: All interactions are in the audit trail

Security Considerations​

When using Claude Code with AxonFlow governance in a team environment, keep these security practices in mind:

ConsiderationRecommendation
Hook script permissionsSet hooks to chmod 700 so only the owner can modify them. Prevent other users from bypassing governance by replacing hook scripts.
AxonFlow credentialsStore AXONFLOW_AUTH in a secure location (for example macOS Keychain or a shell profile loaded from a protected file). Never hardcode credentials in wrapper scripts.
Network isolationRun AxonFlow on localhost or a private network. Do not expose the Agent API (port 8080) to the public internet.
Production database accessUse block policies (not just warn) for production database patterns. A developer can accidentally modify production data through Claude Code's bash tool.
MCP server scopeLimit which MCP servers Claude Code can access. Only configure connectors that the developer actually needs.
Audit retentionRetain Claude Code audit logs for at least 90 days for security incident investigation. Longer for regulated industries.

Team / Fleet Deployment​

Everything above describes a single developer loading the plugin with --plugin-dir and exporting AXONFLOW_* in their shell. That does not scale to a 30–40 engineer team: you cannot rely on every developer to install the plugin, set the endpoint, and never disable the hook. Claude Code solves this with managed settings — an admin-controlled configuration tier that sits above user, project, and even command-line settings and cannot be overridden by the developer. You use it to force-enable the AxonFlow plugin fleet-wide, point it at your AxonFlow agent, and pre-approve the governed tools so developers see zero permission prompts while AxonFlow does the real allow/deny/audit.

Claude Code, not Claude Desktop. This is the genuine managed-settings.json mechanism — a real on-disk policy file (and a server-managed equivalent). It is distinct from the Claude Desktop integration, which has no hooks and is governed by an MCP proxy configured through the com.anthropic.claudefordesktop MDM domain. For Claude Code, governance is the plugin + PreToolUse/PostToolUse hooks, and the fleet mechanism is managed settings.

Two delivery channels​

Claude Code reads managed settings from two sources, both at the top (non-overridable) tier. (Anthropic: server-managed settings, endpoint-managed settings)

ChannelHow it arrivesBest forPlan / version floor
Server-managed settingsPushed from the Claude.ai admin console (Admin Settings → Claude Code → Managed settings); clients fetch at startup + hourly. No MDM required.Teams without device management, or users on unmanaged devices.Claude for Teams: v2.1.38+ · Claude for Enterprise: v2.1.30+
Endpoint-managed settingsA managed-settings.json file (or OS policy) deployed to each device by MDM / Group Policy. The OS protects it from user edits.Fleets already under Jamf / Intune / Kandji / GPO. Stronger enforcement (file is root-owned).Any plan; version-independent (it is an OS-level file)

Within the managed tier, server-managed is checked first, then endpoint-managed; the first source that delivers a non-empty config wins — they do not merge. Pick one as your source of truth. (precedence)

Key difference from Claude Desktop. For Claude Code, admin-console (server-managed) push works on both Team and Enterprise — it is not Enterprise-gated the way Claude Desktop's server-managed settings are. The only Team-vs-Enterprise difference is the minimum CLI version (2.1.38 vs 2.1.30).

managed-settings.json file locations (endpoint-managed)​

PlatformPathOS policy channel
macOS/Library/Application Support/ClaudeCode/managed-settings.jsoncom.anthropic.claudecode managed-preferences domain (Jamf / Kandji plist)
Linux / WSL/etc/claude-code/managed-settings.jsonfile deployed by config management
WindowsC:\Program Files\ClaudeCode\managed-settings.jsonHKLM\SOFTWARE\Policies\ClaudeCode\Settings (REG_SZ, single-line JSON) via Intune / GPO

A managed-settings.d/ drop-in directory is also merged alphabetically, useful for splitting policy fragments. The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75. Anthropic ships ready-made MDM templates (com.anthropic.claudecode.plist, .mobileconfig, Set-ClaudeCodePolicy.ps1, and ADMX/ADML) in anthropics/claude-code/examples/mdm. (file paths)

Template managed-settings.json​

The same JSON works in the admin console (server-managed) or as an on-disk file (endpoint-managed). It does four things: pins the AxonFlow plugin and its marketplace, points the plugin at your agent, pre-approves the governed tools so developers are never prompted, and locks the configuration so developers cannot weaken it.

{
  "env": {
    "AXONFLOW_ENDPOINT": "https://axonflow.internal.example.com",
    "AXONFLOW_AUTH": "BASE64_OF_ORG_ID_COLON_LICENSE_KEY",
    "AXONFLOW_TIMEOUT_SECONDS": "12"
  },

  "extraKnownMarketplaces": {
    "axonflow": {
      "source": { "source": "github", "repo": "getaxonflow/axonflow-claude-plugin", "ref": "v1.6.0" },
      "autoUpdate": false
    }
  },
  "enabledPlugins": { "axonflow@axonflow": true },

  "strictKnownMarketplaces": [
    { "source": "github", "repo": "getaxonflow/axonflow-claude-plugin" }
  ],

  "permissions": {
    "allow": [
      "Bash",
      "Edit",
      "Write",
      "NotebookEdit",
      "mcp__axonflow"
    ]
  },

  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true
}

Pre-approve every tool you want prompt-free. permissions.allow only suppresses the prompt for the tools you list. The AxonFlow plugin governs Bash, Edit, Write, NotebookEdit, and all MCP tools (mcp__*); the example pre-approves the four built-ins plus AxonFlow's own MCP tools. If your team uses other MCP connectors (e.g. mcp__postgres), add each one to allow — they are still governed if omitted, they just still prompt.

Key by key:

  • env — applied to every Claude Code session and every subprocess it spawns. AXONFLOW_ENDPOINT points at your self-hosted AxonFlow agent; AXONFLOW_AUTH is base64(client_id:client_secret) — for an Enterprise/in-VPC agent that is base64(org_id:license_key) (the agent reads the credential from the HTTP Basic header). The credential here is an org-scoped license key, not a per-user secret, so a fleet-wide value is appropriate. (env key)
  • extraKnownMarketplaces + enabledPlugins — register the AxonFlow marketplace and force-enable the plugin. enabledPlugins uses plugin-id@marketplace-id → true. Force-enabling from managed settings means a developer cannot disable it, and even a local --plugin-dir copy cannot override a managed force-enabled plugin. Pin the marketplace ref to a released tag (e.g. v1.6.0) so the fleet runs a known plugin version; bump the ref to upgrade. (enabledPlugins, team marketplaces)
  • strictKnownMarketplaces (managed-only) — allowlist of marketplaces developers may add. With only the AxonFlow repo listed, developers cannot add arbitrary plugin marketplaces; an empty array is full lockdown. (strictKnownMarketplaces)
  • permissions.allow — the answer to per-call approval friction (see below).
  • allowManagedPermissionRulesOnly (managed-only) — only the allow/ask/deny rules defined in managed settings apply; developers cannot add their own allow rules to widen the surface. (managed-only settings)
  • allowManagedHooksOnly (managed-only) — only managed, SDK, and force-enabled plugin hooks load. Because the AxonFlow plugin is force-enabled via enabledPlugins, its PreToolUse/PostToolUse hooks still run — but a developer cannot register their own hooks to short-circuit governance.

Because env and hooks execute or inject shell-level configuration, server-managed delivery shows the developer a one-time security-approval dialog on first startup (skipped in non-interactive -p runs). Endpoint-managed (on-disk) settings apply without a dialog. (security approval dialogs)

Zero-prompt tools — the permissions.allow mechanism​

By default, Claude Code prompts the developer before each Bash, Edit, Write, or MCP tool call. Once AxonFlow governs those tools, that prompt is redundant — AxonFlow already makes the allow/deny/redact/audit decision in the PreToolUse hook. Listing the governed tools in permissions.allow pre-approves them so Claude Code does not prompt, and AxonFlow does the real governance. (permissions)

This is not a weakening of control — you remove a redundant click, not the enforcement:

  • permissions.allow patterns can be tool-wide (Bash) or scoped (Bash(npm run test *), Read(~/.zshrc)).
  • The AxonFlow PreToolUse hook still returns permissionDecision: "deny" for any policy-violating call, which overrides the allow and blocks the tool. (hook deny)
  • Add a permissions.deny list (e.g. "Read(./.env)", "Read(./secrets/**)") as a static backstop alongside AxonFlow's dynamic policy engine; deny always wins over allow.

The net developer experience: the AxonFlow plugin is already installed and governing on first launch, the safe tools you pre-approved run without prompting, and unsafe calls are blocked by policy with an inspectable decision_id.

Team vs Enterprise parity​

CapabilityClaude for TeamsClaude for Enterprise
Plugin + hook governance (the AxonFlow integration)✅✅
Endpoint-managed managed-settings.json via MDM✅✅
Server-managed settings (admin console push)✅ (CLI v2.1.38+)✅ (CLI v2.1.30+)
permissions.allow / allowManagedPermissionRulesOnly / allowManagedHooksOnly✅✅
strictKnownMarketplaces / enabledPlugins force-enable✅✅
Audit-log export / Compliance API for settings changes—✅ (contact Anthropic)
Custom roles composing with managed settings—✅

The full data-access governance story — force-enabled plugin, pinned version, zero-prompt tools, locked-down marketplaces — runs on Team + AxonFlow today. Enterprise adds organization-side conveniences (compliance API, custom roles), not a different AxonFlow integration.

Fail-closed startup (optional)​

Server-managed settings default to fail-open: if the startup fetch fails there is a brief window before the policy loads. For environments where that is unacceptable, set "forceRemoteSettingsRefresh": true so the CLI blocks at startup until settings are freshly fetched (and exits if it cannot reach api.anthropic.com). Endpoint-managed (on-disk) settings have no such window — they apply immediately at startup. Pair either with AxonFlow's own fail-closed posture (auth errors deny; see Fail behavior). (forceRemoteSettingsRefresh)

Caveat: server-managed settings are bypassed when Claude Code is pointed at a third-party model provider (Bedrock, Vertex, Foundry, or a custom ANTHROPIC_BASE_URL). For those fleets, use endpoint-managed managed-settings.json via MDM instead. (platform availability)

Troubleshooting​

Plugin Not Loading​

# Start Claude Code with the local plugin directory
claude --plugin-dir /path/to/axonflow-claude-plugin

# Verify required plugin files exist
ls /path/to/axonflow-claude-plugin/.claude-plugin/plugin.json
ls /path/to/axonflow-claude-plugin/hooks/hooks.json

# Check hook scripts parse
bash -n /path/to/axonflow-claude-plugin/scripts/pre-tool-check.sh
bash -n /path/to/axonflow-claude-plugin/scripts/post-tool-audit.sh

AxonFlow Connection Failed​

# Check AxonFlow is running
curl http://localhost:8080/health

# Verify environment variables used by the plugin
echo "$AXONFLOW_ENDPOINT"
test -n "$AXONFLOW_AUTH" && echo "AXONFLOW_AUTH is set"

# Test the policy enforcement endpoint directly
curl -s -X POST http://localhost:8080/api/v1/mcp/check-input \
  -H "Content-Type: application/json" \
  -d '{"connector_type":"claude_code.Bash","statement":"echo hello","operation":"execute"}'

Policy Not Applied​

# Check system policies are loaded
curl http://localhost:8080/api/v1/static-policies | jq '.policies | length'

# Test a policy check via MCP endpoint
curl -X POST http://localhost:8080/api/v1/mcp/check-input \
  -H "Content-Type: application/json" \
  -d '{"connector_type": "claude_code.Bash", "statement": "DROP TABLE users"}'

Next Steps​

Telemetry​

This plugin sends an anonymous heartbeat at most once every 7 days during activity. Under the v1 telemetry schema, the ping carries telemetry_type=plugin, sdk=claude-code-plugin, and stream=heartbeat. The payload also includes plugin version, OS, architecture, bash version, and AxonFlow platform version. No PII, no tool arguments, no policy data.

The cadence is gated by a stamp file at $HOME/.cache/axonflow/claude-code-plugin-telemetry-sent; delete it to force one fresh ping on the next hook invocation.

Opt out with AXONFLOW_TELEMETRY=off. DO_NOT_TRACK is not honored — the Claude Code CLI injects DO_NOT_TRACK=1 into every hook subprocess regardless of user intent, so it cannot represent a real opt-out signal in this context. See Telemetry for the full wire-level field reference and the scope of AXONFLOW_TELEMETRY=off on Community SaaS vs self-hosted.

Plugin: v1.6.0 | Platform: v8.6.0 | SDKs: Python v8.5.0, TypeScript v8.5.0, Go v8.5.0, Java v8.5.0, Rust v0.7.0 (preview)

Need Help?​

Implementation Checklist​

Before you put this integration in front of real users, connect it back to the core runtime docs:

Last updated on