Introducing x402-mcp: Open protocol payments for MCP tools

Link to headingHow does x402 help?

Developers building agents often encounter the same barrier: the agent can call APIs or MCPs, but integrating payments still requires manual setup such as registering accounts, exchanging keys, and configuring billing. The x402 protocol enables programmatic payments as part of the standard HTTP request flow.

Unlike vendor-specific payment APIs, x402 is designed as an open web protocol. It is not tied to any centralized payment provider and can support different payment networks or schemes.

Link to headingPaid API routes

For APIs, protecting routes is as simple as declaring middleware:

1
import { paymentMiddleware } from "x402-next";
2

3
export const middleware = paymentMiddleware(
4
  {
5
    "/protected": {
6
      price: 0.01,
7
      config: {
8
        description: "Access to protected content"
9
      }
10
    },
11
  }
12
);

On the client side, consuming these APIs just requires a fetch wrapper:

1
import { wrapFetchWithPayment } from "x402-fetch";
2

3
const fetchWithPay = wrapFetchWithPayment(fetch, client);
4
const response = await fetchWithPay("https://api.example.com/paid-endpoint");

Link to headingPaid MCP tools

For MCP servers, x402-mcp is a light wrapper around the existing mcp-handler package. It adds the ability to define paidTools, which include a price when called.

1
import { createPaidMcpHandler } from "x402-mcp";
2
import z from "zod";
3
const handler = createPaidMcpHandler(
4
  (server) => {
5
    server.paidTool(
6
      "add_numbers",
7
      { 
8
        // declare a price of $0.001
9
        price: 0.001 
10
      },
11
      { a: z.number(), b: z.number() },
12
      async (args) => {
13
        // ...your tool call
14
      }
15
    );
16
  },
17
  { recipient: process.env.WALLET_ADDRESS }
18
);
19
export { handler as GET, handler as POST };

On the client, payments are added with a single wrapper:

1
import { experimental_createMCPClient as createMCPClient } from "ai";
2
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
3
import { withPayment } from "x402-mcp";
4
const mcpClient = await createMCPClient({
5
  transport: new StreamableHTTPClientTransport(url),
6
}).then((client) => withPayment(client, { account }));
7
const tools = await mcpClient.tools();

This adds additional tools which enable agents to decide when and how to authorize tool payments over MCP in a transport-agnostic way.

Link to headingHow the protocol works

The protocol follows the standard HTTP exchange:

1. The client requests a protected resource

2. The server responds with a 402 status code and payment instructions

3. The client submits payment authorization in a header and retries the request

4. The server verifies and settles the request with an external payment “facilitator”

5. The server returns the resource to the client with payment outcomes in a header

Right now most implementations settle as exact, one-time payments in USDC on the Base blockchain, which enables fast and accountless transactions. However, the x402 standard itself is payment-network agnostic and supports other currencies and schemes, including non-crypto payments.

Link to headingTry the starter template

We created the x402 AI Starter template that demonstrates x402 in use with our wider suite of AI developer tools: Next.js, AI SDK, AI Elements, and AI Gateway. It has:

• An API route protected by paymentMiddleware

• An MCP server with a paidTool

• An MCP client extended with withPayment

• A normal page which charges crawlers using x402

• Secure server managed wallets through Coinbase's developer platform

• A frontend AI Chat + API playground to see x402 in action

The template deploys to Vercel with one click and comes with everything needed to start experimenting. Install the package with npm install x402-mcp and check out our live example.

Link to headingWhat's next

x402 offers a new approach to programmatic payments in AI applications. If you're building agents that need to pay for services, or APIs that want to charge agents, the starter template is a good place to begin exploring.