Adding Pay-Per-Call to an MCP Server

What MCP does not give you

MCP defines tools, resources, and prompts as JSON-RPC-shaped exchanges between a client (the agent's host application) and a server. As of this writing, there is no concept of a "paid tool" in the spec, no equivalent of an HTTP status code inside a tool result, and no standard field for "this costs money, here's how to pay." If you want per-call payment on an MCP tool, you are building that yourself on top of MCP, not using a feature MCP already has.

This matters because MCP tool calls don't carry raw HTTP responses. HTTP-native payment protocols like x402 are built around a real 402 status code and response headers — none of which exist inside an MCP tool result, which is just a JSON-RPC response payload. You can't return "HTTP 402" from an MCP tool; you have to represent the equivalent information yourself, in your own JSON shape, and get both sides (your server, and whatever client library the agent uses) to agree on what that shape means.

The pattern: bridge a paid tool to a real HTTP route

The approach we use, and the one other independent x402-over-MCP implementations (like community MCP servers built specifically to sit in front of x402 payments) converge on, is: keep the actual paid work behind a normal HTTP endpoint that speaks real x402, and have the MCP tool of the same name act as a thin bridge in front of it.

Concretely, in our own stack: a real x402-gated route (POST /v1/sanctions_screen, protected by the official @x402/express payment middleware) does the actual paid work over HTTP. The MCP tool sanctions_screen doesn't reimplement payment logic — it calls that same HTTP route internally, and when the route returns a real 402 challenge, the tool translates that challenge into a JSON field the calling agent can read.

The call sequence, concretely

1. Call the tool with business arguments only. E.g. sanctions_screen({ name: "..." }) — no payment field yet.
2. The result carries a payment-required flag and the challenge. Something shaped like { payment_required: true, accepts: [{ network: "eip155:8453", asset: "...", amount: "...", payTo: "0x..." }] } — the same information a real x402 402 response would carry, just relocated into the tool result body since there's no HTTP layer to put it in.
3. The calling agent's x402 client signs against that challenge, exactly as it would for an HTTP 402 — this step happens entirely outside MCP, using a normal x402 client library and the agent's own wallet.
4. Call the same tool again with the same business arguments, plus the signed payment attached — e.g. a payment_header field carrying the signed authorization. The server attaches that value to the internal HTTP request it was already bridging to, which then runs through the real x402 verify/settle flow on the HTTP side, and the tool returns the paid result.

Notice that the actual cryptographic signing and settlement still happen through a normal x402 flow against a real HTTP endpoint — MCP is only relaying the challenge and the signed response between two calls. This is deliberate: it means the hard, security-sensitive part of the system (verify-then-settle-only-on-success, discussed in our seller-side lessons post) is the exact same code path whether a buyer arrives over plain HTTP or over MCP.

Give every paid tool a free preview twin

Because an agent has to discover that a tool is paid before it can decide whether to fund a wallet and sign anything, we ship a free <tool_name>_preview twin next to every paid tool — no wallet, no payment, a representative sample response, and a rate limit instead of a price. This does two things: it lets an agent (or a human evaluating the integration) see the real response shape before spending anything, and it means "call this tool" never hard-fails for an agent that hasn't set up payment yet — it just gets the preview version.

We also expose one free, unconditional list_catalog tool that enumerates every paid tool and its price, so an agent doesn't need to trial-and-error its way through the whole tool list to find out what costs what.

What this looks like from the calling agent's side

An MCP client that wants to actually pay needs its own x402-capable signing library on hand (the same ones used for plain-HTTP x402, e.g. @x402/core + @x402/evm on TypeScript, or the x402 package on Python) — MCP doesn't supply this for you, because it isn't an x402 concept in the first place. See our companion piece, How AI Agents Discover and Pay for APIs With x402, for the underlying signing flow; over MCP, the only thing that changes is where the challenge and the signed value travel (inside a tool result/argument, instead of an HTTP header).

Community bridges like MetaMask's mcp-x402 automate more of this client-side dance for wallets that integrate with it; absent that, an agent framework needs to implement the "read payment_required, sign, call again with payment_header" loop itself.

Trade-offs and open edges

• It's convention, not spec. Different MCP servers implementing "paid tools" may shape their payment-required result differently. There's no ratified field name or schema an agent can rely on across servers the way it can rely on the x402 HTTP challenge shape across HTTP sellers.
• Two calls, not one. The probe-then-pay round trip doubles the tool calls needed for a first-time paid call to a given tool (subsequent calls to a route your agent already knows the price for can sometimes skip the probe if your framework caches it, but that's your framework's responsibility, not MCP's).
• The security-critical logic still lives in the HTTP layer. If your MCP bridge just forwards to a real x402 HTTP endpoint (as ours does) rather than reimplementing verify/settle inside the MCP process, you inherit the HTTP layer's correctness — which is exactly why we keep it that way rather than duplicating payment logic in two places.
• Streamable-HTTP transport, not stdio, if you want a shared hosted server. A stdio MCP server runs as a local subprocess per client and has no natural place to hold a shared wallet-facing HTTP endpoint; a streamable-HTTP MCP server (a real hosted URL) is the transport that pairs naturally with this bridge pattern, since it's already an HTTP-reachable process sitting next to your paid routes.

Try our own hosted server

FAQ

Does MCP support payment natively?

No. As of this writing, MCP has no built-in concept of a paid tool call — payment has to be bridged in by the server author, typically by pairing an MCP tool with a real HTTP endpoint that speaks an actual payment protocol like x402.

Can an MCP tool call carry a raw HTTP 402 response?

Not directly — an MCP tool result is a JSON-RPC response, not an HTTP response, so there's no native status code or header slot for it. The equivalent information (payment required, price, network, payTo) has to be encoded into the server's own JSON tool result instead.

Is there a standard way to do this today?

Not an official one. Several independent implementations converge on a similar shape — probe with business arguments, get a payment-required flag and challenge back, sign externally, call again with the signed payment attached — but this is convention among implementers, not a ratified part of the MCP spec.

Who's behind this

We're draconic21 — we sell live, pay-per-call data APIs (SEC EDGAR, OFAC sanctions, U.S. Treasury data, and more) over x402 and MCP, plus developer kits for building your own x402/MCP sellers.