Paying with x402

On the MCP surface, payment happens inside the tool call. Your agent calls a tool; if the call needs payment, an x402-capable client signs and settles it and the tool returns its result. The model sees one tool call and one result.

What “x402-capable” means here

The MCP server signals that a tool call requires payment using the same x402 mechanism as the HTTP API: a payment challenge describing the price ($0.05 in USDC), network, token, and receiving address. A client is x402-capable if it can:

1. detect that challenge,
2. build a signed, gasless payment payload with your wallet, and
3. retry the tool call with the payment attached.

This logic lives in either your MCP client itself (if it supports x402) or a connector you run alongside it. You supply a funded wallet; the client does the rest.

The sequence

1. Tool call. The agent calls a tool — e.g. merge_pdfs — with arguments.
2. Payment required. The server responds that the call requires payment, with the x402 payment requirements (price, network, asset, payTo).
3. Sign. The client builds a gasless EIP-3009 USDC authorization with your wallet and encodes it.
4. Settle & run. The payment is verified and settled by the facilitator; the operation runs.
5. Result. The tool returns the download URL and a confirmation that payment settled. The model just sees the successful tool result.

Cost control

Because each call is quoted at a fixed $0.05 before it settles, you can bound spending in the client rather than relying on a plan limit. Depending on your client or connector you may be able to:

• set a per-session or per-task budget (stop after N paid calls),
• require manual approval above a threshold, or
• log each settlement for accounting (the response carries a settlement reference).

Note

The exact controls depend on your MCP client or connector. If your client doesn’t expose budgets, the connector recommended for preview access can enforce a spend cap.

When a call isn’t charged

If a tool call fails — bad input, unreachable URL, wrong password — it is not charged, just like the HTTP API. See Errors & failures. A payment only settles when the operation is going to produce a result.

Troubleshooting

• “Payment required” loops / call never completes — the client isn’t completing the x402 step. Confirm it’s x402-capable or that the connector is running, and that the wallet key is set.
• “Insufficient funds” — top up the wallet’s USDC on the configured network.
• Payment settles but tool errors — that’s a processing error; the charge is refunded. Check the tool error message and retry.

See also

• x402 payments — the protocol in full.
• Connecting a client — wiring up the wallet.
• Wallets & networks — funding and security.