Repository navigation
[Docs]: Say that MCP tool calls emit no receipt and return no provenance by default #451
Description
Documentation Type
API Reference
Issue Type
Missing documentation
Documentation URL
No response
Description
The MCP server exposes statewave_get_context and statewave_search_memories. Neither emits a state-assembly receipt (the tool never sends emit_receipt, and the server default is on_request), and neither returns source_episode_ids. Nothing in the MCP documentation says so, while receipts and provenance are described elsewhere as core behaviour.
A reader can reasonably assume the audit trail follows them into an MCP client. It does not.
Suggested Improvement
Add to the MCP server documentation, until the connector change lands:
Calls made through the MCP tools do not emit a state-assembly receipt unless the tenant is configured with
receipts: always, and the tools do not returnsource_episode_ids. To record and inspect the assembly trail today, callPOST /v1/contextdirectly withemit_receipt: true.
Remove the paragraph once the connector returns receipt_id, receipt_emitted and provenance.
Contribution
- I would be willing to submit a PR to fix this documentation issue
Activity
happy520ai commentedon Sep 27, 2026
Disclosure: I maintain unified-ai-system, a gateway that fronts other MCP servers, and this reply was drafted by an agent in my repo and reviewed by me. The suggested paragraph is right, and one addition would make it hold up better.
Say what the client can observe, not only what it does not get. Your phrasing tells a reader that no receipt is emitted, which they can verify by looking. The more expensive assumption is the one they will quietly make: that something downstream records the call. Worth naming explicitly - through an MCP client there is no trail at all unless the tenant is on
receipts: always, so an operator who has built a compliance or debugging habit onPOST /v1/contextbehaviour does not have a partial record on the MCP path, they have none.And when the connector change does land, put the receipt handle in the tool result body. A
receipt_idthat travels only in transport metadata is invisible to the MCP clients that matter most in practice: several discard or truncate non-content fields, and none of them show metadata to a human. Ifstatewave_get_contextreturnsreceipt_id,receipt_emittedandsource_episode_idsinside the JSON payload the model sees, then the audit story survives whichever client is in front of it, and "did this answer come from assembled state?" becomes something a user can paste you.One convention from our side that was worth the friction: on the governed path we require exactly one
External-Effect-KeyorIdempotency-Keyheader on mutating upstream calls and write that key into the audit entry. It is the cheapest way to keep "was this call allowed, and did it run once or twice?" answerable after the fact - which is the same class of question youremit_receiptflag is trying to answer, just asked later by someone who was not present.Good documentation bug. The fact that you filed it as a docs issue rather than letting the connector change cover it silently is the right call.