elang2/mcp-audit-gateway

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:
After:
Every tool call is now cryptographically signed and hash-chained. Nothing else changes. The MCP server works exactly as before.
What it does
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
How it works
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
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:
Use with Claude Code
.claude/hooks/mcp-servers.json or directly in your MCP server command — prefix with mcp-audit wrap --.
CLI
Full gateway mode
For teams that also need access control, rate limiting, and multi-server routing:
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
This installs the mcp-audit CLI globally. Or use without installing:
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
| Category | What we found |
|----------|--------------|
| Float formatting | 6 SDKs produce 6 different wire representations of 1e20 |