MCP payments

MCP payments let an assistant pay for a tool call made over the Model Context Protocol, either through a local MCP server that signs payments underneath (wallet or prepaid key) or through a hosted connector that returns MPP challenges in the tool result and accepts a credential in _meta on the retry.

Two places payment can happen

The Model Context Protocol lets an assistant discover and call tools. It does not itself say how a tool gets paid for, so there are two practical patterns, and this server supports both.

  1. A local MCP server pays underneath. The assistant talks to a stdio server on your machine (npx -y agent402-mcp). When a tool call hits a 402, that server pays it with the key you configured and returns the result. The assistant never sees the payment.
  2. A hosted connector asks, and the client pays. The assistant talks to a remote MCP endpoint (https://agent402.tools/mcp). A wallet-only tool answers with the payment challenges attached, and a client that speaks MPP pays and repeats the call.

The local server

Configure one of three things: AGENT_KEY (an EVM key holding USDC, signing x402 payments), AGENT402_CREDITS_KEY (a prepaid card-credits key, sent as a Bearer token and debited only on success), or nothing, in which case the pure-CPU tools pay with proof-of-work. AGENT402_MAX_PER_CALL and AGENT402_BUDGET are checked before any payment is signed.

{
  "mcpServers": {
    "agent402": {
      "command": "npx",
      "args": ["-y", "agent402-mcp"],
      "env": { "AGENT402_CREDITS_KEY": "a402_YOUR_KEY", "AGENT402_MAX_PER_CALL": "0.05" }
    }
  }
}

The hosted connector

On the hosted connector the pure-CPU tools run free (rate-limited). A wallet-only tool called without payment returns a readable tool result with the MPP challenges in _meta["org.paymentauth/payment-required"], so a host that does not speak MPP still shows the user something useful. An MCP client wrapped with mppx's McpClient.wrap() reads the challenges, pays, and retries with the credential in _meta["org.paymentauth/credential"]; the result comes back with _meta["org.paymentauth/receipt"]. A credential that is refused is JSON-RPC error -32043.

// tools/call on https://agent402.tools/mcp for a wallet-only tool, no credential yet
{
  "content": [{ "type": "text", "text": "This tool needs payment ..." }],
  "isError": true,
  "_meta": {
    "org.paymentauth/payment-required": {
      "httpStatus": 402,
      "challenges": [{ "id": "...", "method": "evm", "intent": "charge", "request": { "amount": "...", ... } }]
    }
  }
}

// the retry carries the credential in params._meta["org.paymentauth/credential"];
// the paid result carries _meta["org.paymentauth/receipt"]

Behind the connector the call is replayed against the same paid HTTP route an HTTP client would use, so the price, the settlement rules and the receipt are identical either way.

Related

More explainers: x402 · HTTP 402 Payment Required · MPP (Machine Payments Protocol) · Agent payments · Pay-per-call API