Proposal: Auditable MCP: tool-internal audit events sealed into a host-side tamper-evident ledger #3112

BTW, I've also published the reference SDKs (Python/TS) that implement this.
I hope you can use those whenever you ever need tool audit logs.
I would greatly appreciate it if you could give me any feedback. Thx.

SatoshiImai/auditable-mcp-sdk-ts
SatoshiImai/auditable-mcp-sdk-python

Two things security reviewers ask about, which might be worth stating explicitly in the proposal:

1. Who can write to the ledger, and can a tool revise what it already declared? Saying that plainly is stronger than leaving it implied by the hash chain.
2. When one workflow spans tools from three vendors, can their records be lined up into a single sequence? If they don't compose, the customer is still assembling evidence by hand at audit time.

This is close to something we built independently, so a few notes from the same trench — and @grabdoc's first question is the one I'd most encourage you to answer explicitly in the proposal, because we got it wrong at first.

On "can a tool revise what it already declared": a hash chain proves internal consistency — that this sequence hasn't been edited since it was written. It does not prove authorship, and an actor holding the whole log can rewrite every link from scratch and present a perfectly valid chain. That distinction matters in a regulated setting: an auditor asking "could the operator have fabricated this?" is not answered by chain validity alone. What closes it is a signature from a key the operator doesn't hold, or an external anchor (a periodic head-hash published somewhere they don't control). Host-side sealing is a real step toward that — it moves the pen out of the tool's hand — but it's worth stating plainly which threat it does and doesn't cover, because "tamper-evident" gets read as "tamper-proof" by exactly the people who need the difference.

On cross-language byte-identical chains: we do the same (RFC 8785, Python + TypeScript, vectors generated by the Python side and asserted on every commit), and the sharpest edge we hit was numbers. JCS defers to ECMAScript Number::toString, and Python's int/float split doesn't line up with JavaScript's single number type. 1e21 is the fun one: Python encodes it happily as a float, and we initially added a safe-integer guard that rejected it on the JS side. That guard turned out to be theatre — by the time a value reaches the canonicalizer, 1234567890123456789 has already become 1234567890123456800 in the JS parser, so rejecting it prevented nothing while breaking agreement. We removed it and pinned behaviour with shared vectors instead. If your two SDKs agree on 1e21, 1e-7, and integers past 2^53, you've covered what bit us.

On composing records across vendors (@grabdoc's second question): I don't have a good answer, and I suspect it's the harder half. Chains from three tools compose into one timeline only if they agree on identity — what makes two records refer to the same operation. In our work that question (what makes two calls "the same call") turned out to be domain-specific and the easiest thing to get wrong: too narrow gives false duplicates; too wide collapses two legitimately different operations into one, which looks like success and is far worse. A shared record format doesn't settle it by itself.

One field worth considering: whether the effect was confirmed by the system of record, kept strictly distinct from "we believe we did it". In audit terms "we sent it" and "the provider confirms it exists" are different claims, and collapsing them is how a log ends up attesting to something that never landed.

Ours is at https://github.com/aurumflux20/once-kernel-ts (Apache-2.0, once-kernel/ledger) if a second implementation is useful to compare against — offering it mainly as a cross-check on number encoding, since two independent implementations disagreeing is how you find those cases. Happy to run your vectors against ours if that would help.

Hi @SatoshiImai ,

Really glad to see this. I was putting together a proposal for essentially the same problem and found this SEP already in flight. Saved me from filing a duplicate.

I built something that might be useful here. It's an intermediary that produces tamper-evident records transparently for any MCP server without modifying it (https://github.com/elang2/mcp-audit-gateway). Wraps via stdio, intercepts tools/call responses, signs them, chains them. The wrapped server has no idea attestation is happening.

Reading through the SEP, I think the deployment model is the piece that's complementary to what you've specified. You've nailed the record format and verification. What I kept running into while building the gateway was the "who holds the signing key" question — putting it in an operator-controlled intermediary means the tool server can't forge and the client can't suppress. Might be worth a note in the SEP about where in the stack record production happens, even if it stays non-normative.

One thing I'd want to align on: my canonicalization uses a fixed-order tuple array rather than sorted-JSON. Different tradeoffs but same goal. I'd rather converge on whatever this SEP lands on than have two incompatible forms out there. Once the format stabilizes I'll run the conformance vectors against my implementation.

Is there anything specific you'd find useful from the gateway side? Happy to contribute.

@eason4kim-rocket Yeah the safe integer point is a good one. The vectors I put up already stay within those bounds (only numeric fields are durationMs and errorCode, both well under 2^53), but worth making that an explicit constraint in whatever the SEP lands on. The dual-hash demo might be useful for your testing too since it shows exactly where signing serialization and chaining serialization diverge at the byte level. Happy to compare notes if you run them against your implementation.

@eason4kim-rocket Good timing on the comparative diff. A few things to know before you run:

Pin to the v0.4.0 tag (https://github.com/elang2/mcp-audit-gateway/tree/v0.4.0/test/vectors) rather than main. The vectors stabilized this week after the in-toto attestation predicate review (in-toto/attestation#588) caught a couple of things that tightened the design.

The main one that'll affect your conformance run: chain_break successors chain from the break record's own hash, not a fresh "genesis." If your pipeline resets to a genesis state after a discontinuity, the vectors will fail you there. The reasoning is that chaining from the break hash makes the scar undeletable. Remove the break record and linkage breaks. It's a stronger guarantee than restart-from-zero.

The canonicalization split you validated is now explicitly scoped in the vectors: canonicalization.json covers the signing form (tuple-array, integer-only, float-rejecting), checkpoint.json covers chain_break and rotation continuity. Your pipeline's JCS content-digest path should pass without issues since it's the same RFC 8785 both sides ended up on.

Looking forward to seeing where the diff diverges. That's exactly the kind of cross-implementation signal that tells you whether the spec is tight enough or still ambiguous somewhere.

@eason4kim-rocket Heads up before you run against v0.4.0. I shipped v0.6.0 today and it's a better baseline for your conformance test.

What changed: I ran differential tests across all 10 official MCP SDKs and found 26 wire-level serialization divergences that directly affect hash-chain implementations. Six SDKs produce six different wire representations of 1e20. Go and Swift both sort keys but their algorithms are incompatible (lexicographic vs numeric-aware). C# HTML-escapes angle brackets and ampersands that nobody else touches. And the Python SDK produces different bytes across pydantic-core versions for the same code path, which was a fun one to track down.

I tightened the canonicalization in v0.6.0 because of all this. Integers only, so the float formatting problem goes away entirely. Explicit field order instead of relying on sort, since three SDKs sort three different ways. Surrogate rejection at the boundary. None of the 26 divergences can affect the tuple-array form.

If your pipeline uses any of these SDKs, the divergence table will tell you exactly which tests produce different hashes. The harness is reusable too if you want to point it at your own canonicalization: test/vectors/cross-sdk-diff.sh --layer sdk.

@SatoshiImai this probably affects your design. Your reference implementations use RFC 8785 JCS, which handles key ordering but not float formatting. Two consumers running different SDKs will get the same key order from JCS but potentially different float representations. Chain hashes diverge silently. Might be worth a note in the proposal about numeric constraints, or at minimum flagging that JCS alone isn't sufficient for cross-SDK digest stability.

@eason4kim-rocket following up on "happy to help test the conformance" — it's mergeable now, and it lands exactly on the 3-state model you called out.

The battery is in the SEP working draft under sep/conformance, with the fixture at examples/hostile-server; the standalone version is hostile-facilitator (MIT, stdlib-only, no keys). It drives a client through each ambiguous outcome and counts how many times the effect actually executed for one logical request.

Two of the seven modes are the ones you'd care about most, since they test the distinction you named:

• verify-unavailable — the effect may have landed and the reconciliation read itself fails. This is the mode that actually asserts your "pending_reconciliation" is terminal: a client that resolves "could not determine" to "released/absent" and retries gets caught double-executing. It's the recursive case of the under-reporting risk you described.
• declared-safe — the other direction, so a maximally cautious gate that never replays doesn't score a false pass.

If you run it against your pipeline, the comparative diff you mentioned would be genuinely useful to the SEP — a second real implementation's results are exactly the kind of evidence the motivation section wants before it goes for a sponsor. And if your compliance pipeline needs modes the payment-shaped battery doesn't cover yet (VAT/registry reads have their own ambiguous-outcome shapes), that's worth a mode, and I'd add it.