This guide walks through how to build an MCP server with x402 monetization — a Model Context Protocol server (per Anthropic's open spec) whose tool calls are gated by stablecoin micropayments. The audience is a developer who has an API, dataset, or compute resource they want autonomous AI agents to access, paying per call in USDC, with no API keys or human in the loop. The article maps the architecture, walks through a four-step build sequence — define MCP primitives, wrap a tool with payment gating, verify and log receipts, deploy to agent frameworks — and closes with the cross-chain settlement question x402 itself does not answer. The pattern is live: Coinbase's x402 MCP example and Cloudflare's Agents SDK both ship reference implementations, and x402 has cleared 165 million transactions across 69,000 active agents per Coinbase's April 2026 disclosures.
​

An MCP server is a program that exposes tools, resources, and prompts to AI applications over a standard JSON-RPC 2.0 wire protocol. Adding x402 turns each tool call into a paid API request settled in stablecoins, with no account, API key, or session token between agent and service.
​

Anthropic open-sourced MCP on November 25, 2024 and donated it to the Linux Foundation's Agentic AI Foundation on December 9, 2025 with Anthropic, Block, and OpenAI as co-founders. By the donation date the spec counted 10,000+ active public MCP servers, 75+ connectors inside Claude, and 97 million monthly SDK downloads across Python and TypeScript per the official donation announcement. Most servers expose tools for free or behind an OAuth-protected enterprise license. That model breaks the moment an agent wants to consume a paid service from a publisher it has never seen.
​

x402 fills the gap. It is a payment protocol that revives the long-dormant HTTP 402 status code: a server returns 402 with a payment-required envelope, the client signs a stablecoin transfer authorization (typically USDC on Base), and the server's facilitator settles the transfer onchain before releasing the response. Coinbase shipped the spec in May 2025, the x402 Foundation announced September 23, 2025 (same day Cloudflare added native support), and as of April 2026 the protocol has settled approximately $50 million in cumulative volume.
​

The reason to add x402 rather than gate with API keys is structural. Agents are bad at credential management — they cannot complete signup flows, do not have email addresses, and do not survive token rotations. They are excellent at signing structured payloads in milliseconds. x402 inverts the credential problem: the server trusts the signature on a payment, not a token issued ahead of time. No relationship persists between calls.
​

An x402-monetized MCP server has four runtime components: the MCP server itself (handles JSON-RPC over stdio or Streamable HTTP), the payment middleware (returns 402 on protected tools, accepts signed payment headers on retry), a facilitator service (verifies signatures and broadcasts settlement), and a wallet on the operator side that receives revenue. Each component is independently swappable.
​

Start at the boundary the agent sees. The agent's MCP client opens a connection to the server, exchanges initialize handshakes, and lists tools via tools/list. The list response includes a price annotation on every paid tool so the agent's wallet can decide ahead of time whether the call is in budget. When the agent calls tools/call for a paid tool without a payment header, the server returns HTTP 402 with a PAYMENT-REQUIRED envelope naming the chain (CAIP-2 form, e.g. eip155:8453 for Base), the asset contract, the amount, and the recipient. The agent's wallet signs an EIP-3009 transferWithAuthorization payload, the client retries with a PAYMENT-SIGNATURE header, the facilitator validates and submits the transfer, and the tool result returns once settlement confirms.
​

The facilitator is the part most builders underestimate. It verifies the signature, checks the nonce against a replay-prevention store, broadcasts the EIP-3009 transaction, and waits for confirmation before signaling the MCP server to release the response. Coinbase operates a hosted facilitator at api.cdp.coinbase.com; Cloudflare ships a self-hosted facilitator inside its Agents SDK that batches sub-cent payments on a deferred cadence. You can also run your own. The trade-off mirrors any payment processor — hosted is faster to integrate and absorbs compliance lifting; self-hosted gives control over settlement cadence and skips the per-transaction fee. For most operators starting out, the hosted facilitator is the right default.
​

The wallet is the last leg. Tool revenue lands in the recipient address you specify in the 402 envelope — typically a CDP Server Wallet v2 or another USDC-receiving wallet on the settlement chain. For a multi-tenant server where different tools route revenue to different publishers, each tool definition specifies its own recipient address and the facilitator settles accordingly. The separation of "who owns the server" from "who owns the revenue" falls out naturally from how the EIP-3009 transfer is authorized to a specific recipient.
​

One architectural note: MCP and x402 do not couple. A server can equally accept Stripe Shared Payment Tokens, AP2 mandates, or OAuth-protected API keys. This guide assumes x402 because the rest of the agent stack does — Coinbase's Agent.market, Cloudflare's Agents SDK, Akeneo's PIM-side MCP server, the Stripe MCP server, and dozens of independent publishers converge on x402 for tool calls priced under a dollar.
​

Before adding payment, define the three MCP primitives the server exposes. Tools are the executable functions an agent calls (the ones x402 will gate). Resources are read-only data the agent can subscribe to. Prompts are parameterized templates the host's LLM can use. A well-shaped server typically exposes 5-15 tools, 1-3 resource collections, and 0-3 prompts.
​

Tools are the surface most operators get wrong. The temptation is to expose every endpoint of an existing API one-to-one. The result is a catalog the host's planner cannot reason about. Better: design tool calls around the questions the agent has — "fetch latest pricing for SKU 12345," "summarize this customer's open invoices" — and bundle underlying API calls behind one tool per question. Stripe's MCP server exposes around 25 tools across 13 categories under this shape. Akeneo's MCP server, launched January 12, 2026, exposes a tighter set focused on PIM — read product, propose update, validate against governance rules.
​

Each tool exposes a JSON Schema describing its input arguments. The schema is the agent's only documentation — treat it as user-facing copy. Argument names should match what a junior engineer would say, not internal API parameter names. Required versus optional flags matter because the host's planner uses them to decide how to assemble a call. A schema with 14 optional fields and three required ones is hard to reason about; two required and one optional is trivial. Sprawling schemas are usually a signal to split the tool.
​

Resources are the read-only counterpart. Where tools are verbs, resources are nouns: a customer record, a product entry, a balance, a file. The MCP client lists resources via resources/list and reads them via resources/read. For an x402-monetized server the convention is to leave list and read free and only gate state-changing or compute-heavy tool calls — the same pattern as free GET, paid POST in a REST API. For high-value data resources (a real-time market feed, a private dataset), payment-gating reads is reasonable and the same x402 mechanism works.
​

Prompts are the third primitive and the one most servers omit. A prompt is a parameterized template the host's LLM can use directly. Where a tool says "here is a function to call," a prompt says "here is a template to fill in and reason over." Prompts are not typically payment-gated because they do not consume server resources. They are useful as freebies that improve the agent's behavior on your tools. The MCP spec at modelcontextprotocol.io documents the full handshake and JSON-RPC schema for each method.
​

For each payment-gated tool, add a price annotation to the JSON Schema metadata. The emerging convention is a custom field — typically x-x402 — carrying the price in token base units, the asset address, the chain ID, and the recipient. The host's wallet reads it during tools/list and can decide whether the call is in budget before issuing, avoiding a round-trip just to learn the price. Hosts that ignore the annotation still work — they get the 402 on first call.
​

Wrapping a tool with x402 means inserting a middleware step in the tools/call handler that checks for a payment header, returns 402 with a payment-required envelope if absent, and only calls the tool's actual implementation once the facilitator confirms settlement. The middleware is typically 30-50 lines of code and lives between the JSON-RPC parser and the tool function itself.
​

The control flow is mechanical. The MCP server receives a tools/call request. The middleware checks whether a PAYMENT-SIGNATURE header is attached. If absent, it looks up the tool's price metadata, builds a payment-required envelope (chain, asset, amount, recipient, nonce window), and returns HTTP 402. The agent's MCP client hands the envelope to its wallet, the wallet signs an EIP-3009 transferWithAuthorization, and the client retries with the signature. The middleware forwards the signature to the facilitator, and only after settlement confirms does it invoke the underlying tool function.
​

The signature is the load-bearing part. EIP-3009 defines a transferWithAuthorization primitive supported natively by USDC and most modern stablecoins: the holder signs a typed-data payload authorizing a transfer of a specific amount to a specific recipient within a specific time window, and any forwarder can submit the signature onchain. The nonce field — a 32-byte random value the contract refuses to spend twice — prevents replay. The validAfter and validBefore timestamps bound the settlement window. For x402, this is the entire payment primitive: one signature per payment, no prior session, no per-counterparty allowance.
​

The middleware decides where to call the facilitator. Coinbase's hosted facilitator exposes POST /verify and POST /settle — verify checks the signature without broadcasting, settle executes the transfer onchain. A common pattern is to call verify on every retry (cheap) and only call settle once the rest of the request has passed validation. That way a malformed payload never costs gas. Cloudflare's facilitator in the Agents SDK follows the same pattern and adds deferred settlement for sub-cent payments — batching calls into one transaction at a configured cadence, which makes per-call payments under a few cents economically viable.
​

The tool function does not need to know x402 exists. The middleware sits in front of it, which means an existing API or library can be wrapped without modification — the protected resource is unchanged, the payment gate is bolted on. Coinbase's reference example wraps a plain JavaScript MCP server with under 100 lines of middleware. The middleware is reusable across tools: define it once, apply it to any tool whose JSON Schema metadata includes a price annotation. Tools without one are free.
​

One subtlety: the price denomination must match what the wallet expects. If the annotation says "0.10 USDC on Base" but the agent's wallet only holds USDC on Solana, the agent cannot settle. Production implementations either emit a 402 with alternative payment options or restrict the server to a single chain. The simplest path is one chain (Base, almost always) and require the agent to bring USDC there.
​

Verification has two stages: signature verification (the facilitator confirms the signature is well-formed and the wallet has balance) and settlement verification (the onchain transfer confirms in a block). Logging means writing a structured receipt for every payment-gated call, keyed on the tool name, the agent's wallet address, the amount, the nonce, and the transaction hash, so revenue can be reconciled and audited.
​

Signature verification is what the facilitator does on the verify call. It checks that the EIP-3009 typed-data signature is valid for the wallet address, the nonce has not been spent (replay prevention), the time window is currently valid, and the wallet has enough balance to cover the transfer. None of this requires an onchain transaction. Verify is typically sub-second. Most middleware calls verify on every payment-gated request and only proceeds to settle once the tool's own input validation has passed — so a malformed payload never costs gas.
​

Settlement is the onchain step. The facilitator broadcasts the EIP-3009 transaction, the network includes it in a block, and the funds move. On Base, settlement typically confirms in 2-3 seconds. The middleware can await full confirmation before releasing the response (highest assurance) or release optimistically after broadcast (faster, with a small risk of an orphaned transaction). Most production servers await one block confirmation. The transaction hash becomes the receipt the server logs and the buyer can audit.
​

The receipt is the audit primitive. For every payment-gated call, log a structured row: tool name, buyer's wallet address, amount paid in token base units, asset and chain, the EIP-3009 nonce (unique identifier for the payment), the transaction hash, timestamp, originating tools/call request ID, and any tool-specific result identifier. Storing the nonce alongside the transaction hash matters because the nonce is what the buyer signed; if a buyer ever claims double-charging, you can prove which signature corresponds to which onchain transfer.
​

Allowance management is the buyer-side counterpart. The agent's wallet — typically a Coinbase Agentic Wallet, Circle Wallet, or Crossmint smart wallet — enforces session caps, per-token allowances, and counterparty allowlists before signing. The wallet's policy engine checks the proposed payment against remaining session cap and per-token limits before issuing the signature. If either limit would be exceeded, the wallet refuses and the agent never sends the payload. From the server's view this looks like the agent not retrying after a 402; operators do not have to design for it — the wallet does.
​

Webhook receipts are the optional next layer. Production MCP servers emit a webhook to the operator's backend whenever a payment-gated call completes, feeding dashboards and alerts. Idempotency keys and webhook signing apply the same way they do to Stripe events — HMAC-SHA256, timestamp, five-minute replay tolerance.
​

x402 gates an MCP tool call by intercepting the tools/call request before it reaches the tool function, returning HTTP 402 with a payment-required envelope, and only invoking the function once a facilitator has verified and settled the stablecoin transfer. The gate is a middleware layer between the MCP server's transport and the tool's implementation, transparent to both sides.
​

From the agent's side the gating is invisible to the LLM doing the planning. The MCP client handles the 402 and the retry transparently — the LLM asked for a tool call, the client returned a tool result, with one extra round trip and a wallet signature in between. The reasoning loop never has to decide "should I pay" because the wallet's policy engine made that decision the moment the 402 came back. The wallet is the bridge: the LLM does not have to reason about money, and the MCP server does not have to know the agent is autonomous.
​

The pattern composes with other commerce protocols. An MCP server can payment-gate one tool with x402, gate another tool with an ACP Shared Payment Token (for retail purchases routed through Stripe), and leave a third tool free. Each tool's middleware is independent. MCP became the upstream tool-discovery layer for the entire agentic-commerce stack precisely because every payment protocol composes against it without conflicting. The full agent payment protocols comparison walks through how x402, ACP, UCP, and AP2 each plug in.
​

An MCP server gets deployed in one of two transport modes: stdio (the server runs as a local subprocess of the host) or Streamable HTTP (the server runs remotely and the host connects over HTTPS). For a paid x402 server, Streamable HTTP is almost always correct because remote agents need to reach it. Once deployed, the server is registered with each agent framework — Claude Desktop, ChatGPT (Pro and above), Cursor, Codex, Gemini, Copilot — through a single configuration entry per host.
​

Streamable HTTP is the transport defined in MCP spec version 2025-11-25 (current per modelcontextprotocol.io). It uses HTTP POST for client-to-server messages and optional Server-Sent Events for streaming. Authentication is typically OAuth for enterprise servers, but for x402-gated servers the access control is the payment itself — the server does not need a session token because every paid tool call carries its own signed authorization. This eliminates an entire class of credential management on the server side and is one reason x402 is a clean fit for MCP.
​

Where to host the server is driven by latency and operational simplicity. Cloudflare Workers is the path of least resistance: the Agents SDK ships an MCP transport, the platform handles HTTPS and scaling, the facilitator runs as a co-located worker, and Workers' KV store handles the nonce cache. For a server alongside an existing API, a sidecar deployment on the same Kubernetes cluster works, with the MCP middleware as a thin gateway. Deno Deploy, Fly.io, AWS Lambda behind API Gateway — any platform supporting HTTPS and SSE works.
​

Registration with agent frameworks is the last step. Claude Desktop reads MCP server configurations from a JSON file in the user's application support directory. ChatGPT exposes connectors via its developer portal across Pro, Plus, Business, Enterprise, and Education tiers. Cursor, Codex, and Copilot have their own configuration entry points but accept the same Streamable HTTP MCP servers. Gemini supports MCP through Google's Agent Development Kit. The pattern is uniform: configure the URL, optionally configure OAuth, and the host's MCP client takes care of the rest. For an x402 server no OAuth is needed — the agent only needs the URL, and the wallet handles the rest at tools/call time.
​

The build pattern in this guide trades simplicity for some sharp edges. Pricing per tool call is finer-grained than most operators are used to, replay prevention requires the facilitator to maintain durable state, the buyer's wallet has to be on the same chain as the server's recipient address, and the experience is currently best on Base — which means a deliberate choice to settle on Base USDC even when other chains might fit a use case better.
​

Pricing per tool call is the first design choice and the easiest to get wrong. A tool that produces a small response — a lookup, an embedding, a status check — is easy to price at fractions of a cent. A tool that runs long compute or returns a large dataset is harder. Some operators charge a flat per-call fee; others charge base plus marginal for response size, which requires the price annotation to be a function and is not in the current x402 spec. The simplest path is a flat per-call price per tool, calibrated from observed usage. Underpricing is recoverable; overpricing turns away agents.
​

Replay prevention is the second sharp edge. The EIP-3009 nonce is a 32-byte random value the buyer commits to in their signature; the contract refuses to spend it twice, but the facilitator has to remember which nonces have been used. Hosted facilitators handle this; self-hosted ones need a durable store (Redis, KV, a small SQL table) that survives process restarts. A facilitator that loses its nonce store is a facilitator that double-spends.
​

The chain-locality problem is the third edge. If your server settles to USDC on Base and an agent only holds USDC on Solana, the agent cannot pay without a bridge or swap step in between. Some servers solve this by accepting multiple payment options in the 402 envelope, letting the agent's wallet pick the chain it can satisfy. That works but multiplies the operator's reconciliation surface. The other path is to push the chain-bridging problem to a settlement network and let the agent pay on its native chain while revenue lands on the operator's preferred one.
​

Several pieces of the pattern are still moving. The x402 Foundation is iterating on richer payment envelopes that include subscription-style and metered-billing options. MCP itself is moving toward elicitation primitives — letting a server ask the user for confirmation through the host's UI, which combined with x402 unlocks higher-value tool calls. AP2 mandates and ACP Shared Payment Tokens are converging into MCP-native composition patterns that will let one server accept several payment kinds depending on the buyer's runtime.
​

Eco is a stablecoin execution network that solves the chain-locality problem for MCP server operators. The MCP server still settles into whatever address it specified in the 402 envelope. Eco moves the resulting USDC across the 15 supported networks so that revenue lands on the operator's preferred chain, regardless of where the buyer paid. Hyperlane and CCTP carry the actual transport behind a single intent-style API.
​

An MCP server publisher is not the same person as the buyer. The publisher chooses one chain for revenue — where treasury operations live, where accounting reconciles, where stablecoin liquidity is deepest. The buyer's wallet might be on a different chain. Forcing the buyer to bridge before each tool call breaks the per-call model. Forcing the publisher to accept revenue on whichever chain a buyer happened to pay on creates a reconciliation surface that grows linearly with chain count. Eco closes both gaps by consolidating revenue across chains without requiring per-chain liquidity from the publisher. The agent pays where the agent holds funds; revenue lands where the publisher holds reserves; routing happens in between. For teams building stablecoin agent payment flows across more than one chain, that division of labor is the difference between integrating one settlement surface and stitching together a bridge per chain.
​

Sources and methodology. MCP protocol details verified against Anthropic's November 25, 2024 launch announcement and the December 9, 2025 AAIF donation announcement (10,000+ servers, 75+ Claude connectors, 97M monthly SDK downloads). MCP architecture from modelcontextprotocol.io and the 2025-11-25 specification revision. x402 protocol details from Coinbase CDP documentation; cumulative figures (165M transactions, 69k agents, ~$50M volume) from Cryptonews reporting Coinbase's April 2026 disclosures. Cloudflare Agents SDK + x402 timing per Cloudflare's September 23, 2025 blog post. CDP Server Wallets v2 GA July 24, 2025 per Coinbase Developer Platform. Akeneo MCP server launch January 12, 2026 per the Winter Release announcement. Stablecoin supplies (USDC $77.3B, USDT $189.5B) pulled from DeFiLlama on April 29, 2026. Figures refresh quarterly.
​