x402 Universal Payer

@three-ws/mcp-bridge

オープンウェブ上のあらゆる x402 対応エンドポイントに支払える MCP サーバー。AI エージェントのためのユニバーサルな x402 支払い手段です。

クイックスタート · セキュリティ · ツール · 環境 · three.ws

---

オープンウェブ上のあらゆる x402 対応エンドポイントに支払いができる Model Context Protocol サーバーです。402 Payment Required を返す URL をエージェントに指定すると、ブリッジが署名、支払い、再試行を行い、レスポンスと決済レシートを返します。EVM の exact、EVM の batch-settlement、Solana の exact に対応し、いずれも厳格な支出上限で保護されます。また、Coinbase x402 Bazaar で見つかったサービスごとにツールを事前ロードするため、有料 API エコノミー全体がツール一覧に表示されます。

クイックスタート

Claude Code：

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

代わりに（または追加で）-e MCP_BRIDGE_EVM_PRIVATE_KEY=0x... を指定すると、Base やその他の EVM チェーンで支払えます。キーを少なくとも 1 つ設定する必要があります。

Claude Desktop（claude_desktop_config.json）または 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"
			}
		}
	}
}

クライアントを再起動し、「天気予報に Base で $0.01 支払って」のように依頼してください。モデルが対応する Bazaar ツール（または call_paid_endpoint）を選び、ブリッジが x402 経由で自動的に支払います。

セキュリティと支出の制御

このサーバーは秘密鍵を保持し、実際の USDC を支払います。 設定する前に、このセクションをお読みください。

• 残高の少ない専用ウォレットを使用してください。 MCP_BRIDGE_EVM_PRIVATE_KEY / MCP_BRIDGE_SVM_PRIVATE_KEY にメインウォレットを指定しないでください。エージェントに使わせてもよい金額だけを入金してください。
• 1 回あたりの上限。 MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC（デフォルトは 100000 = $0.10 USDC）を超える支払いは、ペイロードに署名する前に拒否されます。エラーにはネットワーク、アセット、上限が示されます。
• セッション全体の上限。 プロセスごとの累積支出は MCP_BRIDGE_MAX_TOTAL_ATOMIC（デフォルトは 1000000 = $1.00 USDC）で制限されます。これにより、ループするエージェントやプロンプトインジェクションを受けたエージェントによる損害を抑えられます。上限に達すると、再起動するまで以降のすべての支払いが中止されます。累積額はアトミックに確保されるため、並行する呼び出しによって上限を超えることはありません。
• 支払先の許可リスト。 MCP_BRIDGE_ALLOWED_PAYTO（カンマ区切りのアドレス）を設定すると、明示的に信頼していない受取人への支払いを拒否できます。
• SSRF ガード。 モデルが指定した URL でも Bazaar のリストから取得した URL でも、支払いが発生するすべての送信先 URL は、1 つのチェックポイントを通過します。そこで https のみを許可するポリシーを適用し、ホスト名を解決したうえで、解決されたアドレスのいずれかがプライベート、ループバック、リンクローカル（169.254.169.254 のクラウドメタデータを含む）、CGNAT、ULA、または未指定アドレスの場合、リクエストを拒否します。IP アドレスを直接指定したホストも直接検査します。リダイレクトは一切追跡しません（公開ホストが 3xx リダイレクトでブリッジを内部インフラへ誘導することはできません）。http:// は、明示的に MCP_BRIDGE_ALLOW_HTTP=1 を指定してオプトインした開発環境でのみ利用できます。
• ホストの許可リスト。 厳格モードにするには、MCP_BRIDGE_ALLOWED_HOSTS（カンマ区切りのホスト名）を設定してください。リストにあるホストにのみ支払えます。
• 入金上限。 バッチ決済チャネルへの入金は、サーバーの要求額にかかわらず、MCP_BRIDGE_MAX_DEPOSIT_ATOMIC（デフォルトは $5.00）で制限されます。
• 正確なアノテーション。 支払いを行うすべてのツールには readOnlyHint: false、idempotentHint: false、openWorldHint: true が設定されるため、MCP ホストは最も厳格な確認ポリシーを適用します。支払いを伴う呼び出しを再試行すると、新たな請求が発生します。

公開される機能

起動時にブリッジは以下を登録します。

ツール	機能
call_paid_endpoint	汎用フォールバック：任意の URL にアクセスし、402 が返された場合は自動で支払います。レスポンスと解析済みの決済情報を返します。
list_bazaar_tools	Bazaar で検出されたツールのキャッシュ済みリスト（名前、リソース、受け入れ可能な支払い条件）を返します。無料です。
refresh_bazaar	x402 Bazaar を再クエリし、再起動せずに動的ツールを再登録します。無料です。
paid_<derived> …	検出された Bazaar リソースごとに 1 つのツール（最大 MCP_BRIDGE_DISCOVER_LIMIT 個）を登録し、各エンドポイントのスキーマを使用します。

1 回あたりの上限を超える価格の条件しかないツールは検出時に除外されるため、モデルに支払い可能な価格を超えるツールが表示されることはありません。

ツールの注釈

各ツールには MCP の ToolAnnotations が設定されており、ホストは適切な確認ポリシーを適用できます。

• call_paid_endpoint とすべての動的な paid_* ツール：readOnlyHint: false、destructiveHint: false、idempotentHint: false、openWorldHint: true。実際の USDC を消費します — 呼び出しごとに支払いが決済され（MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC が上限）、再試行すると新たな請求が発生します。呼び出し元の状態を削除したり上書きしたりすることはないため、破壊的ではありません。
• list_bazaar_tools：readOnlyHint: true、idempotentHint: true、openWorldHint: false。プロセス内キャッシュの読み取りのみです。無料で、ネットワーク通信もありません。
• refresh_bazaar：readOnlyHint: false、destructiveHint: false、idempotentHint: false、openWorldHint: true。無料（支払いなし）ですが、ライブ Bazaar フィードから登録済みのツールセットを変更するため、繰り返し呼び出すと結果が異なる場合があります。

プレーンなオブジェクトであるツールの結果は、後方互換性のための JSON text ブロックと、型付きクライアント向けの structuredContent の両方で返されます。

支払いスキーム

購入側クライアントに登録される支払い経路：

• eip155:* → BatchSettlementEvmScheme（サーバーが提供する場合に優先。バウチャー方式で、呼び出しごとのガス代は不要）
• eip155:* → ExactEvmScheme（サーバーが scheme: "exact" を提供する場合に使用）
• solana:* および x402 v1 の Solana ネットワーク（solana、solana-devnet、solana-testnet）→ ExactSvmScheme / ExactSvmSchemeV1（広告された手数料支払者が連署する USDC SPL 送金）。registerExactSvmScheme() によって両方まとめて登録されます。v1 は、オープンな x402 Bazaar の大半が現在も使用するワイヤ形式です。販売者が両方を提供している場合、クライアントは常に v2 を優先します。支出上限フックは amount（v2）または maxAmountRequired（v1）のどちらも読み取るため、どちらも同じ方法で上限が適用されます。

バッチ決済チャネルの状態は ~/.x402-mcp-bridge/channels/client/ に保存されるため、クライアントを再起動しても次の呼び出し時に再入金する必要はありません。

環境

変数	必須	デフォルト	備考
MCP_BRIDGE_EVM_PRIVATE_KEY	EVM/SVM のいずれかが必須	—	0x で始まる 32 バイトの 16 進数。Base、Arbitrum などでの USDC 支払いに使用します。
MCP_BRIDGE_SVM_PRIVATE_KEY	EVM/SVM のいずれかが必須	—	base58 形式の 64 バイト秘密鍵（Phantom/solana-keygen 形式）、または 64 個の整数からなる JSON 配列。
MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC	いいえ	100000（小数点以下 6 桁の場合、USDC で $0.10）	1 回の呼び出しあたりの支出上限です。上限を超えると、明確な理由とともに支払いを中止します。
MCP_BRIDGE_MAX_TOTAL_ATOMIC	いいえ	1000000（USDC で $1.00）	セッション全体の累積支出上限です。上限に達すると、それ以降の支払いを中止します。
MCP_BRIDGE_ALLOWED_PAYTO	いいえ	—（すべての支払先）	許可する支払先のアドレスをカンマ区切りで指定します。設定すると、リストにない payTo アドレスへの支払いは拒否されます。
MCP_BRIDGE_ALLOWED_HOSTS	いいえ	—（すべてのパブリックホスト）	有料の送信リクエストで許可するホスト名をカンマ区切りで指定します。
MCP_BRIDGE_ALLOW_HTTP	いいえ	0	1 を設定すると、http:// の接続先を許可します。ローカル開発専用です。
MCP_BRIDGE_DISCOVER_LIMIT	いいえ	20	動的に登録する Bazaar ツールの最大数です。検出を無効にするには 0 を設定します。
MCP_BRIDGE_BAZAAR_URL	いいえ	https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources	セルフホストの Bazaar または代替の Bazaar を指定する場合に変更します。
MCP_BRIDGE_BATCH_DEPOSIT_MULTIPLIER	いいえ	5	バッチチャネルを開く際に、一度に入金するリクエスト金額の倍数です。
MCP_BRIDGE_MAX_DEPOSIT_ATOMIC	いいえ	5000000（USDC で $5.00）	チャネルの開設またはチャージごとの入金額の上限です。
X402_MCP_BRIDGE_CHANNELS_DIR	いいえ	~/.x402-mcp-bridge/channels	FileClientChannelStorage が使用するディレクトリを変更します。
RPC_URL_<chainId>	いいえ	viem のデフォルトのパブリック RPC	チェーンごとの RPC を指定します。例：RPC_URL_8453=https://mainnet.base.org。

MCP_BRIDGE_* のキー変数は、すでに設定されている場合、EVM_PRIVATE_KEY／SVM_PRIVATE_KEY にもフォールバックします。

支出上限の動作

支払い前フックは、選択された accepts エントリを検査し、金額が 1 回あたりの上限を超える場合、支払先が許可リストにない場合、またはセッション全体の上限を超える場合に、ペイロードの作成を中止します。その後、ツールの結果には、ネットワーク、アセット、超過した上限を示す明確なエラーメッセージが含まれます。これにより、モデルは上限の引き上げを依頼するかどうかを判断できます。

クライアントを使わずに検査する

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

インスペクターは stdio 経由で接続し、静的ツール（call_paid_endpoint、list_bazaar_tools、refresh_bazaar）と、検出された Bazaar エントリーごとに 1 つの動的ツールを一覧表示します。

プログラムからの利用

任意の Node モジュールから、同じバイヤークライアントを通じて x402 エンドポイントを利用できます。

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');

同じ支出上限、SSRF ガード、チャネル保存ルールが適用されます。アイドル状態のバッチチャネルは、@x402 SDK の client.refund(resourceUrl, { amount }) を使って帯域外で返金できます。

テスト

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

このハーメチックテストスイートは、プロセス内で使い捨てのキーペアを生成するため、実際のキーや資金は一切使用されません。

ライセンス

All rights reserved. LICENSE を参照してください。