@quackai/q402-mcp

MCP server for Q402 — gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.

Claude can now reason about stablecoin payments end to end — quote a transfer across 7 chains, pick the cheapest route, and (optionally) settle the transaction over Q402's EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.

Quick start (Claude Desktop)

claude mcp add q402 -- npx -y @quackai/q402-mcp

Or, if you prefer editing the config file directly, add this entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "q402": {
      "command": "npx",
      "args": ["-y", "@quackai/q402-mcp"]
    }
  }
}

Restart Claude Desktop and ask:

"Compare gas costs to send 50 USDC to vitalik.eth across all 7 Q402 chains."

You'll get a ranked breakdown immediately — no API key, no signup, no funds at risk.

Tools exposed

q402_pay follows a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address, amount, chain, and token.

Per-chain gas tank balances and full transaction history live in the dashboard — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.

Sandbox vs live mode

By default the MCP server operates in sandbox mode: q402_pay returns a deterministic-looking fake transaction hash, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any Claude Desktop install without worrying about an LLM hallucinating a payment.

To enable real on-chain transactions, all three environment variables must be set:

Q402_API_KEY=q402_live_...           # live-tier key from /dashboard
Q402_PRIVATE_KEY=0xabc...            # signer for the payer EOA
Q402_ENABLE_REAL_PAYMENTS=1          # explicit opt-in

Anything missing → automatic sandbox fallback with a hint pointing at what to set.

Hard caps

Two additional guards run before every payment regardless of mode:

Combined with the confirm: true argument the tool requires, this means the model needs (a) explicit user OK in chat, (b) amount ≤ cap, (c) recipient on allowlist if one exists, (d) all three live-mode env vars set, before a single wei moves.

Configuration reference

Supported chains

Why this exists

x402 standardised "402 Payment Required" semantics for AI agents but the official Coinbase facilitator only covers a few chains and assumes ERC-3009 token support — which excludes BNB USDT, Mantle USDT0, Injective USDT, and the chains where most stablecoin volume actually lives.

Q402 implements the same payer experience (single signature, $0 gas, instant settlement) on all 7 of those chains using EIP-7702 delegated execution, which works with any ERC-20. This MCP server makes that infrastructure addressable from Claude itself.

If you want to dig into how the wire protocol differs from x402, see Q402 docs.

Repository

Source code: https://github.com/bitgett/q402-mcp Issues / requests: https://github.com/bitgett/q402-mcp/issues

License

Apache-2.0 — see LICENSE.