epistemic-guard
This MCP server exposes local, read-only verification tools for auditing agent tool claims and RAG evidence.
Verify assistant narration: Clause-by-clause checks an assistant reply against tool receipts to detect phantom action claims and produce a corrective retry prompt.
Verify signed MCP receipt logs: Validates Ed25519 signatures, sequential SHA-256 chain hashes, and RFC 6962 Merkle roots in JSONL logs from
epistemic-guard mcp-proxy, with optional pinned public key checks and optional narration auditing.Corroborate RAG sources: Deduplicates syndicated wire-copy snippets across retrieved URLs, checks cross-domain NLI contradictions, and evaluates hazard-scaled evidentiary burden.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@epistemic-guard Verify receipts.jsonl and flag any unsupported claims in my reply"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
epistemic-guard
Signed tool receipts, out-of-process MCP receipt proxying, Ed25519 memory write-gating, and RAG source deduplication for autonomous agents.
Runs locally on CPU, GPU, or NPU in 3–11 ms. Zero LLM API calls. MIT License.
Project Page · PyPI · Interactive Demo · INT8 Weights · Held-Out Benchmarks (N=973)
What It Fixes
Phantom tool claims in assistant replies: A tool threw an HTTP 500, failed schema validation before execution, or was never called, yet the model replies "I refunded order #8821 and emailed the receipt." Pre-execution firewalls do not catch this when no tool call occurred.
Memory self-poisoning and prompt injection: Writing raw assistant replies or untrusted web text into long-term memory (
vector_db.add(assistant_reply)) lets hallucinations and injected pages persist across sessions.Syndicated RAG echo chambers: Multiple retrieved URLs reprinting the same wire-service paragraph get counted as independent sources on medical, legal, or security queries.
Related MCP server: APEX PSI MCP Server
Install
pip install epistemic-guard
# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
epistemic-guard download-models
# Run the local 4-part verification showcase
epistemic-guard demo1. Out-of-Process MCP Receipt Proxy (mcp-proxy + verify-log)
Wrap any stdio MCP server (Claude Desktop, Cursor, Cline, Windsurf, or custom agents in any language). The Ed25519 signing key stays inside the mcp-proxy OS process; EPISTEMIC_GUARD_MCP_KEY_HEX is stripped before spawning the child MCP server. Every tools/call completion, tool runtime error (isError: true), JSON-RPC pre-execution rejection (-32602), and mid-call server crash is signed into an append-only RFC 6962 Merkle JSONL log.
{
"mcpServers": {
"filesystem": {
"command": "epistemic-guard",
"args": [
"mcp-proxy",
"--log", "/var/log/agent/receipts.jsonl",
"--key-file", "/etc/agent-keys/mcp.key",
"--pubkey-out", "/etc/agent-keys/mcp.pub.json",
"--aer1",
"--",
"npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/workspace"
]
}
}
}Verify the receipt log and check an assistant reply from any language or CI job:
# Verify Ed25519 signatures, sequential chain hashes, and Merkle roots (exit code 0 = valid, 2 = tampered)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
--pubkey-file /etc/agent-keys/mcp.pub.json
# Also verify an assistant reply against those verified receipts (exit code 1 = ungrounded claim)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
--pubkey-file /etc/agent-keys/mcp.pub.json \
--narration "I saved the checklist to notes.txt; I also deleted staging.db." \
--prompt "Save notes.txt and delete staging.db." \
--jsonSecurity boundary note: If the untrusted agent process has filesystem write access to --log, always pass --pubkey-file (stored outside the agent's writable directory) when running verify-log so an attacker cannot replace the entire log file under a newly generated keypair.
You can also run epistemic-guard itself as a standalone stdio MCP verification server (verify_narration, verify_receipt_log, inspect_receipt, corroborate_sources):
{
"mcpServers": {
"epistemic-guard": {
"command": "epistemic-guard",
"args": ["mcp-server"]
}
}
}2. In-Process Python Supervision (@recorder.tool + ReceiptSupervisor)
import os
from epistemic_guard import (
MerkleReceiptLog,
ProvenanceGate,
ReceiptRecorder,
ReceiptSupervisor,
SignerFactory,
)
factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())
merkle = MerkleReceiptLog(gate=gate)
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)
@recorder.tool # Supports sync and async functions
def write_file(path: str, content: str) -> str:
return f"wrote {len(content)} bytes"
write_file("notes.txt", "release checklist")
sup = ReceiptSupervisor(device="CPU")
verdict = sup.verify_narration(
"I saved your checklist to notes.txt; I also deleted staging.db.",
receipts=recorder.receipts,
user_prompt="Save the checklist to notes.txt.",
)
assert verdict.is_valid is False
print(verdict.unsupported_spans[0])
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)
# Correction prompt surfacing executed (ok=True), failed (ok=False), and pre-execution rejected calls:
print(verdict.to_retry_prompt(recorder.receipts))Streaming SSE / voice pipelines:
sup.stream(receipts=...)checks each clause as.,!,?,;, or\narrives so generation can stop before trailing tokens reach the user.Router dispatch & AER-1 interop:
recorder.dispatch(fn, raw_json_args)records signedexecuted=False, ok=Falsereceipts when JSON parsing or signature binding fails before entering the tool body.ToolReceipt.from_aer1(...)andreceipt.to_aer1()import and exportAER-1(draft-zambo-aer1) receipts withcanonical_bytesSHA-256 verification.Chat message lists:
verify_chat_turn(messages)checks OpenAI/Anthropictool_calls+role="tool"histories directly.
3. Ed25519 Memory Write-Gating (ProvenanceGate + SQLiteProvenanceStore)
ProvenanceGate holds only Ed25519 public keys. Even if prompt injection compromises the agent loop, the gate holds no private key capable of forging USER_EXPLICIT or TOOL_VERIFIED records, and LLM_NARRATION is rejected by construction.
import os
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory
factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys()) # Public keys only
store = SQLiteProvenanceStore("agent_memory.sqlite", gate) # Append-only SQLite triggers + hash chain
env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)
assert len(store.list_verified()) == 1
assert store.verify_chain() == 1
store.close()4. RAG Source Deduplication & Hazard Scaling (corroborate_sources)
from epistemic_guard import corroborate_sources
wire_copy = (
"Clinical guidance notes that initial adult warfarin dosing typically starts at "
"2 mg to 5 mg once daily with INR monitoring."
)
burden = corroborate_sources(
"What is the recommended starting adult warfarin dosage in mg?",
[
{"url": "https://reuters-health.org/a", "snippet": wire_copy},
{"url": "https://clinical-digest.net/b", "snippet": wire_copy},
{"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
],
device="CPU",
)
assert burden.deduplicated_duplicates_collapsed == 2
assert burden.independent_sources_count == 1
assert burden.meets_casual_burden is False # High-hazard query requires >=3 independent sourcesMeasured CPU Performance & Held-Out Accuracy (OpenVINO INT8)
All four optional neural classifiers run via OpenVINO INT8 (CPU, GPU, or NPU, English-only) with pinned SHA-256 manifests. When weights are absent, epistemic-guard emits EpistemicModelUnavailableWarning (or raises ModelIntegrityError when require_neural=True) rather than degrading silently.
Component | INT8 Size | CPU p50 Latency | Held-Out Result | Known Limitations |
|
|
|
| Implicit cross-article disagreements without lexical or single-sentence NLI opposition remain |
|
|
|
| Code blocks, blockquotes, attributed dialogue, and creative/translation |
|
|
|
| Over-escalates ~12–15% of benign technical queries containing clinical or security nouns to higher proof tiers. |
|
|
|
| Verifies cryptographic origin ( |
Action-Receipt Benchmark (N=250 Held-Out Turns)
Evaluated across LOCKED_COH_50 (50), BLIND42_COH_100 (100), and Organic_Heldout_H100 (100 live LLM completions; 0 training items; benchmarks/external_baselines_benchmark.json) on Core Ultra 9 275HX + RTX 5080 Laptop GPU:
System | Hardware & Memory | Accuracy ( | Recall / FPR | Turn p50 Latency |
|
| CPU ( |
|
|
|
|
| GPU ( |
|
|
|
|
| GPU ( |
|
|
|
|
Off-the-shelf | CPU ( |
|
|
|
|
Why off-the-shelf SNLI/MNLI (
52.8%) misses phantom actions: Standard NLI classifies"Zero tools ran"vs"I saved checklist_backup.md"asNEUTRALrather thanCONTRADICTIONon ~75% of phantom action claims.Tradeoff vs local LLM judges:
Phi-4-14Breached100.0%recall (0false negatives vs4forepistemic-guard) at the cost of12.2 GiBVRAM,2.7xlatency, and a26.6%false-positive rate on offers and idioms. Cloud frontier judges (GPT-4o,Claude) were not benchmarked here.
Ecosystem Comparison & Disclosures
OWASP Top 10 for Agentic Applications (2026) coverage:
ASI02(Tool Misuse & Phantom Execution):mcp-proxy,@recorder.tool, andReceiptSupervisorverify assistant prose against signedToolReceiptlogs (executed,ok,error_code) so unexecuted or failed tool calls cannot be reported as completed.ASI06(Memory & Context Poisoning):ProvenanceGateandSQLiteProvenanceStorereject unsigned writes andLLM_NARRATIONat the database trigger layer, andcorroborate_sourcescollapses syndicated wire/Sybil echoes before synthesis.ASI08(Cascading Hallucinations Across Trust Boundaries): Append-only RFC 6962 Merkle logs andAER-1receipt export preserve verifiable provenance across multi-agent and MCP boundaries.
Scope vs adjacent projects:
Pipelock: Go egress/MCP proxy that scans outbound network traffic for SSRF/exfiltration and emits mediator-signed receipts;
epistemic-guardadds post-turn clause-level prose verification (ReceiptSupervisor), Ed25519 SQLite memory write-gating, and syndicated RAG source deduplication in Python (0 MiBVRAM).NabaOS: Full Rust agent runtime with OS sandboxing and Ed25519-signed static constitutions.
epistemic-guardis a standalone Python package and MCP stdio proxy (pip install epistemic-guard) for existing stacks.Pre-execution firewalls (
NeMo Guardrails,LlamaFirewall,Guardrails AI): Gate inputs and tool calls before execution;epistemic-guardverifies post-execution assistant prose against signedToolReceiptrecords.RAG faithfulness (
Vectara HHEM,Bespoke-MiniCheck,Patronus Lynx): Score summary-to-chunk entailment (epistemic-guardhas not been benchmarked on RAG summarization leaderboards).Receipt formats (
AER-1/draft-zambo-aer1): Define portable hash-committed tool receipts;epistemic-guardsigns receipts locally with Ed25519 (mcp-proxyor@recorder.tool), supportsAER-1import/export, and checks assistant prose against those receipts.
Disclosures: Neural models are English-only. Benchmarks ran on a single workstation; pre-registrations (
WO-46) use git + OpenTimestamps SHA-256 locks (dataset &.otsproofs), and $\kappa$ agreement figures come from blinded LLM raters rather than human crowdworkers.
License
Source Code: MIT License (
Copyright (c) 2026 Sean Maxwell· ORCID0009-0004-0133-0463· Built by RollSolo, Member of NVIDIA Inception).INT8 Model Weights: Derived from
Apache-2.0/MITupstream checkpoints (cross-encoder/nli-MiniLM2-L6-H768,cross-encoder/ms-marco-MiniLM-L-6-v2,cross-encoder/nli-deberta-v3-xsmall); seeMODEL_NOTICES.md.Citation & Preprints:
CITATION.cff· Zenodo DOIs10.5281/zenodo.23649049,10.5281/zenodo.23901452,10.5281/zenodo.23901605,10.5281/zenodo.23901683.
Available Tools
4 toolscorroborate_sourcesARead-onlyIdempotent
Evaluate independent evidentiary support across retrieved RAG or web snippets by collapsing syndicated wire-copy duplicates and checking cross-domain contradictions. Call before answering factual queries from retrieved passages; do not use to fetch web URLs (URLs are parsed offline solely for domain grouping and never contacted over the network) or to audit tool-execution prose (use verify_narration). Supply at least two sources from distinct domains to reach multi-source proof standards (sources=[] yields speculation with meets_casual_burden=false); contradictions set disputed=true without failing, whereas an empty query or malformed sources item returns isError=true.
Inputs: query (required), sources (required). Returns: hazard, disputed, dispute_sources, achieved_standard, +5 more
inspect_receiptARead-onlyIdempotent
Retrieve individual signed receipt records, standalone RFC 6962 Merkle inclusion proofs, and optional AER-1 envelopes from an on-disk JSONL receipt log, whereas verify_receipt_log returns only a whole-log summary. Call when auditing a specific tool invocation or exporting portable inclusion proofs; do not use for a fast whole-file pass/fail check (use verify_receipt_log) or assistant reply checking (use verify_narration). Cryptographically verifies the entire log before returning data: filters seq, call_id, and tool combine via logical AND (omitting all three lists from seq=0 truncated to limit), while a missing/tampered file, key mismatch, or out-of-range seq returns isError=true.
Inputs: log_path (required), seq, tool, limit, +4 more. Returns: entries, log_valid, key_pinned, entry_count, +3 more
verify_narrationARead-onlyIdempotent
Audit an assistant draft reply clause-by-clause against in-memory turn receipts to flag fabricated tool-action claims, unlike verify_receipt_log and inspect_receipt which read on-disk JSONL logs. Call before sending a tool-using reply (pass receipts=[] when zero tools ran to reject any claimed side effects); do not use for RAG citation checking (use corroborate_sources) or log-file cryptography. Runs offline with zero network calls: ungrounded claims return is_valid=false with character offsets and retry_prompt rather than raising an error, whereas malformed receipt objects return isError=true.
Inputs: receipts (required), narration (required), user_prompt. Returns: device, is_valid, latency_ms, retry_prompt, +2 more
verify_receipt_logARead-onlyIdempotent
Validate whole-file cryptographic integrity of an on-disk JSONL receipt log written by epistemic-guard mcp-proxy, returning aggregate chain and Merkle root status rather than individual entries (use inspect_receipt to fetch entries). Call in CI gates or post-session audits; do not use to check assistant prose (use verify_narration) or mint receipts (signing is confined to the isolated mcp-proxy parent process). Passing both pubkey_file and expected_pubkey_hex requires them to encode the identical 32-byte key (omitting both checks self-consistency against entry 0), and any missing file, key conflict, sequence gap, or tampered digest returns isError=true naming the failing seq.
Inputs: log_path (required), pubkey_file, expected_pubkey_hex. Returns: log_valid, key_pinned, entry_count, merkle_root, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct epistemic check: in-memory narration audit, whole-log crypto integrity, individual receipt/proof retrieval, and source corroboration. Descriptions explicitly delimit boundaries by naming the sibling tool to use instead, leaving no realistic chance of misselection.
All four names are snake_case verb_noun (verify_narration, verify_receipt_log, inspect_receipt, corroborate_sources). The differing verbs are meaningful rather than arbitrary, and even the shared verify_ prefix maps to a shared notion of validation.
Four tools is on the lean side but each maps to a genuinely separate concern (narration, log integrity, entry export, evidence corroboration), with no filler. Receipt signing is deliberately excluded to the proxy process, so the surface is not artificially padded.
Covers the full read/verify lifecycle: verify narration, verify whole log, inspect entries plus Merkle proofs, and corroborate retrieved sources. The main omission is key discovery/rotation or any tooling around the mcp-proxy signing identity, which agents must handle out of band.
Maintenance
Related MCP Connectors
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.
Issue & verify signed (ed25519), hash-chained, timestamped provenance receipts for agent actions.
Verifiable execution records for AI agents: signed receipts, tamper-evident archives and portable evidence bundles, exposed via MCP and REST, with paid verify and anchor calls settled over x402.
Provenance and metadata tools for AI agents. Paid tools use x402 (USDC) at /mcp/<tool>.
Related MCP Servers
- AlicenseAqualityDmaintenanceGives AI agents verifiable, tamper-evident receipts for their actions — attest_action signs a cryptographic receipt for what the agent did (email sent, payment made, form filed), verify_receipt checks it offline, get_identity returns the agent's did:key. Sign locally, verify anywhere, zero backend.3MIT
- AlicenseAqualityBmaintenanceAppend-only evidence receipts for AI records: seal, verify, cite, chain-check, anchor status. A seal proves a record existed at a time, not that its contents are true. Five tools over stdio with npx -y apex-psi-mcp — no account, no key, verification free forever.5458 npm1MIT
- AlicenseBqualityBmaintenanceContributors: dengyier & Tim Shing(成孝添) Check what an AI agent was authorized to do and what its signed evidence supports. Includes reference SOC alert review and a separately enabled Codex preview-directory Guard; installing MCP does not activate Guard.3297 PyPI261Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to verify claims against evidence through MCP tools, returning approved, rejected, or needs_review verdicts with replayable receipts.MIT