Cloudflare Agents SDK adds x402 payments for MCP tool calls

Cloudflare updated the Agents SDK to support the x402 payment protocol, allowing sellers to charge USDC for individual MCP tool calls.

On the seller side, developers wrap their McpServer instance with withX402 and register paid endpoints with paidTool. Free endpoints remain registered with tool on the same wrapped server. paidTool accepts a name, description, price in USD, a Zod input schema, optional annotations and an async handler.

X402Config requires three fields: network (use “base” for mainnet or “base-sepolia” for testing), recipient (the wallet address that receives USDC) and a facilitator URL. Cloudflare examples use https://x402.org/facilitator. Sellers set USD prices and settlement occurs in USDC on the configured network.

When a client calls a paid tool without payment, the server responds with HTTP 402 and includes payment requirements. The client signs a payment payload off-chain or on-chain, submits payment via the x402 protocol and retries the request with a PAYMENT-SIGNATURE header. After the payment proof is accepted, the server returns the tool result.

Cloudflare provides withX402Client for Agents SDK clients to automate the pay-and-retry loop. Example buyer code uses privateKeyToAccount from viem to build a wallet account and can pass an onPaymentRequired callback or let the client helper handle payments automatically.

Cloudflare recommends testing on base-sepolia and using Circle’s test USDC faucet before switching X402Config to base. Sample code is available in the cloudflare/agents examples/x402-mcp repository and in the Agents SDK documentation pages titled Charge for MCP tools and Pay from Agents SDK.

Operators must choose a facilitator, set the recipient wallet and lock the network configuration before advertising paid MCP endpoints. Developers should store private keys in wrangler secrets or .dev.vars and avoid committing them to source control.

The Agents SDK x402 seller flow is separate from Cloudflare’s Monetization Gateway waitlist, AgentKit buyer guides and Stripe integrations for stablecoins. AgentKit documents the buyer path for paying third-party x402 APIs, while the Agents SDK paidTool flow covers operating a paid MCP server.

The x402 protocol uses HTTP 402 as the payment-required signal and an off-chain or on-chain payment proof attached to a retried request. Paid tool calls are per-call payments priced in USD and settled in USDC through a facilitator.