What you will build
An MCP server that charges per call, built from zero. It exposes tools over the Streamable HTTP transport, and the premium tools sit behind a paywall that settles in USDC on Base. A caller that has not paid gets a 402; one that has runs the tool and gets the result. By the end you have the whole thing: a server, its tools, a priced route, and a free discovery route.
This is the from-scratch build. To retrofit an existing server, see how-to-add-payments-to-mcp-server; for what to charge, see how-to-monetize-mcp-server. The MCP integration page is the canonical reference, and the payment API product page is the broader one.
The shape of a paid MCP server
The structure is three layers, and only one is new.
The MCP server and its tools are the first layer, built the normal way with the Model Context Protocol SDK. The HTTP transport is the second: you expose the server over Streamable HTTP so it is reachable as an HTTP route, which is how agent clients call a remote MCP server anyway. The paywall is the third and only new layer: the x402 server adapter in front of the priced route. That is it. You are not building payments into your tools; you are putting one adapter in front of the route your tools already answer on. Everything about how the tools work, their schemas, their handlers, their results, is unchanged from a free MCP server.
Prerequisites
- A Blockchain0x account with an agent created, so the server has a wallet and a
payToAddress. - A
sk_test_key and apaymentRequestIdfor the priced route. - Node 18+ and a Fastify or Express server to host the transport. The SDK targets
>=18.
export B0X_API_KEY=sk_test_...
export B0X_PAYTO_ADDRESS=0x...Expose tools over HTTP
Build your MCP server and its tools as usual, and serve it over the Streamable HTTP transport on an HTTP route. The tool logic is yours; the only requirement for charging is that it answers on an HTTP path.
import Fastify from "fastify";
const app = Fastify();
// Your MCP server's Streamable HTTP handler answers here. Build the server and
// register tools with the MCP SDK as normal; this route is where it listens.
app.post("/mcp/premium", async (req) => handleMcpRequest(req.body));
app.post("/mcp/free", async (req) => handleMcpRequest(req.body)); // discovery, cheap toolsTwo routes here on purpose: one for the premium tools you will charge for, one for the free discovery and cheap tools. Splitting them by route is what lets you price one and not the other.
Gate the premium route
Mount the x402 adapter and price the premium route. The adapter returns the 402 and verifies payment before your handler runs.
import { createClient } from "@blockchain0x/node";
import { createX402Plugin } from "@blockchain0x/x402/server/fastify";
const sdk = createClient({ apiKey: process.env.B0X_API_KEY! });
await app.register(createX402Plugin, {
sdk,
defaultNetwork: "testnet",
pricing: {
"POST /mcp/premium": { amountUsdc: "0.02", payToAddress: process.env.B0X_PAYTO_ADDRESS!, paymentRequestId: "pr_premium" },
},
});
await app.listen({ port: 8080 });Express works the same with createX402Middleware. Now /mcp/premium returns a 402 quoting two cents to an unpaid caller, verifies the X-Payment header through paymentRequests.settle on the retry, and runs your MCP handler only once the payment confirms. /mcp/free is absent from the pricing table, so it stays open.
Keep discovery free
This is the part new builders skip and regret. Agent clients list a server's tools and inspect their schemas before deciding to call anything. If that discovery is behind the paywall, a client cannot even learn what your server offers without paying, and most will not. So keep the discovery and listing tools on the free route, and gate only the tools that do premium work.
The freemium shape that converts: a caller hits /mcp/free, sees your tools and what they do, and pays at /mcp/premium only for the ones worth paying for. Discovery free, value paid. Putting a price on the front door is the most common way a paid MCP server gets no callers at all.
Which tools to gate first
When you build a paid MCP server, resist gating everything. Start by gating the one tool with the clearest value or the realest cost, and leave the rest free until you know they are worth charging for.
The best first paid tool is one where each call costs you money (a premium upstream API, expensive compute) or returns something a caller could not easily get elsewhere. That is where a price is obviously fair and a caller readily pays. A tool that wraps a cheap public lookup is a poor first choice, because gating it adds friction for no real value and trains callers to expect a paywall where none is warranted. Gate one strong tool, watch whether callers pay for it, and add a second priced route only once the first earns. A paid MCP server that launches with one well-chosen paid tool and a generous free tier converts far better than one that gates its whole surface on day one.
Deploy and scale
A paid MCP server is just an HTTP service, so deploy it like one, and scaling is simpler than you might expect because the adapter holds no state. It verifies each call independently through paymentRequests.settle, with no shared session or cache between requests, so any replica can serve any request. You scale it behind a load balancer with no sticky sessions and nothing shared to provision, exactly like a stateless API. The only stateful thing in the picture is the wallet, which Blockchain0x manages, so your server stays a plain horizontally-scalable process. Run it wherever you run your other services, point your DNS at it, and the paid MCP surface scales with ordinary infrastructure rather than anything payment-specific.
Test end to end
Run the whole thing on Base Sepolia before going live. Start the server, then exercise both routes. Call /mcp/premium with no payment and confirm the 402 quotes the right price; pay it from a test wallet (the pay side is createX402Client) and confirm your tool runs and returns. Call /mcp/free and confirm it answers with no 402. Watch a payment.received event land for the paid call. When the paid, free, and unpaid paths all behave, swap to a sk_live_ key for Base mainnet and re-check the price and wallet address on the live server.
Common pitfalls
Three traps building a paid MCP server.
Stdio-only transport. There is no HTTP layer to gate on pure stdio. Expose the Streamable HTTP transport so the adapter has a route to charge on.
Gating discovery. Keep listing and schema tools on the free route. Charging to discover loses callers before they ever pay.
One price for everything on one path. The adapter keys on route, so premium tools that should cost differently belong on different paths, not crammed onto one with a single price.
What you will ship
Build the server over Streamable HTTP, expose tools on a premium and a free route, gate the premium one with the adapter, and confirm an unpaid call gets a 402 while a paid one runs and fires payment.received. That is a paid MCP server end to end. For the retrofit path see how-to-add-payments-to-mcp-server, and for pricing strategy see how-to-monetize-mcp-server. Pricing for the platform is on the pricing page.