Table of Contents
Cloudflare Agents SDK x402 lets sellers charge USDC per MCP tool call with withX402 plus paidTool. Clients that lack payment get HTTP 402, pay via x402, retry with proof, then receive the tool result.
This guide is the seller-side path on Cloudflare Workers Agents. It is not the buyer-only AgentKit flow, not Stripe checkout for x402, and not Cloudflare's separate Monetization Gateway waitlist product.
Primary sources: Charge for MCP tools, Pay from Agents SDK, and x402 on Cloudflare Agents. Working sample: cloudflare/agents examples/x402-mcp.
Key Takeaways
- Seller path: wrap McpServer with withX402, then charge with paidTool while free tools stay on tool().
- Docs example prices paidTool "square" at $0.01 USD per call; mix paid and free tools in one server.
- X402Config uses network base or base-sepolia, a recipient wallet, and facilitator https://x402.org/facilitator.
- Buyers wrap the MCP client with withX402Client; unpaid paidTool calls return 402 until payment proof retries.
- Test on base-sepolia with Circle faucet USDC; use wrangler secrets for private keys, never commit keys.
What Cloudflare Agents x402 MCP billing is (and is not)
x402 is a payment standard built around HTTP 402 Payment Required. The server returns payment details; the client signs a payment payload and retries with a PAYMENT-SIGNATURE header.
On Cloudflare Agents, agents/x402 adds withX402 for MCP servers and withX402Client for MCP clients. Sellers define price in USD on paidTool; settlement is USDC on the configured network via a facilitator.
This object is not Cloudflare Monetization Gateway waitlist news, not how to pay for an x402 API with Coinbase AgentKit (buyer AgentKit), and not how to accept x402 USDC payments on Stripe. For protocol basics, see x402 protocol.
Who this is for (and who should skip it)
Use this when the team ships MCP tools on Cloudflare Agents and wants per-call USDC pricing without API keys or session accounts for each buyer agent.
Skip it when the job is only buying someone else's x402 API (use AgentKit or Circle agent nanopayment guides), when you need Stripe-hosted acceptance, or when you are waiting on Monetization Gateway and do not yet run Agents SDK MCP.
Seller checklist: charge for MCP tools (2026)
1. Confirm Agents SDK and x402 imports
Cloudflare docs import McpServer from @modelcontextprotocol/sdk/server/mcp.js, McpAgent from agents/mcp, and withX402 plus X402Config from agents/x402. Zod schemas define tool inputs.
Keep the Agents Worker project on a current agents package so paidTool is available as a drop-in replacement for tool.
2. Set X402Config (network, recipient, facilitator)
Docs configuration fields:
| Field | Docs value | Notes |
|---|---|---|
| network | base or base-sepolia | base for production; base-sepolia for testing |
| recipient | 0xYourWalletAddress | Wallet that receives USDC |
| facilitator | https://x402.org/facilitator | Public facilitator used in Cloudflare examples |
Facilitators verify and settle without holding funds. Cloudflare examples use https://x402.org/facilitator. For facilitator selection tradeoffs, see how to choose an x402 facilitator for USDC.
3. Wrap McpServer with withX402
Subclass McpAgent and assign server = withX402(new McpServer({ name, version }), X402_CONFIG). That wrap is what attaches payment requirements to paid tools.
Without withX402, paidTool is not the documented path. Free tools still register with this.server.tool(...) on the same wrapped server.
4. Register paidTool and free tool side by side
paidTool signature from Cloudflare docs: name, description, price in USD, Zod input schema, MCP annotations object, async handler.
Docs example: paidTool("square", "Squares a number", 0.01, { number: z.number() }, {}, handler). Price 0.01 means $0.01 USD per call. A free echo tool uses this.server.tool with no price.
When a client calls a paid tool without payment, the server returns 402 with payment requirements. After x402 payment proof, the client retries and receives the result.
5. Buyer side: withX402Client on Agents SDK
Paying agents connect to the MCP endpoint, build a wallet account (docs use privateKeyToAccount from viem), then wrap the MCP client with withX402Client.
Docs show callTool with an optional confirmation callback (onPaymentRequired) or null for automatic payment. Store MY_PRIVATE_KEY in .dev.vars locally and wrangler secret put MY_PRIVATE_KEY in production.
6. Test on base-sepolia, then promote to base
Set network: "base-sepolia" while integrating. Cloudflare points testers to the Circle faucet for test USDC. Flip to network: "base" only after recipient, facilitator, and tool prices are verified.
Use the official x402-mcp GitHub example as a complete working reference. Do not invent undocumented paidTool fields beyond the docs signature.
paidTool vs free tool vs Monetization Gateway
| Option | What it is | When to use |
|---|---|---|
| paidTool + withX402 | Per MCP tool call USDC price on Agents SDK | You already run MCP on Cloudflare Agents and need seller-side micropayments |
| tool() (free) | Same MCP server, no 402 gate | Health checks, discovery, or unmetered helpers beside paid tools |
| Monetization Gateway waitlist | Separate Cloudflare product on x402 (waitlist) | You want Cloudflare's gateway product, not Agents SDK MCP wrappers |
| AgentKit buyer path | Client pays third-party x402 APIs | Your agent consumes paid APIs; you are not the MCP seller |
Operators comparing acceptance surfaces should also read how to accept x402 USDC payments from AI agents. Keep seller MCP wrapping and buyer AgentKit runbooks in separate docs so credentials never mix.
Stablecoin Insider's take
If the stack is buyer-only, stay on AgentKit x402 pay how-to or Circle nanopayment guides. If the roadmap is Monetization Gateway, track the waitlist post and do not conflate it with Agents SDK MCP billing.
Need the protocol frame before you wrap MCP?
FAQ
What is paidTool in Cloudflare Agents?
paidTool is a drop-in replacement for tool that adds an x402 payment requirement on an MCP server wrapped with withX402.
Clients pay per tool call in USDC on the configured network; free tools can still use tool() on the same server.
How much does the Cloudflare docs example charge?
The Charge for MCP tools docs price the sample paidTool named square at $0.01 USD per call.
Teams set their own USD price argument; do not assume $0.01 is a platform fee.
Which network and facilitator do Cloudflare examples use?
X402Config uses network base for production or base-sepolia for testing, plus facilitator URL https://x402.org/facilitator.
Recipient is the merchant wallet address that receives USDC.
What happens if a client calls a paid tool without paying?
The server returns HTTP 402 with payment requirements. The client pays via x402, retries with payment proof, and then receives the tool result.
withX402Client on the Agents SDK automates that client loop.
Is this the same as Cloudflare Monetization Gateway?
No. Monetization Gateway is a separate Cloudflare waitlist product built on x402.
This guide covers Agents SDK withX402 and paidTool for MCP servers you operate.
How should teams test before mainnet?
Use network base-sepolia and get test USDC from the Circle faucet, as Cloudflare docs recommend.
Keep private keys in wrangler secrets or .dev.vars; never commit them.
Where is the official end-to-end example?
Cloudflare points to the x402-mcp example under cloudflare/agents on GitHub.
Pair it with the Charge for MCP tools and Pay from Agents SDK docs pages.
This content is provided for informational and educational purposes only and does not constitute financial, investment, legal, or tax advice; no material herein should be interpreted as a recommendation, endorsement, or solicitation to buy or sell any financial instrument, and readers should conduct their own independent research or consult a qualified professional.
){kind=link}