How does x402 work with MCP and AI agents?
Short answer
MCP lets an AI assistant call external tools. x402 lets a tool charge for a call. Together, a paid MCP tool answers with the payment requirements, the assistant's client attaches a signed payment and calls again, and the tool returns its result with a receipt. The x402 specification defines this exchange as an official MCP transport.
The two pieces
MCP (Model Context Protocol) is how assistants such as Claude discover and call tools: a search tool, a database, a browser.
x402 is how a service gets paid per request.
An assistant with both can use a tool it has never seen before and pay for it on the spot, with no account and no API key for a person to set up first.
Two ways they connect
1. An MCP server that pays x402 APIs for you
The MCP server holds a wallet. When the assistant calls one of its tools, the server makes an ordinary x402 request to a paid HTTP API, pays, and hands back the result. The assistant never sees the payment. This works with any MCP client, because all the x402 logic sits in the server.
2. Paid MCP tools, with payment inside MCP itself
Here the tool itself charges, and the payment travels in MCP messages instead of HTTP headers. The x402 specification defines how:
- The assistant calls the tool with no payment.
- The tool returns an error result that carries the payment requirements.
- The client signs a payment and calls the tool again, with the payment in the request's
_metafield underx402/payment. - The tool returns its result, with the receipt under
x402/payment-response.
The content of those messages is the same as in HTTP. Only the envelope differs. This route needs an MCP client that understands x402.
There is also a transport for A2A, the agent-to-agent protocol.
What to use
| You are | Look at |
|---|---|
| Building a paid MCP tool | @x402/mcp, or Cloudflare's Agents SDK, which has a paidTool helper |
| Building an agent that pays | An x402-aware MCP client: @x402/mcp or the Cloudflare Agents SDK |
| A person who wants their assistant to use paid tools | A wallet that connects through MCP with a budget, or a hosted MCP server from a tool provider |
See SDKs and wallets in the directory.
Hosted MCP servers from tool catalogs
Some catalogs of x402 tools publish their own MCP server, so one connection gives an assistant the whole catalog. Agent402, for example, has a hosted server at https://agent402.tools/mcp. Adding it gives an assistant tool discovery and the free tools. Paid tools need a payment method configured separately. See the setup guide.
Before you let an agent spend
An assistant that can pay will pay for whatever it is persuaded to call. Give it a wallet with a small balance and a per-call ceiling, and prefer setups where you approve spending above a threshold. More in is x402 safe?.
Sources
- x402 MCP transport specification
- MCP server with x402, x402 documentation
- Cloudflare Agents, x402
- Coinbase agentic wallet documentation
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.