🔐 MCP Witness

Cryptographic proof of every AI decision. An immutable, verifiable audit trail MCP server — because "trust me bro" isn't SOC2 compliant.

pip install mcp-witness
mcp-witness quickstart

✨ Why mcp-witness?

AI agents make decisions. Regulators ask questions. mcp-witness provides cryptographic proof of what happened, when, and why — with hash chain integrity, Merkle tree verification, Ed25519 signatures, external trust anchoring (RFC 3161 TSA strict mode with optional local attestation, OpenTimestamps for structural verification, IPFS), and compliance presets for HIPAA, GDPR, SOC2, and more.

🔒 Assurance Levels

As of v1.0.0, mcp-witness is secure-by-default: it refuses to start without a persistent signing key and fails closed if the chain does not verify at startup. Each default has an opt-out — see docs/configuration.md.

⚠️ Known Limitations

Anchoring is asynchronous. Records are created first, then anchored later when a checkpoint triggers AnchorService. Between record creation and checkpoint anchoring, records exist without external trust proof. Use witness_attest to anchor individual records immediately.

Single-node storage. SQLite (default) and PostgreSQL backends are single-instance. No built-in replication, clustering, or HA. Back up your database regularly. See docs/backup.md.

Encryption at rest is opt-in. Set MCP_WITNESS_ENCRYPTION_KEY (32-byte hex) to enable AES-256-GCM field-level envelope encryption. Without it, sensitive fields are stored as plaintext JSON.

⬆️ Upgrading from 0.9.x

v1.0.0 changes several defaults. To upgrade smoothly:

1. Set a signing key: export MCP_WITNESS_SIGNING_KEY=$(openssl rand -hex 32) (or MCP_WITNESS_REQUIRE_PERSISTENT_KEY=false to keep ephemeral keys).

2. Verify your chain first: mcp-witness verify (or set MCP_WITNESS_FAIL_ON_STARTUP_VERIFICATION_FAILURE=false).

3. If a webhook targets an internal collector, set MCP_WITNESS_ALLOW_INTERNAL_WEBHOOKS=true.

See the full configuration reference and SECURITY.md for the threat model.

Related MCP server: cronozen-proof

🚀 30-Second Quickstart

# Install
pip install mcp-witness

# One command: init + serve
mcp-witness quickstart
# ✅ Database ready: ~/.mcp-witness/witness.db
# 📋 Next Steps:
#    1. Configure signing:  export MCP_WITNESS_SIGNING_KEY=$(openssl rand -hex 32)
#    2. Configure HMAC:     export MCP_WITNESS_HMAC_KEY=$(openssl rand -hex 32)
#    3. Start dashboard:    mcp-witness dashboard
#    4. Add to Claude:      claude mcp add witness -- mcp-witness serve

# Or go step-by-step:
mcp-witness init        # Initialize database
mcp-witness serve       # Start MCP server

# Check system health
mcp-witness stats       # Chain statistics
mcp-witness verify      # Chain integrity check
mcp-witness dashboard   # Web dashboard on :9090
mcp-witness report      # Generate compliance report

Claude Desktop Integration

{
  "mcpServers": {
    "witness": {
      "command": "mcp-witness",
      "args": ["serve"],
      "env": {
        "MCP_WITNESS_DB": "~/.mcp-witness/witness.db",
        "MCP_WITNESS_HMAC_KEY": "<32-byte hex key>",
        "MCP_WITNESS_SIGNING_KEY": "<32-byte hex seed for Ed25519>",
        "MCP_WITNESS_CHECKPOINT_INTERVAL": "1000",
        "MCP_WITNESS_AUTO_ANCHOR": "false",
        "MCP_WITNESS_WEBHOOK_URL": "https://alerts.example.com/witness",
        "MCP_WITNESS_LOG_FORMAT": "json"
      }
    }
  }
}

🛠️ CLI Reference

mcp-witness quickstart           One-command init + serve with next steps
mcp-witness serve                Start the MCP server
mcp-witness init                 Initialize database
mcp-witness verify [--fast]      Verify hash chain integrity
mcp-witness stats                Chain health dashboard
mcp-witness export [--output]    Export audit report
mcp-witness report [--format]    Generate HTML/PDF compliance report
mcp-witness proof SEQUENCE       Merkle proof for a record
mcp-witness search QUERY         Full-text search across audit records
mcp-witness checkpoints          List Merkle checkpoints
mcp-witness dashboard            Start web dashboard (default :9090)
mcp-witness anchors create ID    Anchor to TSA/Bitcoin/IPFS
mcp-witness anchors verify ID    Verify external anchor receipts

🛠️ MCP Tools (17 Total)

🏛️ Compliance Presets

One command. Full compliance baseline.

# Via MCP tool:
witness_configure_compliance(preset="hipaa")
# → 6-year retention, auto-redacts 12 PHI fields, requires attestation

witness_configure_compliance(preset="gdpr")
# → Right-to-erasure support, consent records, 12 PII fields redacted

witness_configure_compliance(preset="soc2")
# → 1-year retention, API key redaction, quarterly audit schedule

📊 How It Works

Hash Chain + Merkle Trees + Ed25519 Signatures

Records:    [R0] → [R1] → [R2] → ... → [R999] → [R1000] → ...
           ✍️🔑    ✍️🔑    ✍️🔑              ✍️🔑       ✍️🔑
           Ed25519 Ed25519 Ed25519          Ed25519     Ed25519
                                                   ↓
                                           [Checkpoint #1]
                                           Merkle Root: abc123
                                           Covers: records 0-999
                                                   ↓
                                           [External Anchors]
                                           🕐 TSA (RFC 3161)
                                           ₿  OpenTimestamps
                                           🌐 IPFS

Merkle Tree:         root_hash
                    /         \
               hash_01        hash_23
               /    \         /    \
            h_0    h_1      h_2    h_3
             ↓      ↓        ↓      ↓
          R0:R0h  R1:R1h  R2:R2h  R3:R3h

Every record is signed with Ed25519 for non-repudiation (signing key auto-generated if not configured).

Tamper Detection: Change any record → its hash changes → signature invalid → Merkle root changes → checkpoint invalidated → external anchors prove when the real root existed.

GDPR Right to Erasure: witness_delete nulls data fields but preserves the hash chain — records can be redacted without breaking integrity verification.

Verification Performance

Single record: O(log n) with Merkle proof (vs O(n) linear scan).

🔒 Security

• SHA-256 hash chain with null-byte delimiters to prevent collision attacks

• Ed25519 JWT assertions — signed JSON Web Tokens as alternative to shared API keys

• Ed25519 record signing — persistent signing key required by default for non-repudiation (MCP_WITNESS_SIGNING_KEY)

• SSRF-guarded webhooks — alert URLs are blocked from reaching internal/metadata addresses

• HMAC key protection — optional server-side secret makes hashes un-recomputable

• RFC 3161 TSA anchoring — legal-grade timestamps (strict mode; local attestation in degraded mode)

• OpenTimestamps — structural verification (full Bitcoin confirmation requires external OTS client)

• IPFS content addressing — CIDv0/CIDv1 computation with gateway verification

• Domain-separated Merkle trees — prevents second-preimage attacks

• Atomic transactions — BEGIN IMMEDIATE prevents race conditions and chain forks

• Rate limiting — configurable token bucket (DB-backed)

• RBAC — role-based access control for read-only audit deployments

• Error sanitization — stack traces never leak to clients

• Path traversal protection — exports confined to allowed directories

• Idempotency — nonce-based replay attack prevention with per-row TTL cleanup

• Webhook alerts — POST to configurable URL on chain integrity failure

• Structured logging — optional JSON log format for production monitoring

See CONTRIBUTING.md for the security disclosure policy.

🐳 Docker

# Build
docker build -t mcp-witness .

# Run MCP server (stdio)
docker run -v witness-data:/data mcp-witness serve

# Run web dashboard
docker run -v witness-data:/data -p 9090:9090 mcp-witness dashboard

# With PostgreSQL
docker run -v witness-data:/data \
  -e MCP_WITNESS_BACKEND=postgresql \
  -e MCP_WITNESS_PG_URL=postgresql://user:pass@host:5432/db \
  mcp-witness serve

🧪 Development

git clone https://github.com/edwiniac/mcp-witness.git
cd mcp-witness
pip install -e ".[dev]"
pytest -v                    # 343 unit tests
pytest --ignore=tests/test_storage_pg.py  # Skip PG (needs PostgreSQL)

CI/CD Pipeline

🗺️ Roadmap

• Core hash chain (v0.1.0)

• Merkle checkpoints + external anchoring (v0.2.0)

• CLI + compliance presets + security hardening (v0.3.0)

• PostgreSQL backend (v0.5.0)

• Ed25519 record signing + non-repudiation (v0.6.0)

• GDPR right to erasure + schema migrations (v0.6.0)

• Web dashboard with live API (v0.6.0)

• HTML + PDF compliance reports (v0.6.0)

• Structured JSON logging (v0.6.0)

• Multi-tenancy (v0.6.0)

• Webhook alerts on chain failure (v0.6.0)

• Full-text search (v0.6.0)

• Adversarial hardening — TSA strict mode, canonical signing, crypto agility, key lifecycle (v0.9.0)

• Merkle proof strict validation + envelope encryption + metrics (v0.9.0)

• PostgreSQL full backend parity + sensitive data log scrubbing (v0.9.0)

• Secure-by-default hardening — required signing key, fail-closed startup, SSRF guard, ASSURANCE-3 (v1.0.0)

• Streaming architecture (Kafka/NATS)

• AWS KMS / cloud HSM signing

• Grafana/Prometheus metrics endpoint

• Plugin system for custom anchor providers

• Post-quantum cryptographic algorithm support (tracking NIST PQC)

📄 License

MIT — see LICENSE

👤 Author

Edwin Isac — AI Engineer
GitHub · Email