intermediate 20 minutes
Return 402 on a paid tool
Once pricing is discoverable, the server has to enforce it. This guide uses the axum reference server to gate a tool behind 402 and verify payment with a facilitator.
- 1
Run the reference server
Clone the repo and start mcp-pay-server pointed at your pay.json. It reads pricing from the manifest.
cargo run -p mcp-pay-server
- 2
Gate the tool
For a priced tool, the server responds 402 with an X-PAYMENT-REQUIRED header carrying everything the agent needs to pay.
- 3
Verify the retry
When the agent retries with X-PAYMENT, the server sends the proof to a facilitator and waits for a valid response before running the tool.
- 4
Return the result
On a valid proof, the server runs the tool and returns 200 with settlement metadata the agent can log.
Why verification is out-of-band
- ▸mcp-pay is not a payment processor — the facilitator settles on the rail.
- ▸The server only asks "is this proof valid?" and runs the tool on a yes, keeping the codebase small and rail-agnostic.
More guides in the index, or read the architecture to see the full 402 handshake.