Skip to main content

Claude Code + AxonFlow Integration

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. Set environment variables
export AXONFLOW_AUTH=$(echo -n "your-client-id:your-client-secret" | base64)
export AXONFLOW_ENDPOINT=http://localhost:8080
export AXONFLOW_TIMEOUT_SECONDS=12  # optional override for remote deployments

# 3. Load the plugin
claude --plugin-dir /path/to/axonflow-claude-plugin

In community mode (DEPLOYMENT_MODE=community), no auth is needed — leave AXONFLOW_AUTH unset.

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

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 evaluation (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.

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 policy evaluation 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 evaluation 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 telemetry ping on first hook invocation. The ping includes: plugin version, OS, architecture, bash version, and AxonFlow platform version. No PII, no tool arguments, no policy data. Fires once per install (stamp file guard at $HOME/.cache/axonflow/claude-code-plugin-telemetry-sent). Opt out with AXONFLOW_TELEMETRY=off (canonical); DO_NOT_TRACK=1 is also honored today but is deprecated and scheduled for removal after 2026-05-05 in the next major release. See Telemetry for details.

Plugin: v0.5.2 | Platform: v7.4.4 | SDKs: Python v6.8.0, TypeScript v6.1.0, Go v5.8.0, Java v6.1.0

Need Help?​

Last updated on