Wire Axiom into your MCP agent stack

Architecture Overview

Axiom sits in the invocation path between your agent and its skill backend. Every skill call passes through the Axiom receipt middleware, which captures a cryptographic snapshot before and after execution.

The receipt captures four elements in a tamper-evident chain:

1. inputs_hash — SHA-256 of skill inputs, computed before execution.
2. output_hash — SHA-256 of skill output, computed after execution.
3. signature — HMAC-SHA256 over the full receipt payload.
4. timestamp — UTC time of invocation initiation.

The signing secret never leaves your infrastructure. Axiom operates in two modes: hosted (signing handled by Axiom's service) and self-hosted (signing secret deployed alongside your agent). The receipt ID is the only lookup key needed for independent verification.

Three Integration Scenarios

# Run the Axiom MCP test server alongside your own server
node mcp-servers/axiom-test-server.js &
node your-mcp-server.js

// wrap-mcp-server.js
const { MCPClient } = require('./services/mcp');

// Point Axiom at your existing MCP server
const client = new MCPClient('node', ['./my-mcp-server.js']);

async function init() {
  await client.connect();

  // Every call through this client is now receipt-stamped
  const { output, receipt } = await client.callTool(
    'my-tool',
    { param: 'value' },
    { source: 'live', caller: 'my-agent-v1' }
  );

  console.log('Receipt ID:', receipt.id);
  console.log('Verify:', `https://axiom-ai-19.polsia.app/verify?id=${receipt.id}`);
}

init();

// axiom-tool-wrapper.js
const { hashInputs, hashOutput, signReceipt } = require('./services/crypto');
const { createReceipt } = require('./db/receipts');

// Call this BEFORE every tool invocation
async function beforeSkillCall(skillName, inputs, caller) {
  const timestamp = new Date().toISOString();
  const inputsHash = hashInputs({ skill: skillName, args: inputs });
  return { timestamp, inputsHash }; // store pending state
}

// Call this AFTER every tool invocation
async function afterSkillCall(beforeState, skillName, output, caller) {
  const { timestamp, inputsHash } = beforeState;
  const outputHash = hashOutput(output);
  const signature = signReceipt(skillName, timestamp, inputsHash, outputHash);

  const receipt = await createReceipt({
    skill_name: skillName,
    timestamp,
    inputs_hash: inputsHash,
    output_hash: outputHash,
    signature,
    verification_status: 'verified',
    source: 'live',
    caller: caller || null,
  });

  return receipt;
}

// ── Example harness integration ──────────────────────────────
// In your Claude Code tool handler:
async function callToolWithReceipt(toolName, toolArgs, caller) {
  const before = await beforeSkillCall(toolName, toolArgs, caller);
  const rawResult = await yourMCPClient.callTool(toolName, toolArgs);
  const receipt = await afterSkillCall(before, toolName, rawResult, caller);
  return { result: rawResult, receipt };
}

{
  "mcpServers": {
    "axiom": {
      "command": "node",
      "args": ["/path/to/mcp-servers/axiom-test-server.js"]
    }
  }
}

/**
 * Called before every skill invocation.
 * @param {string} skill - skill name
 * @param {object} inputs - skill inputs
 * @returns {{timestamp, inputsHash, skill, inputs}}
 */
function beforeSkillCall(skill, inputs) {
  const timestamp = new Date().toISOString();
  const inputsHash = hashInputs({ skill, args: inputs });
  return { timestamp, inputsHash, skill, inputs };
}

/**
 * Called after every skill invocation.
 * @param {object} beforeState - result of beforeSkillCall
 * @param {object} result - skill execution result
 * @param {string} [caller] - optional caller ID
 * @returns {Promise<object>} - stored receipt
 */
async function afterSkillCall(beforeState, result, caller) {
  const outputHash = hashOutput(result);
  const signature = signReceipt(
    beforeState.skill,
    beforeState.timestamp,
    beforeState.inputsHash,
    outputHash
  );
  return createReceipt({
    skill_name: beforeState.skill,
    timestamp: beforeState.timestamp,
    inputs_hash: beforeState.inputsHash,
    output_hash: outputHash,
    signature,
    verification_status: 'verified',
    source: 'live',
    caller: caller || null,
  });
}

// Inside your agent's skill execution loop:
async function executeSkill(skill, inputs, caller) {
  const before = beforeSkillCall(skill, inputs);
  const result = await callMCP(skill, inputs);   // your MCP call
  const receipt = await afterSkillCall(before, result, caller);
  return { result, receipt };
}

API Reference

{
  "skill_name": "echo",           // required — skill/tool identifier
  "inputs": { "message": "hello" }, // required — skill inputs as JSON object
  "caller": "my-agent-v1"         // optional — caller identifier for audit filtering
}

{
  "receipt": {
    "id": 142,
    "skill_name": "echo",
    "timestamp": "2026-05-27T08:00:00.000Z",
    "inputs_hash": "a1b2c3d4e5f6…",
    "output_hash": "f6e5d4c3b2a1…",
    "signature": "xK8mP2nLqRvT4wYzAb3c…",
    "verification_status": "verified",
    "source": "live",
    "caller": "my-agent-v1"
  },
  "result": { "content": [{ "type": "text", "text": "..." }] }
}

// 400 Bad Request — missing required fields
{ "error": "skill_name and inputs are required" }

// 502 Bad Gateway — MCP server unreachable
{ "error": "MCP server unavailable", "detail": "...", "hint": "..." }

// Error receipts are still stored (every attempt is auditable)
{ "receipt": { "id": 143, "skill_name": "...", "verification_status": "error" }, "result": { "status": "error", "message": "..." } }

# Live receipts for a specific skill, paginated
curl "https://axiom-ai-19.polsia.app/api/receipts?skill_name=echo&source=live&limit=20&offset=0"

# All receipts from a specific caller in May 2026
curl "https://axiom-ai-19.polsia.app/api/receipts?caller=my-agent-v1&date_from=2026-05-01&date_to=2026-05-31"

curl https://axiom-ai-19.polsia.app/api/receipts/142/verify | jq .

{
  "receipt_id": 142,
  "skill_name": "echo",
  "timestamp": "2026-05-27T08:00:00.000Z",
  "source": "live",
  "caller": "my-agent-v1",
  "inputs_hash": "a1b2c3d4e5f6…",
  "output_hash": "f6e5d4c3b2a1…",
  "signature_valid": true,       // HMAC-SHA256 intact
  "verification_status": "verified",
  "verified": true               // signature valid AND not an error receipt
}

curl https://axiom-ai-19.polsia.app/api/receipts/invocations | jq .tools[].name

Receipt Schema

Every receipt is a tamper-evident cryptographic record. The fields below are the complete schema — compliance auditors will read this directly.

Security Model

HMAC Signing

Receipts are signed with HMAC-SHA256 using a secret key. The signing payload is:

signing_payload = skill_name + "|" + timestamp + "|" + inputs_hash + "|" + output_hash
signature = base64(HMAC-SHA256(signing_payload, signing_secret))

The signing secret is derived from RECEIPT_SECRET environment variable. In production, set this to a cryptographically random 256-bit value. Rotation: generate a new secret, re-sign active receipts, deploy, then revoke the old secret.

Input/Output Hashing

Hashes use SHA-256 over canonical JSON. Keys are sorted alphabetically before serialization to guarantee determinism across runs and languages:

// Inputs are serialized with keys sorted — identical inputs always produce identical hash
const canonical = JSON.stringify(inputs, Object.keys(inputs).sort());
const inputsHash = crypto.createHash('sha256').update(canonical).digest('hex');

Timing-Safe Verification

Verification uses crypto.timingSafeEqual to prevent timing attacks. String comparison in constant time ensures attackers cannot use response latency to infer the correct signature byte-by-byte.

What Axiom Can't See

Moving from Demo to Production

Before going live, work through this checklist. Each item is a real compliance requirement that enterprise procurement will ask about.

1. ✓
   Get a production API key. Demo keys tag traffic as source: 'demo', which is excluded from compliance exports. Retrieve your production key at /account/billing.
2. ✓
   Point at the production endpoint. Base URL: https://axiom-ai-19.polsia.app. Set AXIOM_BASE_URL in your agent's env so you can swap endpoints for testing.
3. ✓
   Configure receipt retention policy. Define how long receipts must be kept based on your regulatory requirements. By default, Axiom retains receipts indefinitely. Contact joe@getaifo.com for data retention SLA customization.
4. ✓
   Set up monitoring on receipt volume. Track GET /api/receipts?source=live volume. A spike in error receipts or a drop in total receipts is a sign something is wrong in the invocation path. Set alerts at 2× your baseline.
5. ✓
   Enable audit log export. Export receipts on a schedule using GET /api/receipts?source=live&date_from=...&date_to=.... Format: JSON Lines (\n-delimited) is recommended for bulk ingestion into your SIEM.
6. ✓
   Rotate the signing secret. Generate a production-strength secret (node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"). Store it in your secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.), not in source code.
7. ✓
   Test the full verify loop. Invoke a skill, fetch the receipt ID, call GET /api/receipts/:id/verify, confirm verified: true. Do this with your production key and in your deployment environment before the first compliance audit.