@three-ws/mcp-bridge

One MCP server that can pay any x402-paid endpoint on the open web — the universal x402 payer for AI agents.

Quick start · Security · Tools · Environment · three.ws

A Model Context Protocol server that can pay any x402-paid endpoint on the open web. Point your agent at a URL that answers 402 Payment Required; the bridge signs, pays, retries, and hands back the response plus the settlement receipt — EVM exact, EVM batch-settlement, and Solana exact, all behind hard spending caps. It also pre-loads a tool per service discovered on the Coinbase x402 Bazaar, so the entire paid-API economy shows up in your tool list.

Quick start

Claude Code:

claude mcp add x402-bridge -e MCP_BRIDGE_SVM_PRIVATE_KEY=... -- npx -y @three-ws/mcp-bridge

Use -e MCP_BRIDGE_EVM_PRIVATE_KEY=0x... instead (or as well) to pay on Base and other EVM chains. At least one key is required.

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

{
	"mcpServers": {
		"x402-bridge": {
			"command": "npx",
			"args": ["-y", "@three-ws/mcp-bridge"],
			"env": {
				"MCP_BRIDGE_EVM_PRIVATE_KEY": "0x…buyer key…",
				"MCP_BRIDGE_SVM_PRIVATE_KEY": "…base58 64-byte secret key…",
				"MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC": "100000",
				"MCP_BRIDGE_DISCOVER_LIMIT": "20"
			}
		}
	}
}

Restart the client and ask for something like "pay $0.01 on Base for a weather report" — the model picks a matching Bazaar tool (or call_paid_endpoint), and the bridge auto-pays via x402.

Security and spending controls

This server holds private keys and spends real USDC. Read this section before configuring it.

• Use a dedicated, low-balance wallet. MCP_BRIDGE_EVM_PRIVATE_KEY / MCP_BRIDGE_SVM_PRIVATE_KEY should never be a main wallet. Fund it with only what you are willing to let an agent spend.
• Per-call cap. Any payment above MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC (default 100000 = $0.10 USDC) is refused before a payload is signed, with an error naming the network, asset, and cap.
• Session ceiling. Cumulative spend per process is capped by MCP_BRIDGE_MAX_TOTAL_ATOMIC (default 1000000 = $1.00 USDC). This bounds the damage of a looping or prompt-injected agent: once the ceiling is reached, every further payment aborts until restart. The accumulator reserves atomically, so concurrent calls cannot jointly overshoot it.
• Payee allowlist. Set MCP_BRIDGE_ALLOWED_PAYTO (comma-separated addresses) to refuse payment to any recipient you have not explicitly trusted.
• SSRF guard. Every outbound payable URL — whether supplied by the model or by a Bazaar listing — passes one chokepoint that enforces an https-only scheme policy, resolves the hostname, and rejects the request if any resolved address is private, loopback, link-local (including 169.254.169.254 cloud metadata), CGNAT, ULA, or unspecified. Literal-IP hosts are checked directly; redirects are never followed (a public host cannot 3xx the bridge into internal infrastructure). http:// is available only behind the explicit MCP_BRIDGE_ALLOW_HTTP=1 dev opt-in.
• Host allowlist. Set MCP_BRIDGE_ALLOWED_HOSTS (comma-separated hostnames) for strict mode: only listed hosts can be paid at all.
• Deposit caps. Batch-settlement channel deposits are bounded by MCP_BRIDGE_MAX_DEPOSIT_ATOMIC (default $5.00) regardless of what a server requests.
• Honest annotations. Every paying tool is annotated readOnlyHint: false, idempotentHint: false, openWorldHint: true, so MCP hosts apply their strictest confirmation policy. Retrying a paid call is a new charge.

What it exposes

On startup the bridge registers:

Tools whose prices all exceed the per-call cap are filtered out at discovery time, so the model never sees a tool it cannot afford.

Tool annotations

Every tool carries MCP ToolAnnotations so hosts can apply the right confirmation policy:

• call_paid_endpoint and every dynamic paid_* tool: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true. These spend real USDC — each call settles a payment (capped by MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC), and retrying is a new charge. They never delete or overwrite caller state, hence not destructive.
• list_bazaar_tools: readOnlyHint: true, idempotentHint: true, openWorldHint: false. Pure in-process cache read; free, no network.
• refresh_bazaar: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true. Free (no payment), but it mutates the registered tool set from the live Bazaar feed, so repeat calls can differ.

Tool results that are plain objects are returned as both a JSON text block (backward compatible) and structuredContent for typed clients.

Payment schemes

Payment paths registered on the buyer client:

• eip155:* → BatchSettlementEvmScheme (preferred when the server advertises it; voucher-based, no per-call gas)
• eip155:* → ExactEvmScheme (used when the server advertises scheme: "exact")
• solana:* → ExactSvmScheme (USDC SPL transfer co-signed by the advertised fee payer)

Batch-settlement channel state is persisted to ~/.x402-mcp-bridge/channels/client/ so client restarts do not re-deposit on the next call.

Environment

MCP_BRIDGE_* key vars also fall back to EVM_PRIVATE_KEY / SVM_PRIVATE_KEY if you already have those set.

Spending cap behavior

The pre-payment hook inspects the selected accepts entry and aborts payload creation if the amount exceeds the per-call cap, the payee is outside the allowlist, or the session ceiling would be crossed. The tool result then carries a clear error message naming the network, asset, and the limit that was hit — useful for the model to decide whether to ask you to raise it.

Inspecting without a client

MCP_BRIDGE_SVM_PRIVATE_KEY=... npx -y @modelcontextprotocol/inspector npx -y @three-ws/mcp-bridge

The inspector connects over stdio and lists the static tools (call_paid_endpoint, list_bazaar_tools, refresh_bazaar) plus one dynamic tool per discovered Bazaar entry.

Programmatic use

Any Node module can consume an x402 endpoint through the same buyer client:

import { buildBuyerAxios } from '@three-ws/mcp-bridge/src/x402-axios-client.js';

const { api } = await buildBuyerAxios();
const res = await api.get('https://api.example.com/some-paid-resource');

The same spending caps, SSRF guard, and channel-storage rules apply. Idle batch channels can be refunded out-of-band with the @x402 SDK's client.refund(resourceUrl, { amount }).

Tests

npm test           # hermetic: url-guard SSRF policy, spending-cap hook, tool naming, stdio boot
npm run test:smoke # live: boots against the real Bazaar and asserts the cap blocks a real paid call

The hermetic suite generates throwaway keypairs in-process; no real keys or funds are ever involved.

License

All rights reserved. See LICENSE.