Require the signed envelope and document where to get one

[GChief117]

The defect

The MCP canary reached tool discovery and then failed on the only tool call, HTTP 400.

The free route POST /v1/demo/verify accepts bare claims and works, so the landing page, the playground and the published Postman example all teach that shape. The paid POST /v1/verify requires the signed envelope returned by POST /v1/mandates.

The tool schema was z.record(z.string(), z.unknown()) — it accepted the bare shape and forwarded a request that could not succeed. The developer saw "mandate.mandate" must be the claims object, an internal field path with no route to a signed mandate.

This is on the only surface with verified external discovery: the Glama listing advertises this package, so it is the most likely first contact a real developer has with the product.

The fix

• Schema requires {mandate, signature}, so the tool refuses locally with a message naming the real cause instead of forwarding a doomed request.
• Tool description names POST /v1/mandates as the source of the envelope and notes bare claims belong to the keyless demo route.
• README gains the missing first step as a copyable walkthrough, names the HTTP 400 and explains it, and states that a deny or requires_approval is a correct result, not a failure.

Why not have the tool mint the envelope itself

It would consume two metered units per verification without the caller knowing, and turn a verification-only tool into one that creates durable authority. The server's own instructions say it never issues or revokes mandates. That property is worth more than the convenience.

Tests

Three existing fixtures passed only because the old schema accepted anything; they now carry a structurally real envelope. A new regression suite asserts the bare shape is refused, an envelope without a signature is refused, an empty signature is refused, the real /v1/mandates response passes unchanged, and passthrough preserves extra fields.

28/28 pass.

Verified against production

POST /v1/mandates  -> 201  keys: mandate, requestId, signature
verify_action via the built MCP server with that envelope
                   -> 200  decision: requires_approval
                      violation: Actions above 25000 minor units need a human approval token.

That is the correct decision for the fixture: 30000 requested against an approvalRequiredAboveMinor of 25000.

Version bumped to 0.1.1 in package.json, server.json and the README install commands.

🤖 Generated with Claude Code