q402-mcp

@quackai/q402-mcp

Q402 用 MCP サーバーです。12 の EVM チェーン（Robinhood Chain 上の USDG を含む）で、ガス代不要の USDC、USDT、RLUSD、USDG 決済を利用できます。Claude（Desktop / Code）、OpenAI Codex CLI、その他すべての Model Context Protocol クライアントから呼び出せます。

無料トライアルをご利用いただけます。BNB Chain + Base（USDC + USDT）でガス代不要の取引を500回、カード不要です。ウォレットで1回署名するだけです：https://q402.quackai.ai。 期間限定ボーナス： 2026-08-21~08-28 UTC+9 の期間中、Mantle（USDC + USDT）もトライアルキーで利用できます。

トライアル対象範囲のポリシー： 無料トライアルプログラムで発行された API キー（plan: "trial"）は、BNB Chain（USDC/USDT のガス代不要決済）および Base（USDC/USDT のガス代不要決済）を恒久的なチェーンとして利用できます。Avalanche のトライアルは終了しました — avax を利用するにはマルチチェーンキーをご使用ください。期間限定の 2026-08-21~08-28 UTC+9 の間は、Mantle（USDC/USDT のガス代不要決済）も利用できます。サーバー側で時間が判定され、期間外は TRIAL_BNB_ONLY が返されます。有料 API キーでは、常に12チェーンすべてを利用できます。

任意の MCP クライアントから、12 の EVM チェーンでステーブルコイン決済の見積もり → ルーティング →（任意で）決済を行えます。受取人は全額を受け取り、送信者は Q402 の EIP-7702 リレイヤーによりガス代が $0 になります。

クイックスタート

1. サーバーをクライアントに登録します（クライアントごとに1行）。
2. エージェントに 「Q402 をセットアップして」 と伝えます。エージェントが q402_doctor を実行し、~/.q402/mcp.env を作成して、キーの貼り付けを案内します。

1. サーバーを登録する

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

Claude Code（claude バイナリを使う CLI）と Claude Desktop（macOS / Windows アプリ）は別の製品です。claude mcp add コマンドは CLI にのみ存在します。Desktop アプリでは上記の JSON 設定が必要です。

シークレットはこの設定には含まれません。サーバーは ~/.q402/mcp.env から読み込みます（AWS / Stripe / gh CLI と同じ方式です）。

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

クライアントを再起動し、次のように尋ねます。> 「Q402 をセットアップして」

エージェントが q402_doctor を実行します。初回インストール時は、次の処理を行います。

1. ~/.q402/mcp.env（プレースホルダー）を作成します
2. エディターでファイルを開きます
3. API キーと署名パスを、チャットではなくファイルに貼り付ける手順を案内します
4. 再起動し、q402_doctor を再実行して確認します

キーをチャットに貼り付けないでください。 ローカルモードではお使いのマシン上で署名するため、キーがデバイスの外に出ることはありません。モード C（サーバー管理）では、クライアントに PK は不要です。

署名モードを選択

複数のモードが設定されている場合、q402_pay は使用するモードを尋ねます。選択肢：walletMode = "agentic-server" \| "agentic-local" \| "eoa"。

手動セットアップ（AI を使用しない場合）

以下のテンプレートを使って、~/.q402/mcp.env を自分で作成します。API キーと署名パスの両方を設定した場合にのみライブモードに切り替わるため、テンプレートをそのまま保存すればサンドボックスのままです。実際のキーが設定されていても、Q402_ENABLE_REAL_PAYMENTS=0 にするとサンドボックスが強制されます。

# ~/.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

次に chmod 600 ~/.q402/mcp.env を実行し（Unix）、クライアントを再起動します。これで設定は完了です。EIP-7702 に関する影響にご注意ください。 チェーン上で初めて実際の支払いを行うと、MetaMask / OKX でウォレットに「スマートアカウント」と表示されます。これは Q402 がガス代不要の決済に使用する委任で、いつでも q402_clear_delegation で元に戻せます。x402 ユーザーへの重要事項： EIP-7702 が古い実装に委任されている場合、q402_clear_delegation を呼び出すまで q402_x402_fetch で x402 の支払いに署名できません（Base ではガス代不要で元に戻せます。次の q402_pay で自動的に再委任されます）。現在の ERC-1271 対応実装に委任されたウォレットは通常どおり動作します。

上級者向け - 環境変数の明示的な注入

ファイルを使わずに環境変数を自分で注入したい場合（たとえば、Codex の env_vars 許可リスト、シークレット管理ツール、またはシェルのエクスポートを使用する場合）、サーバーは process.env にフォールバックします。競合する場合は、ファイル内の値より process.env の値が優先されます。そのため、既存のシェルでのエクスポート設定は変更なしで引き続き使えます。

[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",
]

セットアップせずに試す

q402_quote は設定なしで動作します。API キー、秘密鍵、環境変数ファイルは不要です。次のように尋ねてください。

「12 の Q402 チェーンすべてで、vitalik.eth に 50 USDC を送金する場合のガス代を比較して。」

Q402_RELAY_BASE_URL はリレーノードのエンドポイントを上書きします。セルフホスト型の Q402 デプロイメント、または標準環境以外で実行する場合は、明示的に設定してください。

公開されるツール

機能別に分類された 49 個のツールです。 デフォルトでは読み取り専用です。ライブモードには、有効な API キー、署名パス、および Q402_ENABLE_REAL_PAYMENTS=1 が必要です。live mode と記された行のツールは資金を移動するため、チャット内で明示的な確認が必要です。

注意：q402_pay では 0x アドレスが必要です。サーバー側では ENS を解決しないため、先にクライアント側で解決してください。 チェーンごとの Gas Tank 残高とすべての TX 履歴は、ダッシュボードで確認できます（ウォレット署名のみ）。

x402 の送金（q402_x402_fetch）

q402_x402_fetch は汎用 x402 クライアントです。あらゆる URL を取得し、HTTP 402（支払いが必要）レスポンスを自動的に処理します。サーバーが 402 以外のステータスを返した場合、レスポンスは変更されずに渡されるため、通常のフェッチツールとしても機能します。

解決する課題。 一部の API やコンテンツエンドポイントでは、リクエストごとに課金するために x402 プロトコルを使用します。このような URL にアクセスしたエージェントは、機械可読な支払い要件を含む HTTP 402 レスポンスを受け取ります。q402_x402_fetch はその要件を読み取り、支払い方法を検証し、Base USDC に対する EIP-3009 TransferWithAuthorization に署名して、base64 の JSON ペイロードとしてエンコードし、リクエストを再試行します。x402 v2 サーバーでは PAYMENT-SIGNATURE を、レガシー v1 サーバーでは X-PAYMENT を使用します。これらすべてを 1 回の呼び出しで行います。

サポート対象。 scheme=exact + network=base（CAIP-2 eip155:8453。base-mainnet も受け付けます）+ Base USDC のみです。それ以外のスキーム、ネットワーク、資産は明示的に拒否され、署名は生成されません。

ガード（3 層）。

2 段階の同意フロー：最初の呼び出し（consentToken なし）では、正確な金額と受取人を示すプレビューおよび consentToken とともに needs_confirmation が返されます。見積もりをそのままユーザーに提示し、支払いを確認する次の独立したメッセージを待ってください。 その後に限り、同じ引数に consentToken を加えて再度呼び出します。トークンは1 回限り使用可能で、約 120 秒で期限切れになります。また、発行から 2 秒以内に使用された場合は拒否されます（同一ターン内の二重呼び出し防止のための時間しきい値であり、ユーザーの確認を証明するものではありません）。ユーザーから別個の確認メッセージがない限り、同じ会話ターン内で再度呼び出してはいけません。

結果の状態 — ユーザーに要約する前に確認してください。

最小限の動作例。

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "confirm": true
}

エンドポイントが 402 を返すと、ツールは needs_confirmation と consentToken を返します。見積もりを一字一句そのままユーザーに提示し、ユーザーから次の独立したメッセージが届くまで待ちます。支払いを承認するには、同じ引数に consentToken を加えて再度呼び出します。トークンは一度のみ使用でき、有効期限は約 120 秒です。

要件。 Q402_ENABLE_REAL_PAYMENTS=1 と、ローカル署名キー（Q402_AGENTIC_PRIVATE_KEY または Q402_PRIVATE_KEY）が必要です。署名済みの認可情報は販売者のファシリテーターエンドポイントに直接送信されます。この経路では Q402 リレーは関与しません。

前提条件 — 委任の確認。 このウォレットで以前に q402_pay を呼び出したことがある場合、EIP-7702 によって委任されている可能性があります（MetaMask / OKX では「スマートアカウント」と表示されます）。古い実装に委任されている場合、q402_x402_fetch は失敗します。現在の ERC-1271 対応実装に委任されているウォレットは、通常どおり動作します。復旧するには、q402_clear_delegation を呼び出します（Base ではガスレスで、元に戻せます）。委任を解除すると、q402_x402_fetch が再び動作します。次回の q402_pay では、自動的に再委任されます。

ガバナンス分析（q402_governance_analyze）

q402_governance_analyze は Snapshot のガバナンス提案を分析し、投票の推奨、5 つの評価軸のスコア、およびその理由を返します。Base 上で x402 を介して、1 回の呼び出しにつき $0.05 USDC です。

入力パラメーター。

言語に応じた結果。 language: "zh" を設定すると、投票の推奨、評価軸名、評価、および理由のテキストがすべて中国語で提示され、ユーザーに英語の列挙値は表示されません。

サンドボックスモードとライブモード

デフォルトのサンドボックス: q402_pay は、success: false および sandbox: true を伴う偽の txHash を返します。資金もクォータも消費されません。

ライブモード = (a) ライブ API キー（q402_live_*）、(b) 署名経路（A / B / C）、(c) Q402_ENABLE_REAL_PAYMENTS=1。ライブフラグのデフォルトは 1 です。ゲートが切り替わるのは、他の 2 つの条件も満たされた場合のみです。実際のキーを使用していてもサンドボックスモードを強制するには、0 に設定します。

テンプレート q402_doctor は ~/.q402/mcp.env に書き込みます。

# ── API key - fill ONE (or both for auto-routing) ──
# Auto-routing (same for q402_pay AND q402_batch_pay):
#   chain="bnb" or "base" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
#   anything else                                    → Multichain (paid 12-chain)
# Batch ambiguity: 6+ recipient BNB/Base batch with Trial set returns
#   status="ambiguous" instead of executing - agent asks user to pick.
# Override per call with keyScope: "auto" | "trial" | "multichain".
Q402_TRIAL_API_KEY=                # BNB + Base sponsored Trial key (from /event; Avalanche trial ended)
Q402_MULTICHAIN_API_KEY=           # paid 12-chain key (per-chain Gas Tank)

# ── Signing path - pick ONE of Mode A / B / C ──
Q402_PRIVATE_KEY=                  # Mode A: real EOA pk (0x + 64 hex)
Q402_AGENTIC_PRIVATE_KEY=          # Mode B: exported Agent Wallet pk (from dashboard)
# Mode C: leave both PK lines blank. A Trial key enables one-shot Mode C
# payments; Multichain key required for recurring, batch, and bridge/OFT.
# Q402 signs with the server-managed Agent Wallet. Optionally:
# Q402_AGENT_WALLET_ADDRESS=0x...   # pin one of your wallets when you have multiple

# Live mode switch:
#   0 = sandbox (test mode, no funds move - every q402_pay returns a fake hash)
#   1 = real on-chain payments (live mode)
# Default 1. Safe because the gate only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated. Empty values
# fail the gate, so partial setups stay in sandbox with a hint.
Q402_ENABLE_REAL_PAYMENTS=1

# Pre-check trust-check (live mode). Triggers for first-time counterparties or
# payments >= $1. Fee: $0.02 per check; cached 7 days. Never blocks the main tx.
# Set Q402_DISABLE_PRECHECK=1 to opt out.

解決されたスコープで不足している項目がある場合は、設定すべき項目を示すヒントとともに、自動的にサンドボックスへフォールバックします。

サンドボックスの応答には、success: false、sandbox: true、mode: "sandbox"、method: "sandbox" に加え、理由を説明する setupHint が含まれます。下流の要約が成功したと誤って主張できないよう、4 つのシグナルで示します。

ハード上限

2段階の consentToken とライブモード環境変数を組み合わせることで、ステーブルコインの支払いには、別のメッセージでユーザーが承認したプレビュー、上限以下の金額、許可された受取人、3つすべてのライブ環境変数が必要になります。consent token は1回限り有効で、有効期限は約120秒です。発行から2秒以内に使用すると、同一ラウンドでの二重呼び出しを防ぐゲートが作動します（これはしきい値であり、人間による確認を保証するものではありません）。Q（QuackAI）は上限の対象外です（独自トークンのため）。ただし、プレビュー、受取人の許可リスト、ライブモード環境変数は引き続き適用されます。

設定リファレンス

対応チェーン

これが必要な理由

AI エージェントはソフトウェアのデフォルトのインターフェースになりつつありますが、資金を動かす必要が生じた途端、スタックは機能しなくなります。ガストークンの保有、すべてのトランザクションへの署名、多数のチェーンにまたがるウォレットの管理が必要になるためです。エージェントが自律的に動作することを想定する場合、こうした仕組みでは拡張できません。

Q402 は、そのギャップを埋める決済レイヤーです。単一の署名プリミティブ（EIP-712 + EIP-7702）で、12 の EVM チェーンにわたるガス代不要のステーブルコイン決済を実行し、すべてのトランザクションに ECDSA 署名付き Trust Receipt を発行します。MCP パッケージはこの機能を Claude、Codex、Cursor、Cline 内で利用できるようにします。エージェントは自然言語のプロンプトから、決済の見積もり、送金、一括処理、監査を行えます。

単一送金と複数の受取先への一括送金は、すでに利用できます。次のレイヤーとなる定期支払い、条件付き実行、ポリシーで制御されたトレジャリーの自動化も、同じプリミティブを異なる形で組み合わせたものです。エージェントが実際の予算を管理し、相互に決済し、人が手動で開始しなくてもワークフロー内で価値を移動できる未来に向けて開発を進めています。

フック - プログラム可能な決済ポリシー

Q402 Hooks 1.0 は、決済のライフサイクルにルールを適用するポリシーエンジンです。OFAC コンプライアンス審査、支出上限と受取先の許可リスト、ERC-8004 による評判のゲーティング、Chainlink オラクルを使った条件付き決済（「BTC ≥ $80k の場合のみ」）、複数の受取人への自動分割に対応します。また、高額決済には承認が必要なソフトブロックを適用できます（202 approval_required を返します。呼び出し元は別の手段で再送信します。v1 では保留状態は保存されません）。Uniswap v4 が DEX の流動性にプログラム可能なフックを導入したのに対し、Q402 は AI エージェントの決済にフックを導入します。

開発者向けリファレンス：docs/HOOKS.md - ライフサイクル、Hook コントラクト、リリース済みの各フックと設定および例。

Base でのエスクロー: docs/ESCROW-VS-INSTANT.md - エージェント向けの即時決済とエスクロー決済の選択ガイド。docs/ESCROW-BASE-DEPLOY-RUNBOOK.md - Base メインネットへの Vault デプロイに関するエンジニアリング向け手順書（人間が操作するものであり、エージェント向けではありません）。

リポジトリ

ソースコード：https://github.com/quackai-org/q402-mcp
イシュー / リクエスト：https://github.com/quackai-org/q402-mcp/issues

ライセンス

Apache-2.0 - LICENSE を参照してください。