TollNode

x402 MCP: how an agent pays for a tool call

How paid MCP tools work with x402: the error result that carries the price, the signed retry in _meta, and the receipt, shown with a live call to our server.

By the TollNode teamPublished 6 min read

A toll booth whose barrier arm is a plug, a coin dropping into its slot, and a toolbox waiting past the gate

Short answer

  • MCP has no payment step of its own. The x402 MCP transport adds one: a paid tool first answers with an error result that holds the price, and the client calls again with a signed USDC payment in params._meta["x402/payment"].
  • The receipt comes back in result._meta["x402/payment-response"] with the transaction hash, network and payer.
  • Signing moves no money. The server settles after the tool has run, and on TollNode a failed or empty call is never charged.
  • An agent that should not hold a wallet can connect with an API key instead and pay from a prepaid balance.
On this page
  1. Why does MCP need x402 for paid tools?
  2. The exchange, step by step
  3. What does the first answer look like?
  4. How does the agent send the payment?
  5. What comes back after a paid call?
  6. When the tool fails, nobody pays
  7. How do you keep an agent's spending in check?
  8. x402 or an API key on an MCP server?
  9. If you sell tools over MCP
  10. Try it against our server

On 17 November 2026 we sent one unpaid tools/call to our own MCP server at tollnode.com/mcp and asked for a Google search. It did not run the search. It answered with a price: 8000 units of USDC, which is $0.008, payable on Base. That answer is the first half of the x402 MCP transport. This post walks through the whole exchange with the real messages, then covers what happens when a tool fails, how to cap what an agent spends, and how to charge for your own tools. It is written for developers wiring an agent to paid tools and for anyone who wants to sell tools over MCP.

Why does MCP need x402 for paid tools?

MCP describes how an agent finds and calls tools. It says nothing about money. A server that wants to charge has two options: ask every user to sign up and paste an API key, or let the agent pay per call.

x402 is the per-call option. It started on plain HTTP, where a server answers 402 Payment Required with a price and the client retries with a signed payment. MCP calls do not travel as separate HTTP requests the way REST calls do, so the x402 Foundation published a small transport spec that moves the same objects into MCP's reserved _meta field. It adds no MCP method and no status code, so a client that does not know about x402 just sees a tool error with a price in it.

The exchange, step by step

AgentServerBase
  1. 1 tools/call run_toolNo payment attached.

  2. 2 isError: true + PaymentRequiredThe price, network, asset and payee.

  3. 3 tools/call + _meta["x402/payment"]Same call, now carrying a signed USDC authorization.

  4. 4 verify, run the tool, settleSettled only if the tool delivered a result.

  5. 5 result + _meta["x402/payment-response"]The tool's output and the transaction hash.

Five messages: one call that gets a price, one call that pays.
Top lane: a parcel bounces back from a closed barrier with a price tag. Bottom lane: the same parcel carries a sealed coin through the open barrier.
The first call bounces with a price. The second carries the signed payment and goes through.

The agent decides between steps 2 and 3. It reads the price, checks it against its budget, and only then signs. Nothing is paid until the server settles in step 4.

What does the first answer look like?

Here is what our server returned for that unpaid search, captured on 17 November 2026 and trimmed to the fields that matter:

{
  "isError": true,
  "structuredContent": {
    "x402Version": 2,
    "resource": {
      "url": "https://tollnode.com/api/v1/nodes/web-search",
      "method": "POST",
      "description": "Google web search results. … Charged only when the call succeeds."
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "8000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0xb8E9…520c",
        "maxTimeoutSeconds": 300,
        "extra": { "name": "USD Coin", "version": "2" }
      }
    ]
  },
  "content": [{ "type": "text", "text": "{\"x402Version\":2,…}" }]
}

The spec asks for the same object twice: once in structuredContent and once as JSON text in content[0].text, for clients that only read text. Clients should look for x402Version and accepts in structuredContent first.

FieldWhat it means
scheme: "exact"Pay exactly this amount, once.
network: "eip155:8453"Base mainnet, written as a CAIP-2 chain id.
amount: "8000"USDC has 6 decimals, so 8000 units is $0.008.
assetThe USDC contract on Base, as listed by Circle.
payToThe wallet that receives the money.
maxTimeoutSeconds: 300How long the signed payment stays usable.

A careful client checks asset, network and amount before it signs. A server that swaps any of them should get no signature.

How does the agent send the payment?

The agent repeats the same tools/call and adds the signed payment under params._meta["x402/payment"]:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "run_tool",
    "arguments": { "name": "web-search", "input": { "query": "x402 mcp" } },
    "_meta": {
      "x402/payment": {
        "x402Version": 2,
        "resource": { "url": "https://tollnode.com/api/v1/nodes/web-search" },
        "accepted": { "scheme": "exact", "network": "eip155:8453", "amount": "8000", "payTo": "0xb8E9…520c" },
        "payload": {
          "signature": "0x…",
          "authorization": { "from": "0x…", "to": "0xb8E9…520c", "value": "8000", "validAfter": "…", "validBefore": "…", "nonce": "0x…" }
        }
      }
    }
  }
}

The authorization is a USDC transfer the wallet has signed but not sent. It names one amount, one recipient and an expiry time, and it carries a one-time nonce, so the server cannot take more or use it twice.

You rarely build this by hand. The official @x402/mcp package wraps an MCP client and does both calls for you. This is a complete agent that pays our server per call and refuses anything over five cents:

// npm i @x402/mcp @x402/evm @modelcontextprotocol/sdk viem
import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { privateKeyToAccount } from "viem/accounts";

const wallet = privateKeyToAccount(process.env.AGENT_WALLET_KEY as `0x${string}`);

const client = createx402MCPClient({
  name: "my-agent",
  version: "1.0.0",
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(wallet) }],
  spendControls: { maxAmountPerPayment: "$0.05" },
  onPaymentRequested: async ({ paymentRequired }) => {
    console.log("price in USDC units:", paymentRequired.accepts[0].amount);
    return true; // return false to refuse
  },
});

await client.connect(new StreamableHTTPClientTransport(new URL("https://tollnode.com/mcp")));

const result = await client.callTool("run_tool", { name: "web-search", input: { query: "x402 mcp" } });
if (result.paymentMade) console.log("settled in tx", result.paymentResponse?.transaction);

What comes back after a paid call?

The normal tool result, plus a receipt in _meta:

{
  "content": [{ "type": "text", "text": "{\"results\":[…]}" }],
  "_meta": {
    "x402/payment-response": {
      "success": true,
      "transaction": "0x…",
      "network": "eip155:8453",
      "payer": "0x…"
    }
  }
}

transaction is the hash of the USDC transfer on Base. Log it next to the tool output. If anyone later asks what the agent spent and on what, that hash is the answer.

When the tool fails, nobody pays

A toll gate with two exits: an intact parcel passes and its coin drops into the box; a broken parcel is stopped and its coin rolls back.
Settle after the work, not before. A broken result keeps its coin.

Signing and paying are two separate events. The signature authorizes a transfer; the transfer only happens when the server settles it. The spec leaves the order to the server, with one firm rule: if settlement fails after the tool ran, the server returns the payment error and not the tool's output.

We go one step further. Our server verifies the signature, runs the tool, and settles only when the result is usable. A timeout, an upstream error or an empty answer ends with no settlement, so the signed authorization expires unused and the agent keeps its USDC. After three failures in a row we pause the tool until it is fixed, so agents don't keep calling something broken.

How do you keep an agent's spending in check?

Four habits cover most of the risk:

  1. Cap each payment. The spendControls line in the code above refuses any single payment over $0.05 (the package's default cap is $1). Pick a cap a little above the most expensive tool you expect to call.
  2. Keep the wallet small. Fund it with what you are happy for the agent to spend this week. A few dollars covers hundreds of searches at $0.008 each.
  3. Look at the price before signing. onPaymentRequested sees every price; log it, and refuse a payee or network you did not expect.
  4. Don't sign twice on a timeout. Each signature has its own nonce, so a fresh signature on retry is a second purchase. Check whether the first one settled before paying again.

x402 or an API key on an MCP server?

Our server takes both, and they suit different agents:

x402 per callAPI key
Sign-upNoneOne account
Where the money sitsThe agent's own walletA prepaid TollNode balance
What the agent sendsA signed payment in _meta on each paid callAuthorization: Bearer tn_live_… on the connection
Recover a dropped callCheck the wallet historyget_call with the request id
Good forAgents that already hold USDC, or one-off useTeams, budgets, and chat apps that can't sign

With a key, run_tool never returns a price to sign; the cost comes off the balance and the result ends with the amount charged and a request id.

If you sell tools over MCP

Charging is mostly a wrapper around a tool you already have:

  • Cloudflare's Agents SDK has paidTool, which registers a tool with a price in US dollars and handles the x402 exchange.
  • The @x402/mcp package has createPaymentWrapper for the official TypeScript MCP SDK, with hooks before execution, after execution and after settlement. The after-execution hook is where you refuse to settle an empty result.
  • You can also reuse an HTTP endpoint you already sell. Our MCP server forwards each run_tool to the same HTTP endpoint that sells over plain x402, so price, verification and settle-on-success live in one place for both.

Whichever you use, put the price in the tool's description too. Agents choose tools by reading descriptions, and a price they can see before calling saves everyone a round trip.

Try it against our server

The unpaid call is free and shows the exact price object for any tool:

curl -s https://tollnode.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_tool","arguments":{"name":"web-search","input":{"query":"x402 mcp"}}}}'

Swap web-search for any tool from search_tools. To connect an agent for real, the connect page has the setup for Claude, Cursor and other clients, and What is x402? covers the HTTP side of the same protocol.


Questions people ask

Does MCP support payments on its own?

No. The MCP specification has no payment step. It reserves a _meta field on every request and result for extra data, and the x402 MCP transport uses that field to carry the payment and the receipt.

Do I need ETH to pay for an MCP tool with x402?

No. The agent signs a USDC transfer authorization. The facilitator submits it on Base and pays the network fee, so a wallet that holds only USDC can pay.

Is x402 over MCP different from x402 over HTTP?

The payment objects are the same. Over HTTP the price travels in the PAYMENT-REQUIRED header and the payment in PAYMENT-SIGNATURE. Over MCP the price is the tool's error result and the payment sits in params._meta["x402/payment"].

What happens if the connection drops after the agent signed?

On TollNode the call keeps running to the end and the payment settles only if it delivered. With an API key, get_call returns the result by request id. With x402, check the wallet before signing a second payment, because a second signature is a second purchase.

Can an MCP server mix free and paid tools?

Yes. Payment is per tool call. Our server's search_tools, get_tool, get_call, list_calls, get_balance and upload_file are free, and only run_tool asks for payment.

Try it on TollNode

Live prices. Pay per call with x402 or an API key, charged only when the call returns a usable result.

Sources

  1. x402 MCP transport specification (v2), x402 Foundation
  2. MCP specification 2025-11-25: the _meta field, Model Context Protocol
  3. @x402/mcp package (version 2.31.0), npm
  4. Charge for MCP tools, Cloudflare
  5. USDC contract addresses, Circle

Written by the TollNode team. We run a pay-per-call catalog of AI models and live data for agents, so what we write about x402 and MCP comes from serving those calls. Facts are checked against the linked sources and our own live endpoints on the date shown. How we write.