MCP Audit Gateway

mcp-audit

Your AI agent made 847 tool calls yesterday. Can you verify what it did?

Tamper-evident audit trail for AI agent tool calls.

Not to be confused with amin-ale/mcp-audit-gateway, an unrelated Python project with the same name.

Setup (10 seconds)

Before:

{
  "command": "npx",
  "args": ["@modelcontextprotocol/server-github"]
}

After:

{
  "command": "npx",
  "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-github"]
}

Every tool call is now cryptographically signed and hash-chained. Nothing else changes. The MCP server works exactly as before.

What it does

$ mcp-audit tail

✓ 14:32:01 github/create_pr                 234ms  bf7a2f62
✓ 14:32:03 github/list_issues                89ms  a1c4e890
✗ 14:32:05 fs/delete_file                    12ms  c3d9f012
✓ 14:32:08 github/merge_pr                  456ms  e5f6a7b8

Every entry is signed with HMAC-SHA256 and chained to the previous record. Tamper with any entry and verification fails. Delete an entry and the chain breaks.

Verify integrity

$ mcp-audit verify ~/.mcp-audit/audit.jsonl

Results:
  Total records: 847
  Valid: 847
  Invalid: 0

All records verified successfully.

How it works

┌────────────┐       ┌───────────┐       ┌────────────┐
│ MCP Client │──────▶│ mcp-audit │──────▶│ MCP Server │
│ (Claude,   │◀──────│   wrap    │◀──────│ (any)      │
│  Cursor)   │       └─────┬─────┘       └────────────┘
└────────────┘             │
                           ▼
                    ~/.mcp-audit/
                    audit.jsonl

The wrap command spawns your MCP server as a child process and sits between the client and server on stdio. It forwards ALL messages transparently. Only tools/call responses get signed and logged. Everything else passes through untouched.

On first run, a signing key is auto-generated in ~/.mcp-audit/key.hex. No configuration needed.

Audit record format

{
  "id": "bf7a2f62-4d0f-4cce-afd2-cbfbf7bca2a5",
  "timestamp": "2026-08-16T14:32:01.000Z",
  "method": "tools/call",
  "toolName": "github/create_pr",
  "args": {"title": "Fix bug", "body": "..."},
  "durationMs": 234,
  "success": true,
  "previousHash": "8a3f2b...",
  "attestation": "7c4d9e..."
}

The attestation is an HMAC-SHA256 signature over the record's canonical fields. The previousHash is SHA-256 of the preceding record. Together they detect tampering, ordering, and completeness.

Use with Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Use with Claude Code

.claude/hooks/mcp-servers.json or directly in your MCP server command — prefix with mcp-audit wrap --.

CLI

mcp-audit wrap -- <cmd> [args]    # Wrap any MCP server
mcp-audit tail                    # Live stream of tool calls
mcp-audit verify <log>            # Verify chain integrity
mcp-audit serve [config]          # Full gateway (policy + OTel)
mcp-audit keygen [dir]            # Generate Ed25519 key pair

Full gateway mode

For teams that also need access control, rate limiting, and multi-server routing:

mcp-audit serve gateway.config.json

The full gateway adds:

• Policy engine (glob-based ACLs, per-principal rate limits)
• Tool namespacing across multiple upstream MCP servers
• OpenTelemetry traces and metrics export
• Upstream health management with automatic reconnection
• Ed25519 signatures (stronger than HMAC, portable verification)

See gateway configuration for the full schema.

Install

npm install -g @mcp-audit-gateway/core

This installs the mcp-audit CLI globally. Or use without installing:

npx @mcp-audit-gateway/core wrap -- <your mcp server command>

Attestation layer

The signing and verification subsystem goes beyond per-record HMAC. Gateway mode signs each record with Ed25519 (asymmetric, verifiable with a public key) by default; HMAC-SHA256 is available for symmetric-secret deployments. Wrap mode uses HMAC-SHA256 with a per-user key auto-generated on first run. Records are hash-chained across log rotation, crash recovery, and multi-file chains.

Checkpoint records let a consumer detect tail truncation by stashing a single hash externally. The chain carries forward across file rotations (no silent resets). Forced restarts emit signed chain_break records instead of quietly starting fresh.

The canonical form is type-tagged and injective, avoids JCS's float-formatting problem by rejecting unsafe numbers entirely, and has proven cross-language parity via 46 conformance vectors (JS + Python). See SECURITY-DESIGN.md for the full specification and threat model.

Cross-SDK differential testing (10 SDKs, 26 divergences)

MCP has 10 official SDKs and no cross-SDK conformance testing. We built a Wycheproof-style differential harness that runs 40 serialization edge-case tests across all 10 SDKs and reports where they disagree.

Result: 26 wire-level divergences across 8 distinct serializers.

Headline findings

Float divergence example (1e20)

TypeScript:  100000000000000000000
Python:      1e20
Swift:       1e+20
Java:        1.0E20
C#:          1E+20
PHP:         1.0e+20

Six SDKs, six different bytes on the wire. If your hash-chain implementation assumes consistent serialization across SDKs, it breaks silently.

SDKs tested

Run it yourself

# Clone and run the full matrix
git clone https://github.com/elang2/mcp-audit-gateway.git
cd mcp-audit-gateway && npm ci

./test/vectors/cross-sdk-diff.sh              # full matrix (stdlib + SDK layers)
./test/vectors/cross-sdk-diff.sh --layer sdk  # SDK wire-level only
./test/vectors/cross-sdk-diff.sh --json       # machine-readable output

Output shows per-test agreement/divergence across all SDKs with exact byte representations.

Use in your CI

Drop this into .github/workflows/cross-sdk-conformance.yml to catch serialization regressions in your own MCP server or client:

name: Cross-SDK Conformance
on: [push, pull_request]

jobs:
  conformance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'

      - name: Install mcp-audit-gateway
        run: npm install @mcp-audit-gateway/core

      - name: Run cross-SDK differential tests
        run: |
          npx cross-sdk-diff --json > results.json
          npx cross-sdk-diff

      - name: Fail on new divergences
        run: |
          DIVS=$(python3 -c "
          import json
          with open('results.json') as f:
              d = json.load(f)
          print(sum(1 for x in d if not x['agree']))
          ")
          echo "Divergences found: $DIVS"
          if [ "$DIVS" -gt 26 ]; then
            echo "ERROR: New divergences detected (was 26, now $DIVS)"
            exit 1
          fi

Or run just the conformance vectors (no language SDKs required, only Node.js):

name: Canonicalization Conformance
on: [push, pull_request]

jobs:
  vectors:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: node test/vectors/verify-checkpoint.mjs
      - run: node test/vectors/aps-action-ref-v1.mjs

Methodology

The harness uses a Wycheproof-inspired approach: define edge-case inputs (floats at precision boundaries, non-ASCII strings, nested key orders), serialize them through each SDK's actual JSON encoder, and compare the raw bytes. No mocking. Each SDK runner imports the real serialization library that the official MCP SDK uses in production.

Full divergence table with per-test byte comparisons: SDK-AUDIT.md

The audit gateway's canonicalization was designed to be immune to all 26 divergence classes: safe integers only (eliminates float formatting), explicit field order (eliminates sort disagreements), surrogate rejection (eliminates encoding divergences). See SECURITY-DESIGN.md for the threat model.

Examples

Verify your canonicalization against ours

import { canonicalize } from '@mcp-audit-gateway/core';

const record = {
  method: 'tools/call',
  toolName: 'github/create_pr',
  args: { title: 'Fix bug', body: '...' },
  timestamp: '2026-08-16T14:32:01.000Z'
};

const canonical = canonicalize(record);
// Deterministic bytes regardless of key insertion order,
// float formatting, or platform JSON encoder

Python verification (cross-language parity)

from mcp_audit_gateway import verify_chain

results = verify_chain("/path/to/audit.jsonl")
assert results.valid == results.total
assert results.chain_breaks == 0

Run the conformance vectors against your own implementation

# 46 cross-language vectors (JS + Python must agree on every hash)
node test/vectors/verify-checkpoint.mjs
python3 test/vectors/verify-checkpoint.py

# 51 APS action-ref-v1 vectors
node test/vectors/aps-action-ref-v1.mjs

# Full 10-SDK matrix
./test/vectors/cross-sdk-diff.sh

Docker (self-contained, no host dependencies)

docker build -f test/vectors/Dockerfile -t cross-sdk-diff .
docker run --rm cross-sdk-diff

Conformance

This implementation satisfies the following properties (verified by cross-language conformance vectors and unit tests):

• Injective canonical form (no cross-type digest collisions)
• Cross-language sort equivalence (UTF-16 code-unit order)
• Unpaired surrogate rejection
• Hash chain continuity across log rotation
• Planted state detection on startup
• No false-positive after legitimate chain break
• Fail-closed on corrupt or oversized input
• Segmented monotonicity at chain_break boundaries
• Consumer-anchored completeness via checkpoint records
• Memory-bounded init (1MB cap)

APS action-ref-v1 conformance: 51/51 vectors passing (JCS recomputation + fail-closed digest comparison).

Testing

npm test                                    # unit tests
node test/vectors/verify-checkpoint.mjs     # JS conformance vectors
python3 test/vectors/verify-checkpoint.py   # Python conformance vectors
node test/vectors/aps-action-ref-v1.mjs     # 51 APS vectors
./test/vectors/cross-sdk-diff.sh            # 10-SDK differential test

License

MIT

The APS conformance fixtures (test/vectors/aps-action-ref-v1-vectors.json) are adapted from upstream Apache-2.0 sources. See test/vectors/SOURCE.md for provenance and terms.