mcp-audit

Ihr KI-Agent hat gestern 847 Tool-Aufrufe ausgeführt. Können Sie überprüfen, was er getan hat?

Manipulationssicheres Audit-Protokoll für KI-Agenten-Tool-Aufrufe.

Einrichtung (10 Sekunden)

Vorher:

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

Nachher:

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

Jeder Tool-Aufruf ist jetzt kryptografisch signiert und hash-verkettet. Sonst ändert sich nichts. Der MCP-Server funktioniert genau wie zuvor.

Related MCP server: DCL Evaluator

Was es tut

$ 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

Jeder Eintrag ist mit HMAC-SHA256 signiert und mit dem vorherigen Datensatz verkettet. Manipulieren Sie einen Eintrag, schlägt die Verifizierung fehl. Löschen Sie einen Eintrag, bricht die Kette.

Integrität prüfen

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

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

All records verified successfully.

So funktioniert es

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

Der Befehl wrap startet Ihren MCP-Server als Kindprozess und sitzt zwischen Client und Server auf stdio. Er leitet ALLE Nachrichten transparent weiter. Nur tools/call-Antworten werden signiert und protokolliert. Alles andere passiert unverändert.

Beim ersten Start wird automatisch ein Signaturschlüssel in ~/.mcp-audit/key.hex erzeugt. Keine Konfiguration erforderlich.

Format des Audit-Datensatzes

{
  "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..."
}

Die attestation ist eine HMAC-SHA256-Signatur über die kanonischen Felder des Datensatzes. Der previousHash ist der SHA-256-Hash des vorherigen Datensatzes. Zusammen erkennen sie Manipulation, Reihenfolge und Vollständigkeit.

Verwendung mit 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"]
    }
  }
}

Verwendung mit Claude Code

.claude/hooks/mcp-servers.json oder direkt in Ihrem MCP-Server-Befehl – mit mcp-audit wrap -- voranstellen.

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

Vollständiger Gateway-Modus

Für Teams, die auch Zugriffskontrolle, Ratenbegrenzung und Multi-Server-Routing benötigen:

mcp-audit serve gateway.config.json

Der vollständige Gateway fügt hinzu:

• Policy-Engine (glob-basierte ACLs, Ratenbegrenzungen pro Prinzipal)

• Tool-Namespacing über mehrere vorgelagerte MCP-Server

• OpenTelemetry-Traces und Metrik-Export

• Upstream-Health-Management mit automatischer Wiederverbindung

• Ed25519-Signaturen (stärker als HMAC, portable Verifizierung)

Siehe Gateway-Konfiguration für das vollständige Schema.

Installation

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

Dies installiert die mcp-audit-CLI global. Oder ohne Installation verwenden:

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

Attestierungsebene

Das Signatur- und Verifizierungssubsystem geht über das HMAC pro Datensatz hinaus. Es bietet Manipulationsnachweis über Log-Rotation, Crash-Recovery und Multi-Datei-Ketten hinweg.

Checkpoint-Datensätze ermöglichen es einem Konsumenten, Kürzungen am Ende zu erkennen, indem ein einzelner Hash extern gespeichert wird. Die Kette wird über Datei-Rotationen hinweg fortgeführt (keine stillen Neustarts). Erzwungene Neustarts erzeugen signierte chain_break-Datensätze, anstatt stillschweigend neu zu beginnen.

Die kanonische Form ist typmarkiert und injektiv, vermeidet JCS' Float-Formatierungsproblem, indem unsichere Zahlen vollständig abgelehnt werden, und hat nachweislich sprachübergreifende Parität über 46 Konformitätsvektoren (JS + Python). Siehe SECURITY-DESIGN.md für die vollständige Spezifikation und das Bedrohungsmodell.

SDK-übergreifende Differenztests

MCP hat 10 offizielle SDKs und keine SDK-übergreifenden Konformitätstests. Wir haben einen Wycheproof-artigen Differenz-Harness gebaut, der 40 Serialisierungs-Grenzfälle über alle 10 SDKs ausführt und meldet, wo sie abweichen.

Ergebnisse: 26 Wire-Level-Abweichungen über 8 verschiedene Serialisierer. Sechs verschiedene Darstellungen von 1e20. Drei inkompatible Schlüssel-Sortieralgorithmen. TypeScript verliert stillschweigend Integer-Präzision bei 2^53+1. C# escaped Zeichen, die kein anderes SDK escaped. Das Python-SDK erzeugt unterschiedliche Bytes über pydantic-core-Versionen hinweg für denselben Codepfad.

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

Die Kanonisierung des Audit-Gateways wurde entwickelt, um gegen alle 26 Abweichungsklassen immun zu sein: nur sichere Ganzzahlen, explizite Feldreihenfolge, Surrogat-Ablehnung. Siehe SDK-AUDIT.md für die vollständige Abweichungstabelle und Methodik.

Konformität

Diese Implementierung erfüllt die folgenden Eigenschaften (verifiziert durch sprachübergreifende Konformitätsvektoren und Unit-Tests):

• Injektive kanonische Form (keine kollidierenden Digests über Typen hinweg)

• Sprachübergreifende Sortieräquivalenz (UTF-16-Code-Unit-Reihenfolge)

• Ablehnung ungepaarter Surrogate

• Kontinuität der Hash-Kette über Log-Rotation hinweg

• Erkennung manipulierter Zustände beim Start

• Keine Fehlalarme nach legitimer Kettenunterbrechung

• Fail-closed bei beschädigter oder übermäßig großer Eingabe

• Segmentierte Monotonie an chain_break-Grenzen

• Vollständigkeit durch Verankerung beim Konsumenten über Checkpoint-Datensätze

• Speicherbegrenzte Initialisierung (1-MB-Obergrenze)

APS action-ref-v1-Konformität: 51/51 Vektoren bestanden (JCS-Neuberechnung + Fail-closed-Digest-Vergleich).

Tests

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

Lizenz

MIT

Die APS-Konformitäts-Fixtures (test/vectors/aps-action-ref-v1-vectors.json) sind aus Apache-2.0-Quellen von Drittanbietern übernommen. Siehe test/vectors/SOURCE.md für Herkunft und Bedingungen.