Assay Protocol defines the verification contract for MCP gateways in the Assay ecosystem.
Assay Protocol is the spec and reference implementation for MCP gateways that can prove what tool-using AI systems did. It defines deny-by-default controls, tamper-evident receipts, and incident-response hooks for gateway-layer enforcement.
"Agents talk via MCP. Agents prove via Assay."
What this is: A specification and reference implementation for MCP gateway conformance — how to build gateways that produce cryptographic proof of every tool action.
What this isn't: An agent framework. If you want to build agents, look elsewhere. If you want to prove what your agents did, you're home.
Use this repo when: you are building or auditing an MCP gateway and need to know what controls, receipts, and conformance hooks are required.
Spec: v1.0.0-rc1
Fastest path: run the reference tests, then read FOR_HUMANS.md if you want the plain-English version before the spec.
cd reference/python_gateway
python3 -m venv .venv && source .venv/bin/activate # Windows: py -m venv .venv && .venv\Scripts\activate
pip install pytest
PYTHONPATH=src pytest tests/ -v
# 52 tests, ~0.05s
- Proof when things go wrong: Every tool action gets a receipt with timestamp, decision, and hash
- Deny-by-default protection: Nothing executes without explicit policy approval
- Incident response: Kill switch to disable compromised tools instantly
- Auditable trail: Signed receipts with hash chains (Ed25519, JCS-canonical)
Normative:
| File | Purpose |
|---|---|
| SPEC.md | Full RFC-style specification |
| MCP_MINIMUM_PROFILE.md | 9 MUSTs for MCP gateway conformance |
Informative:
| File | Purpose |
|---|---|
| FOR_HUMANS.md | Plain-English explainer |
| IMPLEMENTORS.md | Adoption checklists (Basic/Standard/Court-Grade) |
| CONTROL_MAP.md | MUST → Hook → Module → Test mapping |
| MCP_GATEWAY_MAP.md | Enforcement hooks + code patterns |
| REASON_CODES.md | Canonical reason codes |
| schemas/receipt.schema.json | JSON Schema for receipts |
| conformance/ | How to claim conformance |
| CONSTITUTIONAL_RECEIPT_STANDARD_v0.1.md | Receipt format spec (JCS, Ed25519, anchoring) |
reference/python_gateway/
├── src/assay_gateway/
│ ├── gateway.py # Main orchestration
│ ├── types.py # Core types + enums
│ ├── registry.py # MUST 1: Tool inventory
│ ├── authn.py # MUST 2: Authentication
│ ├── authz.py # MUST 3+4: Discovery + AuthZ
│ ├── credentials.py # MUST 5: No token passthrough
│ ├── preflight.py # MUST 7: Validation
│ ├── sandbox.py # MUST 8: Boundaries
│ ├── receipts.py # MUST 9: Receipts
│ └── incident.py # MUST 9: Kill switch
└── tests/
├── test_conformance.py # 22 conformance tests (9 MUSTs)
└── test_pccap.py # 30 PCCap capability tests
# Validate receipts and generate report + badge
python scripts/assay_validate.py path/to/receipts/ -o report.json --badge badge.svg
# Output:
# - PASS/FAIL for 7 conformance checks
# - JSON report (optionally signed)
# - SVG badge for embedding
# Generate Ed25519 keypair
python scripts/crypto_core.py keygen --key-id my-operator -o keys/
# Sign a receipt
python scripts/crypto_core.py sign receipt.json --key keys/my-operator.private.json
# Verify chain
python scripts/crypto_core.py verify r1.json r2.json r3.json --keys public_keys.json
Note: Install
cryptographyfor real Ed25519 signatures:pip install cryptography
- Security engineers who need to prove agent behavior to their CISO
- Platform teams building tool-using AI that needs guardrails
- Compliance teams preparing for EU AI Act and SOC 2 AI audit requirements
| Repo | Purpose |
|---|---|
| assay | Core CLI + SDK — evidence compiler for AI systems |
| assay-verify-action | GitHub Action for CI evidence verification |
| assay-ledger | Public transparency ledger |
| agentmesh | Multi-agent coordination and provenance |
Part of the Assay ecosystem. Created by Tim B. Haserjian.
CC BY 4.0 (specification text), MIT (reference implementation code).