feat(x402): add the MCP transport to the buyer skill

[estmcmxci]

Closes #23 (proposed and scoped there). Extends #16 by @basgys, which landed the x402 HTTP payer — this adds the second of x402 v2's three transports, MCP, per the spec (specs/transports-v2/mcp.md), so an agent can pay x402-gated MCP tools with the same mm-backed signer.

What's in it

Two new subcommands in scripts/x402_pay.py — pure stdlib, zero new dependencies:

• mcp-inspect — parses the paid tool's PaymentRequired challenge and prints the payment options, read-only. Accepts the whole JSON-RPC response, the tool result, or the bare PaymentRequired object (via --challenge — pass - to read stdin — or --challenge-file); checks structuredContent, content[0].text, and _meta["x402/error"] (see below).
• mcp-sign --confirm — validates and signs one offered option with mm wallet sign-typed-data and prints the PaymentPayload for the retried tool call's _meta["x402/payment"] — both as the spec's raw JSON object (payment) and as a base64 string (paymentBase64), since real servers disagree on which one they want (see below).

Design notes:

• The MCP session (and any OAuth on it) stays the caller's — the script signs, the caller delivers. That keeps it transport-honest and dependency-free.
• The transport-agnostic core from feat: add x402 buyer payment support #16 (select / validate / build_typed_data / sign_typed_data / build_payment) is reused untouched; --confirm, --asset/--network disambiguation, and all validation guards carry over. The HTTP path is behavior-unchanged (the accepts[] normalization was extracted to a shared _normalize_accepts(), keeping the v1 maxAmountRequired fallback in one place).
• v2 only: the MCP transport is not defined for x402 v1; v1 challenges are refused with a clear error.
• Fail-closed: mcp-sign refuses a challenge without a resource URL before signing (a v2 payload must forward the resource, so signing first would burn a real authorization on a payload the facilitator rejects). Malformed offers (extra: null, string resource) produce the JSON error contract, not tracebacks. stdin is read only via an explicit --challenge -, so a forgotten flag errors immediately instead of blocking under an agent harness.

Also: conformance tests (scripts/test_x402_pay.py, stdlib unittest, no network and no mm calls) — the core assertion is that the built payload equals the spec's _meta["x402/payment"] object exactly, plus fixtures captured verbatim from a live Cloudflare withX402 run. Docs: MCP sections in references/x402.md and workflows/x402-pay.md, plus SKILL.md routing/validation/confirmation rows.

Where this actually gets used

The x402 MCP transport, as documented, is early — real sellers we found gate payment with a plain HTTP 402/header regardless of protocol underneath, and CDP's own public discovery index can't even describe an in-band MCP resource (its schema's input.type is hardcoded to "http"). The one substantial real implementation of the spec's actual in-band mechanism is Cloudflare's Agents SDK (agents/x402, withX402/paidTool) — official, documented, and already used in production-shaped builds (Crossmint's crossmint-agentic-finance reference demo wires both sides of it).

Reading Cloudflare's real server code turned up two concrete divergences from the spec text, both now handled:

• The challenge lives in _meta["x402/error"], not structuredContent (there's no structuredContent key at all in Cloudflare's response).
• The retry's _meta["x402/payment"] is read via JSON.parse(atob(token)) — a base64-encoded string, not the inline object the spec shows.

Verified

• python3 scripts/test_x402_pay.py → 33/33, including fixtures captured from a live Cloudflare run.
• Full mainnet round-trip, real money: ran Cloudflare's own official x402-mcp example server locally, unmodified, configured for Base mainnet + the CDP facilitator. mcp-inspect/mcp-sign correctly parsed the real challenge and produced a payload the server accepted; mm's TEE wallet signed a real EIP-3009 authorization; the retry settled for real — tx 0x7f7fe537…bcd6064, $0.01 Base USDC, independently confirmed via eth_getTransactionReceipt (status 0x1, ERC-20 Transfer + EIP-3009 AuthorizationUsed logs both present).
• The signer core is separately proven on the HTTP transport too: mainnet vs an independent seller (tx) and Base Sepolia (tx).

Field notes from building x402 payers with mm (why some choices look the way they do)

• v1 wire uses maxAmountRequired where v2 uses amount; miss the fallback and you sign a null value. _normalize_accepts() handles both in one place for both transports.
• Never blind-take accepts[0]: real sellers offer multiple rails (e.g. Exa lists a Solana rail alongside Base USDC). The existing --asset/--network selection carries over to MCP unchanged.
• Real MCP-branded x402 sellers we probed (found via CDP's Bazaar index) all gate at the HTTP layer regardless of protocol underneath — worth knowing if you're deciding where to spend interop effort next.

A possible follow-up (kept out of scope here, as discussed in #23): the next_action/handoff convention some sellers use (Coinbase payments-mcp style), which wraps a standard exact-EVM offer — could ship with a redacted capture as a test fixture.

cc @basgys — this extends your #16; happy to adjust naming/scope.

[AyushBherwani1998]

Can you separate out workflow in x402-mcp. It reduces the chances of hallucination.

[AyushBherwani1998]

Pay an x402-gated MCP tool call

[AyushBherwani1998]

We can remove the gitignore and test case for script. As of now we are not adding the test for scripts.

[AyushBherwani1998]

This should be under ## Notes

Also, use the third person voice instead of first person in the SKILLs.

[AyushBherwani1998]

Instead of inspect (or mcp-inspect) we can add when to use either one. Or something that is descriptive so that agent doesn't always default inspect and sues mcp-inspect as fallback.

[AyushBherwani1998]

The caller owns the MCP session; the script only signs.