Skip to content

Proposal: AMEP evidence extension (signed effect receipts for tool calls) - #31

Open
stafordtituss wants to merge 3 commits into
modelcontextprotocol:mainfrom
stafordtituss:amep-evidence-proposal
Open

stafordtituss wants to merge 3 commits into
modelcontextprotocol:mainfrom
stafordtituss:amep-evidence-proposal

Conversation

@stafordtituss

@stafordtituss stafordtituss commented Nov 20, 2026 •

Copy link
Copy Markdown

This adds a draft Extensions Track proposal for io.github.stafordtituss/amep-evidence, an optional extension that lets tool servers return signed receipts of the effects they actually executed, in the tools/call result's _meta. An auditor can then verify afterwards, without trusting the agent or its host, whether each effect stayed within the authority the user delegated.

  • Uses only capability negotiation and _meta: no new methods, no change to result content. Off unless both sides opt in.
  • Works on both protocol eras: initialize, and 2026-07-28 with server/discover and per-request capabilities.
  • Covers discovery and filtering of servers that sign receipts, and partial adoption, following feedback from the Agents WG call on Nov 20.
  • Sponsor: @LucaButBoring, as discussed in #agents-wg.

The TypeScript implementation follows in a separate PR to packages/, ported to the { id, setup(ctx) } extension API from modelcontextprotocol/typescript-sdk#2820 once that's released.

Feedback is very welcome, especially on the open questions at the end of the proposal.

Update (revision 0.3). Following the review comments here:

  • financial effects carry their amount as an exact decimal string, and AMEP now defines per-call and per-period limits;
  • servers return a signed call statement for every call (completed, not_executed or failed_after_effects, with an effect count);
  • receipts are bound to the exact signed invocation, and argument digests on both sides expose changes in transit;
  • evidence is stored before the result is returned and can be recovered with resources/read.

The TypeScript reference implementation and AMEP v0.3 verifiers are on the AMEP repository's main branch.

@vendrell46 vendrell46 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewing from the payments side, since the Motivation and the 20 Nov call both name financial services as an early audience. Checked against 46e3c72 and AMEP at 2e89e84.

1. A financial receipt can't say how much was paid. The receipt's executed block has no amount, and the proposal doesn't say where one goes. AMEP's payment vectors (interop/approval-path-attacks) carry it in x-args, with the payee as the resource, and that README asks (question 3) whether a monetary threshold should be a profile. I think a payments server needs that answered before it can use the extension, for two reasons:

  • Without an approval, nothing in the evidence bounds the amount. I rebuilt the packet of small-payment-within-budget-needs-no-approval with the amount changed from 84.10 to 840000.00 EUR, and AMEP's Python verifier still says preserved. The other way round, two payments of 0.50 EUR under the same budget: 100 come out violated (I2), like the suite's 2 × 600.00 split, because each irreversible payment costs 60 points whatever it moves.
  • x-args can't carry a limit. Spec §16 says extensions MUST NOT change outcomes, and each server picks its own member names inside it. So two servers' receipts for the same payment can't be compared, which is the problem the Motivation sets out to fix.

What would close it: for financial effects, one defined member with the amount as a decimal string and its asset (an ISO 4217 code, or a CAIP-19 id for a token), keeping the payee in resource. A mandate could then carry a cap in that asset, per call and per period, and I2 could keep a running total the way §9.2 does for points. Whether that lives in this extension or in an AMEP profile it points to is your call, but the extension should say where a payments server puts the amount.

2. Amounts as strings. Requirement 4 keeps numbers inside the I-JSON safe range but leaves out AMEP §12.1's advice that amounts SHOULD be strings. It's worth carrying over: a server that writes a token amount in base units as a JSON number passes 2^53 at about 0.009 of an 18-decimal token, and the verifier then marks every invocation in the packet unresolved (I7; checked with 10 tokens).

If useful, I can add must-reject vectors in the suite's format once the shape is settled: payments that each fit a per-call cap but together cross a period cap, one payment over the cap with no approval, and an amount with no asset, which should come out unresolved rather than preserved.

AI use: Claude Code wrote this comment on my behalf from the proposal and the AMEP repo, and ran the checks above with AMEP's Python verifier.

@zambodotdev

Copy link
Copy Markdown

@stafordtituss thanks for putting this in the open. I run ops for Zambo, where every tool call through our MCP endpoint produces an AER-1 execution receipt in production (158K+ public receipts so far), so this is the design space I work in daily. Three points from that running system, aimed at the questions an evidence extension has to answer:

  1. The receipt needs the outcome states around it, not just the effect. AMEP receipts cover calls that executed. The auditor's hard cases are the other outcomes: the call was refused before execution, the response was lost after execution, the server never opted in. If all three surface as "no receipt," the auditor cannot distinguish "no effect happened" from "an effect happened and left no record," and the second case is the one that matters. AER-1's records carry five anchor outcomes for exactly this reason: verified, verification failed, rejected: unresolvable record, not checked, and absent, where "absent" is a fact about the record, never a verdict that nothing ran. The extension does not need to copy the dictionary, but the client's side of the negotiation should have somewhere to write which of those states a call ended in.

  2. Bind the receipt to the call, not just the server. A receipt in _meta should carry the tools/call identifier and a commitment over the request arguments as sent. Without that binding, a genuine receipt for one effect can be presented as evidence for a different call, and the auditor is back to trusting the presenter. With it, the check is mechanical: recompute the commitment from the call the client actually made.

  3. Mint at execution time, inside the executing layer. A receipt reconstructed afterwards from logs or traces inherits every failure mode of the pipeline that produced the log, including the lost-response case where the effect happened and the record of it is what got lost. The receipt has to be written on the execution path, when the effect happens, or the extension attests to the logging pipeline rather than the effect.

On verification: our receipts are checked by recomputing SHA-256 over the record's served canonical bytes and comparing against the record's output hash. Anyone can repeat that with a hash tool, no account and nothing from the vendor: https://zambo.dev/run/5497d6a7-49db-46ee-873f-54fdb28604ff is a live example (606 canonical bytes, recomputed digest matches the commitment exactly). Whatever signature scheme AMEP settles on, I would argue the verification story should be equally presentable: the auditor recomputes something from bytes they hold, rather than trusting that a signature was checked correctly upstream.

…pt recovery, payment amounts

Addresses the review comments on this PR: amounts on financial effects as
exact decimal strings with limits defined in AMEP, a signed call statement
per call, receipts bound to the exact signed invocation, argument digests
on both sides, write-ahead storage with recovery via resources/read, and
the minting rule.
@stafordtituss

Copy link
Copy Markdown
Author

@vendrell46 thank you, this was exactly the review this needed. I re-ran your cases against the Python verifier and they reproduced: 840000.00 EUR came out preserved under a 100-point budget, so did a payment with no amount at all, and 2 × 0.50 EUR came out violated (I2). You were right that nothing bounded the amount without an approval, and that x-args couldn't fix it.

Revision 0.3 is now in this PR, with AMEP v0.3 on the repository's main branch (spec Sections 5.9.2 and 7.6):

  • value: {amount, unit} on executed effects:
    • amount is a decimal string with a strict grammar (no sign, no exponent, no leading zeros, at most 18 decimals), compared as an exact decimal;
    • it is the total debited, fees included;
    • unit is iso4217:… or caip19:…, matched exactly, with no conversion.
  • limits on claims (per call, per period, per unit), attenuated under I1:
    • a payment over a limit without an approval is violated (I2);
    • an unauthorized asset is violated;
    • a missing amount is unresolved;
    • approved payments still count toward the period total.
  • The extension now requires value on financial effects and amounts as strings. The semantics stay in AMEP, so the extension remains a carrier.
  • Two holes a profile alone would have left:
    • a verifier that didn't implement limits would have ignored it. In AMEP 0.3 packets, an unknown claim member is now unresolved, never ignored;
    • a period total can't be trusted from one packet, because earlier payments can be left out. The observer can sign its own running total (period_spent), and without that or earlier state the result is unresolved.

The 0.50 EUR case is unchanged on purpose. The risk budget bounds autonomy across effects that have no common unit, so budget: 100 reads as "at most one irreversible payment without asking me". Money is now a second cap that must also hold.

The suite has 24 vectors on amounts and limits, including:

  • your three cases (per-call, period, amount with no asset);
  • an unauthorized asset;
  • non-canonical, negative and JSON-number amounts;
  • a delegation that widens a limit;
  • an observer total below the recorded payments;
  • a period total carried across packets;
  • a record-count limit on bulk reads.

I'd gladly take you up on the must-reject vectors, now that the shape is fixed. The set doesn't yet cover fees pushing a payment over a cap, or currency conversion on the debit side, and those would be especially welcome. The suite format is in vectors/. The quickest check of a new vector is to run both reference verifiers over it with packages/conformance (amep-conformance verify), which also works for any independent implementation. Does the value shape match what a payments server can actually produce?

@stafordtituss

Copy link
Copy Markdown
Author

Thanks @zambodotdev, these came straight from a running system, and they changed the design. Revision 0.3 is in this PR, with AMEP v0.3 on main:

Outcome states. Absent was already unresolved, never preserved. But you were right that "nothing ran" and "no receipt" looked the same. Servers now sign a call statement for every call, giving completed, not_executed or failed_after_effects, and an effect_count:

  • a no-op is provably preserved;
  • a promised receipt that is missing is unresolved (lost or withheld);
  • a receipt that contradicts not_executed is violated.

Lost responses are recoverable: servers store the evidence before replying, and the client fetches it with resources/read on amep-receipt://{invocation}.

Binding. Receipts and statements carry invocation_digest, the SHA-256 of the exact signed invocation, so a genuine receipt can't be presented for another call. The host signs args_digest over the arguments it sent, and the server's statement carries the digest of the arguments it received; a mismatch is violated. Invocation ids are random 128-bit values. I didn't use the JSON-RPC id, because it's session-scoped, reused, and rewritten by proxies.

Minting at execution time. This is now a requirement: receipts are produced on the execution path, before the result returns, and a receipt reconstructed from logs claims at most L1.

Verification you can repeat. I agree it has to be checkable with bytes you hold and standard tools. The recipe in spec/verify-by-hand.md checks a signed object with jq, xxd, shasum and OpenSSL alone, and agrees with the reference verifier on 971 of the 972 signed objects in the suite. The one remaining case is a vector built to catch non-RFC 8785 canonicalizers, and there it fails rather than accepting. Where we differ: a hash shows that bytes match a published digest, and whoever serves both can replace both, so AMEP pairs the digest with a role-bound signature.

AER-1 → AMEP. I built an import adapter (packages/conformance, profile aer1) and tried it on the receipt you linked:

  • all six AER-1 format checks pass (id, timestamp, provenance class, canonical base64, output_hash, metadata_hash);
  • with a published tool map, it becomes market.read market:price/ETH;
  • under a mandate for market:price/* the call is preserved, and under one for market:price/BTC it is violated (I2).

The adapter also reports what AMEP needs that AER-1 doesn't carry:

  • an issuer signature. The receipt itself says the issuer is not authenticated, so imported effects are capped at L1;
  • binding to the authorizing call. input_hash uses the layout zambo-json-sorted-keys-utf8-v1, which isn't the bare arguments object. If AER-1 offered an input layout of RFC 8785 over the arguments, input_hash would equal AMEP's args_digest, and an AER-1 receipt would bind to a signed invocation by digest alone;
  • quantities and data-flow labels.

Would you be up for reviewing the profile, or running it against more of your receipts? An RFC 8785 input layout seems like the smallest change that would let the two formats compose.

@zambodotdev

Copy link
Copy Markdown

@stafordtituss yes, up for both. I read the aer1 profile in packages/conformance before replying, and its gap list is accurate about our receipts, including the two hard ones:

  • The L1 cap is right. AER-1 receipts are unsigned, and our own verify checks say so plainly: issuer is not authenticated, no signature checked. What the hash proves is that the saved result was not changed, nothing about who served it. A profile that imported them at higher assurance would be overstating it.
  • The binding gap is exactly where you put it. input_hash carries layout zambo-json-sorted-keys-utf8-v1, so it does not equal an RFC 8785 args_digest over the bare arguments. Since the layout is already a named field on the receipt, adding an RFC 8785 layout as a second value is a small, non-breaking way to make input_hash equal args_digest, and I agree it is the right composition step to test first.

The call statement design also goes past what I asked for in a good way: args_digest on both sides turning an in-transit change into violated, and recovery through resources/read, close the lost-response case instead of just naming it.

Where do you want the profile review: comments on this PR, or issues on the AMEP repo? Either way I will run the profile against a wider set of our receipts, across tools and provenance classes, and post what it reports, including any receipt where its checks and ours disagree.

@stafordtituss

Copy link
Copy Markdown
Author

@zambodotdev thank you, that's a generous read, and good to have the L1 cap and the gap list confirmed from your side.

Issues on the AMEP repository would be best, so this PR stays on the MCP extension:

  • Running the profile against your receipts: the implementation report form fits. amep-conformance import RECORD --map TOOLMAP --json out.json writes the full per-receipt report (format checks, mapping, binding, gaps), so attaching those, or a summary across tools and provenance classes, works well. Any receipt where the profile's checks and yours disagree is the most useful part, since that is either a bug in the profile or a reading of the draft worth pinning.
  • Review of the profile itself: the independent review form, or a plain issue if that's easier.

On the input layout: when an RFC 8785 layout is available on your side, I'll add a test to the profile that binds a receipt to a signed invocation by digest alone, and report the result back here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants