x402 Universal Payer — Claude Code MCP server: pay x402 endpoints
An MCP server that settles x402 payments for your agent: it signs, retries and returns the response with a settlement receipt, under spending caps.
claude mcp add --env MCP_BRIDGE_EVM_PRIVATE_KEY=<MCP_BRIDGE_EVM_PRIVATE_KEY> --env MCP_BRIDGE_SVM_PRIVATE_KEY=<MCP_BRIDGE_SVM_PRIVATE_KEY> --env MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC=<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC> --env MCP_BRIDGE_MAX_TOTAL_ATOMIC=<MCP_BRIDGE_MAX_TOTAL_ATOMIC> --env MCP_BRIDGE_ALLOWED_PAYTO=<MCP_BRIDGE_ALLOWED_PAYTO> --transport stdio mcp-bridge -- npx -y @three-ws/mcp-bridgeWhat x402 Universal Payer does
Point your agent at a URL that answers 402 Payment Required. The bridge signs the payment, retries the request and hands back the response plus a parsed settlement. EVM exact, EVM batch-settlement and Solana exact are all supported.
Four tools ship with it. call_paid_endpoint is the fallback: any URL, auto-pay on 402. list_bazaar_tools returns the cached Bazaar list and refresh_bazaar re-queries the feed and re-registers tools without a restart — both free. On top of that you get one tool per discovered Bazaar resource, up to MCP_BRIDGE_DISCOVER_LIMIT. Anything priced above the per-call cap is dropped at discovery time.
The server holds private keys and spends real USDC, so use a dedicated wallet with a small balance. At least one of MCP_BRIDGE_EVM_PRIVATE_KEY or MCP_BRIDGE_SVM_PRIVATE_KEY is required. MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC caps a single payment, MCP_BRIDGE_MAX_TOTAL_ATOMIC caps the whole session — once hit, further payments abort until restart. Payee and host allowlists are available, and outbound URLs are checked against private and loopback addresses. Retrying a paid call is a new charge.
What it helps with
- pay a paid API from inside the agent without a manual invoice
- get the response and settlement receipt from an x402 endpoint
- cap agent spending per call and per session
- expose x402 Bazaar services as ready-made tools
- block payments to untrusted addresses and hosts
Example prompts for the agent
- Pay $0.01 on Base for a weather report and show me the receipt
- Refresh the Bazaar tool list with
refresh_bazaar - Call
call_paid_endpointon this URL and return the response
How to install x402 Universal Payer
Platform CLI
claude mcp add --env MCP_BRIDGE_EVM_PRIVATE_KEY=<MCP_BRIDGE_EVM_PRIVATE_KEY> --env MCP_BRIDGE_SVM_PRIVATE_KEY=<MCP_BRIDGE_SVM_PRIVATE_KEY> --env MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC=<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC> --env MCP_BRIDGE_MAX_TOTAL_ATOMIC=<MCP_BRIDGE_MAX_TOTAL_ATOMIC> --env MCP_BRIDGE_ALLOWED_PAYTO=<MCP_BRIDGE_ALLOWED_PAYTO> --transport stdio mcp-bridge -- npx -y @three-ws/mcp-bridgeReplace <…> with your own values. 8 more environment variables are in the server README
Platform CLI
codex mcp add mcp-bridge --env MCP_BRIDGE_EVM_PRIVATE_KEY=<MCP_BRIDGE_EVM_PRIVATE_KEY> --env MCP_BRIDGE_SVM_PRIVATE_KEY=<MCP_BRIDGE_SVM_PRIVATE_KEY> --env MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC=<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC> --env MCP_BRIDGE_MAX_TOTAL_ATOMIC=<MCP_BRIDGE_MAX_TOTAL_ATOMIC> --env MCP_BRIDGE_ALLOWED_PAYTO=<MCP_BRIDGE_ALLOWED_PAYTO> -- npx -y @three-ws/mcp-bridgeReplace <…> with your own values. 8 more environment variables are in the server README
Config file
{
"mcpServers": {
"mcp-bridge": {
"command": "npx",
"args": [
"-y",
"@three-ws/mcp-bridge"
],
"env": {
"MCP_BRIDGE_EVM_PRIVATE_KEY": "<MCP_BRIDGE_EVM_PRIVATE_KEY>",
"MCP_BRIDGE_SVM_PRIVATE_KEY": "<MCP_BRIDGE_SVM_PRIVATE_KEY>",
"MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC": "<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC>",
"MCP_BRIDGE_MAX_TOTAL_ATOMIC": "<MCP_BRIDGE_MAX_TOTAL_ATOMIC>",
"MCP_BRIDGE_ALLOWED_PAYTO": "<MCP_BRIDGE_ALLOWED_PAYTO>"
}
}
}
}Replace <…> with your own values. 8 more environment variables are in the server README
Config file
{
"servers": {
"mcp-bridge": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/mcp-bridge"
],
"env": {
"MCP_BRIDGE_EVM_PRIVATE_KEY": "<MCP_BRIDGE_EVM_PRIVATE_KEY>",
"MCP_BRIDGE_SVM_PRIVATE_KEY": "<MCP_BRIDGE_SVM_PRIVATE_KEY>",
"MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC": "<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC>",
"MCP_BRIDGE_MAX_TOTAL_ATOMIC": "<MCP_BRIDGE_MAX_TOTAL_ATOMIC>",
"MCP_BRIDGE_ALLOWED_PAYTO": "<MCP_BRIDGE_ALLOWED_PAYTO>"
}
}
}
}Replace <…> with your own values. 8 more environment variables are in the server README
Platform CLI
gemini mcp add -e MCP_BRIDGE_EVM_PRIVATE_KEY=<MCP_BRIDGE_EVM_PRIVATE_KEY> -e MCP_BRIDGE_SVM_PRIVATE_KEY=<MCP_BRIDGE_SVM_PRIVATE_KEY> -e MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC=<MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC> -e MCP_BRIDGE_MAX_TOTAL_ATOMIC=<MCP_BRIDGE_MAX_TOTAL_ATOMIC> -e MCP_BRIDGE_ALLOWED_PAYTO=<MCP_BRIDGE_ALLOWED_PAYTO> mcp-bridge npx -y @three-ws/mcp-bridgeReplace <…> with your own values. 8 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about x402 Universal Payer
How do I install x402 Universal Payer in Claude Code?
Run `claude mcp add x402-bridge -e MCP_BRIDGE_EVM_PRIVATE_KEY=<MCP_BRIDGE_EVM_PRIVATE_KEY> -e MCP_BRIDGE_SVM_PRIVATE_KEY=<MCP_BRIDGE_SVM_PRIVATE_KEY> -- npx -y @three-ws/mcp-bridge`, then restart the client.
What does x402 Universal Payer do?
It pays x402 endpoints on the agent's behalf: signs the payment, retries the request and returns the response with a parsed settlement. It also loads tools from the x402 Bazaar.
Which keys does it need?
At least one: MCP_BRIDGE_EVM_PRIVATE_KEY for Base and other EVM chains, or MCP_BRIDGE_SVM_PRIVATE_KEY for Solana. A separate wallet with a small balance is the safer choice.
