@quackai/q402-mcp

MCP server for Q402 - gasless USDC, USDT, RLUSD, and USDG payments across 12 EVM chains (USDG on Robinhood Chain), callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.

Free trial available. 500 gasless transactions on BNB Chain + Base (USDC + USDT), no card. One wallet signature: https://q402.quackai.ai. Limited-time bonus: Mantle (USDC + USDT) is also covered by trial keys during 2026-08-21~08-28 UTC+9.

Trial-scope policy: API keys minted under the free-trial program (plan: "trial") settle on BNB Chain (USDC/USDT gasless) and Base (USDC/USDT gasless) as permanent chains. Avalanche trial has ended — use a Multichain key for avax. Mantle (USDC/USDT gasless) is covered during the limited-time window 2026-08-21~08-28 UTC+9 — server-side time enforcement, returns TRIAL_BNB_ONLY outside the window. Paid API keys see the full 12-chain matrix at all times.

Quote → route → (optional) settle stablecoin payments across 12 EVM chains, from any MCP client. Recipient gets the full amount; sender pays $0 gas via Q402's EIP-7702 relayer.

Quick start

1. Register the server with your client (one-line per client).
2. Say "Set up Q402" to your agent. It runs q402_doctor → creates ~/.q402/mcp.env → walks you through pasting keys.

1. Register the server

mcp_servers:
  q402:
    command: "npx"
    args: ["-y", "@quackai/q402-mcp"]
    enabled: true

Claude Code (the CLI, claude binary) and Claude Desktop (the macOS / Windows app) are different products. The claude mcp add command only exists in the CLI; the Desktop app needs the JSON config above.

Secrets are NOT in this config. The server reads them from ~/.q402/mcp.env (same pattern as AWS / Stripe / gh CLIs).

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]

2. First-time setup

Restart your client, ask: > "Set up Q402"

The agent runs q402_doctor. On first install:

1. Creates ~/.q402/mcp.env (placeholders)
2. Opens it in your editor
3. Walks you through pasting an API key + a signing path into the file, not into chat
4. Restart + re-run q402_doctor to verify

Keys never paste into chat. Local modes sign on your machine; the key never leaves the device. Mode C (server-managed) needs no PK on the client.

Pick a signing mode

When more than one mode is set, q402_pay asks the user which to use. Picker: walletMode = "agentic-server" \| "agentic-local" \| "eoa".

Manual setup (no AI)

Create ~/.q402/mcp.env yourself with the template below. Live mode only flips when an API key + a signing path are populated, so saving the template as-is stays in sandbox. Q402_ENABLE_REAL_PAYMENTS=0 forces sandbox even with real keys.

# ~/.q402/mcp.env

# ── API key (pick one or both for auto-routing) ──
Q402_TRIAL_API_KEY=          # Free Trial, BNB (permanent) + Base (permanent) + Mantle limited-time (from /event)
Q402_MULTICHAIN_API_KEY=     # Paid Multichain, all 12 chains (from /payment)

# ── Signing path - pick ONE of Mode A / B / C ──
# Mode A: your MetaMask EOA's hex private key.
# Hardware wallets (Ledger / Trezor) are NOT supported here - Q402
# needs a raw hex key it can sign EIP-7702 type-4 authorizations with.
Q402_PRIVATE_KEY=

# Mode B: exported Agent Wallet pk from the dashboard. Keeps your
# MetaMask untouched. Get it at:
#   https://q402.quackai.ai/dashboard → Agent tab → Export
Q402_AGENTIC_PRIVATE_KEY=

# Mode C: no PK needed. A Trial key also enables Mode C one-shot payments;
# leave both PK lines blank. Q402 signs with the server-managed Agent Wallet.
# Multichain key required for recurring, Mode C batch, and bridge/OFT.
# Optional: pin one of your Agent Wallets when you have multiple (max 10).
# Q402_AGENT_WALLET_ADDRESS=0x...

# Live mode switch:
#   0 = sandbox (test mode, no funds move)
#   1 = real on-chain payments
# Default 1 - safe because mode only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated above.
Q402_ENABLE_REAL_PAYMENTS=1

# Default Q402 deployment. Only change for self-hosted.
Q402_RELAY_BASE_URL=https://q402.quackai.ai/api

# Safety guards (max-amount ships uncommented at $200; lower for tighter caps):
Q402_MAX_AMOUNT_PER_CALL=200
# Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...

# Pre-check (automatic trust-check before outgoing payments in live mode).
# Triggers when paying a first-time counterparty OR amount >= $1.
# Fee: $0.02 per check; verdict cached 7 days (no repeat charge within TTL).
# Set to 1 to disable pre-check entirely (even first-time / large-amount pays).
# Q402_DISABLE_PRECHECK=0

Then chmod 600 ~/.q402/mcp.env (Unix) and restart your client. That's the full configuration. Heads up on the EIP-7702 side effect: after your first live payment on a chain, your wallet will show 'Smart account' in MetaMask / OKX - that's the delegation Q402 uses for gasless settlement, reversible anytime via q402_clear_delegation. Important for x402 users: after EIP-7702 delegation is active, q402_x402_fetch cannot sign x402 payments until you call q402_clear_delegation (gasless on Base, reversible — the next q402_pay re-delegates automatically).

Advanced - explicit env injection

If you'd rather skip the file and inject env vars yourself (e.g. via Codex env_vars allow-list, a secrets manager, or shell exports), the server falls through to process.env - and process.env wins over file values on conflicts. So existing shell-export setups keep working unchanged.

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]
startup_timeout_sec = 20.0
env_vars = [
  "Q402_TRIAL_API_KEY",
  "Q402_MULTICHAIN_API_KEY",
  "Q402_PRIVATE_KEY",
  "Q402_AGENTIC_PRIVATE_KEY",
  "Q402_AGENT_WALLET_ADDRESS",
  "Q402_ENABLE_REAL_PAYMENTS",
  "Q402_RELAY_BASE_URL",
]

Try it without any setup

q402_quote works with zero configuration - no API key, no private key, no env file. Ask:

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

Q402_RELAY_BASE_URL overrides the relay endpoint. Set it explicitly when running against a self-hosted Q402 deployment or a non-canonical environment.

Tools exposed

47 tools, grouped by capability. Read-only by default; live mode needs a live API key, a signing path, and Q402_ENABLE_REAL_PAYMENTS=1. Rows marked live mode move funds and need an explicit in-chat confirmation.