mcp-x402-accept

@cryptoapis-io/mcp-x402-accept

すでに稼働している MCP サーバーの前に x402 のペイウォールを設置し、サーバーのコードを一行も変更せずに、AI エージェントからツール呼び出しごとに料金を請求できます。

agent  →  mcp-x402-accept (your process)  →  your existing MCP server

このプロキシは、エージェントに対しては MCP サーバーとして、あなたのサーバーに対しては MCP クライアントとして動作します。サーバーが公開するすべてのツールをミラーリングし、料金を設定したツールにはペイウォールを設け、それ以外のツールは無料でそのまま通します。

どのような場合に使うか（また、使わない場合）

状況	使用するもの
MCP サーバー（Node/TS）を編集できる	x402-merchant-sdk/mcp — ハンドラーの前後に3行追加するだけで、データパスには何も加わりません
編集できない — サードパーティ製、クローズドソース、または Node 製ではない	このプロキシ

サーバーを編集できる場合は、代わりにそちらを使ってください。よりシンプルで、構成要素も確実に少なくなります。このパッケージは、それができない場合のためにあります。

セルフホスト限定の理由

このプロセスを実行するのはあなたです。私たちが実行することはなく、ホスト型バージョンも提供していません。

これは既定の設定ではなく、意図的な製品上の判断です。プロキシはエージェントとあなたのサーバーの間に位置するため、ホスト型にすると、CryptoAPIs が上流サーバーの認証情報を預かり、ツールの引数と結果が平文で通過する経路に入り、あなた自身の収益に対する稼働時間まで保証することになります。製品がツール呼び出しを通じて流れるデータそのものである事業者に、これを求めるのは妥当ではありません。セルフホストにすれば、その問いに答えるのではなく、問い自体をなくせます。

構造上、次のことが保証されます。

• ツールの引数と結果は、プロキシからは内容を読み取れません。読み取るのはツールの名前（料金が設定されているか）と _meta["x402/payment"]（支払い済みか）だけで、それ以外は何も読み取りません。解析、ログ記録、バッファリング、キャッシュは一切行いません。
• 上流の認証情報は、あなた自身の環境変数として、あなた自身のプロセス内に保持されます。
• 外部への呼び出し先は、支払いそのものを /verify および /settle で処理する CryptoAPIs facilitator だけです。

インストール

npm install -g @cryptoapis-io/mcp-x402-accept

設定

{
  "upstream": {
    "transport": "stdio",
    "command": "node",
    "args": ["/path/to/your-mcp-server.js"],
    "env": { "YOUR_UPSTREAM_TOKEN": "${YOUR_UPSTREAM_TOKEN}" }
  },

  "apiKey": "${CRYPTOAPIS_API_KEY}",
  "payTo":  "0xYourReceivingAddress",

  // Only these are charged for. Everything else your server exposes stays FREE.
  "pricedTools": {
    "premium_data": {
      "network": "eip155:8453",
      "asset":   "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount":  "10000"
    }
  }
}

${VAR} は環境変数から読み取るため、設定ファイル自体にシークレットは含まれず、安全にコミットできます。

amount は最小単位で指定します。USDC は小数点以下6桁なので、"10000" は $0.01 です。ここで最も起きやすい間違いは、値を10^6倍間違えることです。

stdio ではなく HTTP の上流を使う場合：

"upstream": {
  "transport": "http",
  "url": "https://your-server.example.com/mcp",
  "headers": { "Authorization": "Bearer ${YOUR_UPSTREAM_TOKEN}" }
}

1つのツールで複数のアセットやネットワークを受け入れるには、配列を渡してください。エージェントはその中から1つを選びます。GET https://ai.cryptoapis.io/x402/merchant/supported が一覧に掲載しているもの（公開されており、キー不要）のみを提示してください。それ以外は提示されても、/verify で拒否されます。

実行

cryptoapis-mcp-x402-accept --config ./x402-accept.config.json

その後、サーバーの代わりにプロキシをエージェントに指定します。Claude Code の場合：

claude mcp add my-paid-tools -- cryptoapis-mcp-x402-accept --config /abs/path/to/config.json

起動時にすべて検証されます。設定、上流への接続、料金を設定したツールが実際に上流に存在するかが確認されます。ツール名の入力ミスは、見過ごされることなく致命的なエラーになります。そうしないと、ツールにペイウォールがあると思い込んでいる間に、実際には無料で提供され続けるおそれがあるためです。

エージェントから見た動作

手順	結果
料金設定済みツールへの未払いの呼び出し	structuredContent と content[0].text の両方に PaymentRequired を含む isError: true が返されます
エージェントが支払う	ローカルで署名し、ペイロードを _meta["x402/payment"] に含めて再試行します（生の JSON で、base64 ではありません）
支払い済みの呼び出し	レシートが _meta["x402/payment-response"] に含まれた、ツールの本来の結果が返されます
料金未設定のツールへの呼び出し	無料でそのまま転送されます

支払いが確定するまで、サーバーが呼び出されることはありません。 プロキシは料金を請求してから転送します。先に転送して後から請求することはありません。未払いの呼び出しがサーバーに到達することはないため、無料で処理させることもできません。

料金設定済みのツールは、説明に [paid: x402] を表示するため、エージェントは呼び出す前に料金を把握できます。拒否されて初めて料金を知るエージェントは、すでに不要な往復を1回行っています。

支払い方法

エージェントは @cryptoapis-io/mcp-x402-pay を使って支払うことができます。コードから支払う場合は、@cryptoapis-io/x402-buyer-sdk/mcp を使います。

注意事項

• X402_FACILITATOR 機能が有効な CryptoAPIs API キーが必要です。
• "settle": false は決済を確定せずに検証します。接続設定中には便利ですが、あくまで参考情報です。購入者が支払えることを証明しただけで、実際に支払ったことを証明するものではありません。本番環境では絶対に使用しないでください。
• 実際に課金する前に、Base Sepolia（eip155:84532）でエンドツーエンドのテストを実施してください。
• x402 v2 MCP トランスポート（仕様）を実装しており、マーチャント SDK と実装を共有しています。そのため、仕様の修正は両方に反映されます。