What it is
An MCP payment server is an MCP server whose HTTP endpoint is gated so callers pay to use it, settled in USDC on Base per call. The MCP server is ordinary, the same tools and resources you would expose anyway; what makes it a payment server is the @blockchain0x/x402 adapter sitting in front of its route, returning a 402 on unpaid calls and settling payment on paid ones.
This page is about the architecture: what a payment-enabled MCP server looks like as a running service, and the structural decisions that follow. For the monetization strategy see mcp-server-monetization; for the step-by-step build see how-to-build-a-paid-mcp-server. The payment API product page is the reference. Here the focus is the shape of the server itself.
Why Streamable HTTP, not stdio
The first architectural decision is forced: a payment server must use the Streamable HTTP transport, not stdio. The x402 adapter gates an HTTP route, and a stdio transport has no HTTP route to gate, so there is nothing for the adapter to sit in front of. This is not a configuration choice; it is structural, and it is the single most common surprise when teams try to charge for an existing MCP server.
If your server runs over stdio today, as many local MCP servers do, switching it to Streamable HTTP is the prerequisite for charging. The good news is that the MCP SDK supports Streamable HTTP as a first-class transport, so the change is to how the server is served, not to its tools. Once the server speaks HTTP, the adapter can gate it; until then, it cannot. Decide this first, because the rest of the architecture assumes an HTTP endpoint.
The gate sits in front
The defining structural fact is that the gate sits in front of the MCP server, not inside it. You register createX402Plugin (Fastify) or createX402Middleware (Express) on the route that serves the MCP endpoint, with per-route pricing, and the adapter runs before the MCP server sees the request.
import Fastify from "fastify";
import { createClient } from "@blockchain0x/node";
import { createX402Plugin } from "@blockchain0x/x402/server/fastify";
const sdk = createClient({ apiKey: process.env.B0X_API_KEY! });
const app = Fastify();
await app.register(createX402Plugin, {
sdk,
defaultNetwork: "testnet",
pricing: {
"POST /mcp": { amountUsdc: "0.02", payToAddress: process.env.B0X_PAYTO_ADDRESS!, paymentRequestId: "pr_mcp" },
},
});
// The MCP Streamable HTTP handler is mounted on POST /mcp and only runs after payment.An unpaid POST /mcp gets a 402 quoting the price; the adapter verifies the X-Payment header through settle on the retry, and only then does the MCP server handle the call. The MCP server code is unchanged, which is the point: payment is a layer in front, so you reason about it separately from your tools.
Free and paid on one server
One server can serve both free and paid routes, and a good payment server does. Discovery, the part where a caller learns what the server offers, should stay free, so leave the route that lists the server's capabilities out of the pricing map. The routes that do the valuable work go in the map with a price.
In practice this means two kinds of endpoint on the same server: an unpriced one a caller (often an agent) hits to see what is available, and priced ones that run the actual tools. A machine caller reads the free discovery, decides the server is worth paying for, and then calls a paid route. Gating discovery would defeat the model, since a caller cannot decide to pay for something it cannot see, so keep the door open and price the work behind it. The split is a routing decision, expressed entirely in which paths appear in the pricing map.
Stateless by design
A payment server stays stateless, because the adapter verifies each call by calling settle with no receipt cache and no session. Every paid request carries its own X-Payment header, the adapter settles it independently, and nothing about the payment needs to persist between requests.
That keeps the server horizontally scalable: put several instances behind a load balancer and any instance can handle any paid request, since none of them holds payment state. It also keeps reasoning simple, because there is no cache to invalidate or expire and no session to lose; a request either arrives with a valid payment or it does not. Build the MCP server's own logic to be stateless too where you can, and the whole service scales by adding instances. The on-chain settlement is the source of truth, and the server is just a stateless gate in front of stateless tools.
The lifecycle of one paid call
It helps to trace a single call through the architecture. A caller makes its first request to a priced route with no payment, and the adapter responds 402 with the price, the pay-to address, and the network, all from your pricing entry. The caller's x402 client reads that, settles the amount, and retries the identical request with an X-Payment header. The adapter parses the header, calls settle to verify it on chain, and on success passes the request through to the MCP server, which runs the tool and returns its result.
Nothing in that flow touches the MCP server until payment is verified, and nothing about the payment lingers after the response. That clean before-and-after boundary is what lets you reason about the gate and the tools independently: the gate is a verified checkpoint, and everything behind it can assume it was paid for. When a settle is rejected, the adapter returns the failure and the MCP server never runs, so an unpaid caller costs you nothing.
Compatibility
The architecture works wherever an MCP server can speak HTTP and sit behind a Node gate.
| MCP server aspect | Works? | Notes |
|---|---|---|
| Streamable HTTP transport | Yes | Required; the gate fronts the HTTP route |
| stdio transport | No | No HTTP route to gate; switch to Streamable HTTP |
| Fastify host | Yes | Use createX402Plugin |
| Express host | Yes | Use createX402Middleware |
| Horizontal scaling | Yes | Stateless settle per call, no shared store |
When this fits
A payment server fits when you have an MCP server worth charging for and want machine callers to pay per use with no signup. It fits naturally for a server exposing valuable tools (paid data, compute, a specialized capability) to agents that can pay, since the gate turns usage directly into revenue without a billing relationship.
It fits less well when the server is local and personal (stdio, single user, nothing to charge) or when every caller is internal and trusted. For a server meant to be reached and paid by callers you do not know, the gated Streamable HTTP architecture is what makes that possible, and it is the same shape whether the server has one tool or many.
Pricing
Running a payment server is free to set up; you pay the wallet platform fee per agent on the pricing page: Free is $0 per agent per month at a 5% transaction fee, Pro is $9 at 2%, Business is $29 at 1%. The fee applies to the server's own agent profile, the one that receives the USDC, and scales with what the server earns rather than a flat seat.
What to ship today
Make sure your MCP server speaks Streamable HTTP, mount it on a route, and register createX402Plugin (or createX402Middleware) in front with one priced route and a free discovery route. Confirm an unpaid call gets a 402 and a paid one runs the server on Base Sepolia. For the build steps see how-to-build-a-paid-mcp-server; for monetization strategy see mcp-server-monetization. Pricing is on the pricing page.