Claude Code integration

Capture Claude Code sessions as cryptographically-signed audit events. Two setup paths, both work natively.

Native · OpenTelemetry + MCP

For non-technical readers: Claude Code is Anthropic's command-line AI coding agent. It runs on a developer's laptop. By default, no record is kept of what it does. This integration captures every Claude Code session into a tamper-evident audit log that can be verified by an outside auditor without trusting Anthropic or SteelSpine. The dev team enables it once and forgets about it; the audit trail accumulates automatically.

How it works

Claude Code (as of 2026) emits OpenTelemetry signals natively: traces of every tool call, every token used, every cost incurred, every session. These signals are off by default and turned on with a single environment variable.

SteelSpine includes an OpenTelemetry receiver that accepts these signals at standard OTLP/HTTP endpoints. Once configured, every Claude Code session is automatically captured into SteelSpine's signed event chain. The captured events go through the same pipeline as any other agent: hash-chained, Ed25519-signed, replayable, independently verifiable.

Plus: SteelSpine includes a Model Context Protocol (MCP) server. Once configured in Claude Code, the AI assistant gains direct read access to your captured audit history. Ask Claude Code "what failed in the last 24 hours according to SteelSpine?" and it queries the audit chain directly.

Setup option A: OpenTelemetry capture (recommended)

This path captures every Claude Code session automatically. Ideal for compliance and audit-trail use cases.

Step 1: Start the SteelSpine OpenTelemetry receiver

steelspine otel-receiver --port 4318 --project claude-code

The receiver runs as a background process and listens on port 4318 (the standard OTLP/HTTP port). It accepts traces from Claude Code or any other OTEL-instrumented agent. For production deployments, configure as a systemd service so it survives reboots.

Step 2: Enable Claude Code telemetry

Set these environment variables in the shell where Claude Code will run (typically in ~/.bashrc or ~/.zshrc for permanent setup):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

That's it. Run Claude Code as normal. Every session is captured.

Step 3: Verify capture is working

# Quick health check
curl -s http://localhost:4318/health

# List captured runs
steelspine run list

# Generate audit report
steelspine verify-run --compliance-html > claude_code_audit.html

Setup option B: MCP server (AI assistant access)

This path gives Claude Code's AI assistant direct read access to your SteelSpine audit history. The AI can answer questions about past runs, compare sessions, verify integrity, and generate reports without leaving the chat.

Step 1: Configure the MCP server in Claude Code

Add to your Claude Code MCP configuration (location depends on Claude Code version; check the Claude Code docs for current path):

{
  "mcpServers": {
    "steelspine": {
      "command": "python3",
      "args": ["/home/<your-user>/.prime/adapters/cursor/bin/steelspine_mcp_server.py"]
    }
  }
}

Replace <your-user> with your actual username (find it with whoami).

Step 2: Restart Claude Code

The MCP server is loaded on Claude Code startup. After restart, the AI has 8 SteelSpine tools available.

Step 3: Use it

In Claude Code, ask questions like:

"What's the status of my SteelSpine installation?"
"List my last 20 captured runs."
"Compare runs run_0047 and run_0046."
"Verify the integrity of run_0050."
"What failed across all my runs?"
"Search for 'connection refused' in captured runs."

The AI calls the MCP tools, gets real data from your SteelSpine installation, and answers with citations.

Best practice: use both

The two setup paths are complementary, not alternatives:

Option A captures every Claude Code session automatically into your audit trail. Run-and-forget.
Option B gives the AI assistant interactive access to query that audit trail during sessions.

Most teams use both: A for the audit-trail (compliance, retrospectives, debugging), B for in-session intelligence ("did I run this before? what happened?").

What you'll see in the audit chain

Each Claude Code session captured produces events like:

{"adapter": "otel", "label": "claude-code", "line": "tool_call: bash 'npm test'", "kind": "success", ...}
{"adapter": "otel", "label": "claude-code", "line": "tool_call: edit_file 'src/auth.ts'", "kind": "success", ...}
{"adapter": "otel", "label": "claude-code", "line": "tool_call: web_search 'OAuth 2.0 PKCE'", "kind": "success", ...}

Each event is hash-chained and Ed25519-signed. A regulator or auditor with the public key can verify any subset of these events independently.

Compliance use cases

Scenario	What SteelSpine + Claude Code provides
SOC 2 Type II audit asks "what did your AI tooling do in March?"	`steelspine verify-run --compliance-html` for any date range; shows every captured Claude Code session with cryptographic integrity
Customer security questionnaire asks for AI activity logs	Export portable audit packet via `steelspine pack-create`; customer auditor verifies independently with public key
Regulator inquiry about a specific AI-assisted code change	`steelspine search "<commit hash>"` finds the captured session; full event timeline with model, tool calls, and reasoning
Internal incident response: "what did the AI do during this outage?"	`steelspine replay-run <session_id>` deterministically replays the captured session offline

Troubleshooting

Receiver starts but no events appear

Verify CLAUDE_CODE_ENABLE_TELEMETRY=1 is set in the same shell where Claude Code runs. Run echo $CLAUDE_CODE_ENABLE_TELEMETRY to confirm.
Verify OTEL_EXPORTER_OTLP_PROTOCOL=http/json. Without it, Claude Code may default to protobuf which SteelSpine's receiver does not currently accept.
Confirm the receiver is actually reachable: curl http://localhost:4318/health should return {"status": "ok"}.
Run the receiver with --verbose to see each span as it arrives.

MCP server doesn't show up in Claude Code

Confirm the path to steelspine_mcp_server.py is absolute and correct.
Restart Claude Code after editing the MCP configuration.
Test the MCP server directly: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 ~/.prime/adapters/cursor/bin/steelspine_mcp_server.py should return a proper response with serverInfo.
Check Claude Code's MCP logs (location depends on version) for connection errors.

"steelspine binary not found" errors from MCP

The MCP server expects steelspine at ~/.prime/bin/steelspine. Verify it exists: ls -la ~/.prime/bin/steelspine.
If installed elsewhere, set STEELSPINE_BIN environment variable to the correct path.

Pairing with other integrations

Cursor: same MCP server works in Cursor with .cursor/mcp.json config. See /integrations/cursor.html.
Docker: if Claude Code runs inside a container, the OTEL receiver can be on the host. Set the endpoint to the container-host bridge.
Git / CI: capture Claude Code sessions in CI workflows. See /docs/ci-cd.html.