agent-pay-mcp

@deepfirstsearch/agent-pay-mcp

あらゆる MCP エージェント（Claude Desktop、Claude Code、Cursor、…）が、ウェブページや API のレスポンスによるプロンプトインジェクションを受けた場合でも使いすぎることなく、Base 上の x402 API に USDC で支払える MCP サーバーです。

ベータ版、未監査です。 Base Sepolia を使うか、Base メインネットでは少額のみを利用してください。

モデルに提供されるツールは 3 つだけです。

ツール	モデルができること
paid_fetch(url, method?, body?, contentType?)	URL を取得します。402 Payment Required が返された場合、加盟店、価格、予算がお客様の設定と一致するときに限り、支払いが実行されます
check_price(url, method?, body?, contentType?)	無料：支払わずに、この URL に支払うとどうなるかを確認します。支払われる価格と受取人、または拒否する理由（payee_mismatch、price_changed、…）を表示します。署名は行われません。no_challenge は現時点で支払い条件が提示されていないことを意味し、ルートが無料という意味ではありません
list_merchants()	支払い可能なオリジン、価格、残りの予算を確認します
budget_status()	加盟店ごとの残り予算、期間の更新時期、ボールトの残高を確認します

モデルは、受取人、金額、ネットワーク、上限を選択できません。これらを指定する引数はありません。加盟店、価格の固定値、上限、支出計画は設定ファイルで指定し、キーは環境変数から取得します。レスポンスは、信頼できないデータであることを示すランダムなタグ付きフェンス内に返されます。オンチェーンでは、Agent Safe ボールトが、たとえこのマシンが侵害されても、署名済みの支払いごとおよび日ごとの上限を強制します。

セットアップ

1. 予算（オーナーが一度だけ実行）： ボールトを作成し、オーナー CLI で加盟店ごとの予算に署名します。npx @deepfirstsearch/agent-pay owner create-vault を実行し、続いて owner budget … を実行すると、intentId と、すぐに貼り付けて使える merchants[] エントリが出力されます。（ボールトがない場合は、vault、tranche、intentId を省略してください。各加盟店には AGENT_PAY_BURNER_SEED から導出された独自の支払元アドレスが割り当てられるので、USDC をご自身で入金してください。）
2. 設定： config.example.json をコピーして、必要事項を入力します。金額は USDC の十進数文字列で指定します。tranche は各 intent の trancheCap および maxPerTx 以下にしてください。
3. シークレット（環境変数のみ）：
   • AGENT_PAY_AGENT_KEY：intent のエージェントキー（ボールトを使用する場合のみ）。
   • AGENT_PAY_MCP_CONFIG：引数で指定しない場合の設定ファイルのパス。
   • AGENT_PAY_BURNER_SEED：支払元アドレスの導出に使った 32 バイトのシークレット。オーナーキーは絶対に使用しないでください。

Claude Code

claude mcp add agent-pay \
  -e AGENT_PAY_AGENT_KEY=0x… -e AGENT_PAY_BURNER_SEED=0x… \
  -- npx -y @deepfirstsearch/agent-pay-mcp /absolute/path/config.json

OpenClaw

npm install -g @deepfirstsearch/agent-pay-mcp   # or use "command":"npx","args":["-y","@deepfirstsearch/agent-pay-mcp","/absolute/path/config.json"]
openclaw mcp set agent-pay '{"command":"agent-pay-mcp","args":["/absolute/path/config.json"],"env":{"AGENT_PAY_AGENT_KEY":"${AGENT_PAY_AGENT_KEY}","AGENT_PAY_BURNER_SEED":"${AGENT_PAY_BURNER_SEED}"}}'
openclaw mcp probe agent-pay   # - agent-pay: 3 tools

詳しい手順については、OpenClaw ガイドをご覧ください。

Claude Desktop / Cursor

claude_desktop_config.json（Claude Desktop）または .cursor/mcp.json（Cursor）：

{
  "mcpServers": {
    "agent-pay": {
      "command": "npx",
      "args": ["-y", "@deepfirstsearch/agent-pay-mcp", "/absolute/path/config.json"],
      "env": { "AGENT_PAY_AGENT_KEY": "0x…", "AGENT_PAY_BURNER_SEED": "0x…" }
    }
  }
}

npm ではなくソースから実行する場合：cd integrations/mcp && npm ci && npm run build を実行し、コマンドとして node /path/to/integrations/mcp/dist/index.js を指定します。

検証済みの販売者ですぐに始める（Base メインネット）

verified プリセットには、実際の支払いで受取先と価格を確認済みの x402 販売者が35件含まれており、それぞれにガイドが付いています。これらは、scripts/verify-preset.ts によって支払いを行わずにライブで再確認され、一覧は src/presets.ts にあります。利用する販売者を選び、合計予算を設定します。

{
  "network": "eip155:8453",
  "preset": "verified",
  "presetOnly": ["https://netintel.dev"],
  "periodBudget": { "amount": "1.00", "hours": 24 }
}

preset.json として保存し、AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./preset.json でサーバーを起動します。起動時に、各販売者の支払い元アドレスが表示されます。そのアドレスに Base 上の USDC を少額送金してください（0.10 あれば数十回の呼び出しに対応できます）。次に、エージェントに販売者の URL に対して check_price と paid_fetch を実行するよう指示します。たとえば、https://netintel.dev/web/extract?url=https://www.sitemaps.org/protocol.html です。シードは保管しておいてください。同じシードを使うと、同じ支払い元アドレスが生成されます。

• 独自のエントリーが優先されます： merchants に同じオリジンの販売者を登録すると、プリセットのエントリーは無視されます。
• 販売者の選択： presetOnly を使うと、プリセットを指定したオリジンのみに限定できます。presetExclude では一部を除外できます。presetMaxSpend（デフォルトは "0.25"）では、プラン期間ごとの販売者あたりの上限を設定できます。
• 予算： プリセットを使う場合は periodBudget が必須です。これは、すべての販売者を合わせた合計額です。
• Vault： 現時点では、プリセットは自分で資金を入金する支払い元で動作します。Vault を使う場合は、代わりに intentId を指定して販売者を登録してください。

オフラインで試す（1分）

入金用のキーもチェーンも不要です。SDK のローカルモック販売者を起動し、サーバーを接続します。

npm install -g @deepfirstsearch/agent-pay-mcp   # or skip this and use `npx -y @deepfirstsearch/agent-pay-mcp` below
mkdir mock && cd mock && npm init -y >/dev/null && npm install @deepfirstsearch/agent-pay
node --input-type=module -e '
import { startMockServer } from "@deepfirstsearch/agent-pay/testing";
const m = await startMockServer({ "/data": { price: 10000n, payTo: "0x1111111111111111111111111111111111111111", body: "{\"ok\":true}" } });
console.log("origin:", m.url);'

起動したままにしておきます。offline.json では、表示されたオリジンを使います：{ "network": "eip155:84532", "merchants": [{ "origin": "<printed origin>", "payTo": "0x1111111111111111111111111111111111111111", "price": "0.01", "maxPerTx": "0.05", "maxSpend": "0.50" }] }。次に、AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) agent-pay-mcp ./offline.json でサーバーを起動します（グローバルインストールしない場合は、AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./offline.json）。または、MCP クライアントに追加して、<printed origin>/data に対して paid_fetch を呼び出します。モックは署名をローカルで検証するため、支払い元に資金は不要です。

5分で動作を確認（Base Sepolia）

sdk/examples/demo-merchant.ts は Base Sepolia 上の小規模な x402 API です。正規のルート（/premium、0.01 USDC）と、悪意のあるルート（/malicious：その 402 は攻撃者のアドレスへの 5 USDC の支払いを要求し、本文にはプロンプトインジェクションが含まれています）があります。

cd sdk && MERCHANT=0xYourMerchantAddress npx tsx examples/demo-merchant.ts

設定の販売者を、その payTo とともに http://127.0.0.1:4021 に指定し、エージェントに /premium と /malicious を取得するよう指示します。想定される結果：1つ目は支払いが行われ、オンチェーンで決済されます。2つ目は署名が行われる前に拒否されます（「payTo … is not the merchant's registered address」）。

設定リファレンス

フィールド	意味
network	eip155:84532（Base Sepolia）または eip155:8453（Base）
rpcUrl	そのネットワークのオプションの RPC URL（Vault へのチャージと残高の読み取りに使用）。デフォルトは viem のパブリック RPC です
vault, tranche	各マーチャントの支払者にチャージする Agent Safe Vault と、チャージ額
merchants[].origin, payTo	支払いが許可される相手と、支払い先として許可される唯一のアドレス
merchants[].intentId	このマーチャント用の、オーナー署名済み予算（インテント）です。owner budget の出力に表示されます。vault が設定されている場合、すべてのマーチャントで必須です
merchants[].label	list_merchants に表示される、任意の表示名（最大 80 文字）
merchants[].price, tolerancePct	1 回の呼び出しで想定される価格です。price × (1 + tolerance) を超える金額は拒否されます
merchants[].maxPerTx, maxSpend	1 回あたり、およびプラン期間内のマーチャントごとの上限額
merchants[].maxTimeoutSeconds	このマーチャントが要求できる認可時間の上限です。10～86400 秒（デフォルト 300 秒）。延長された時間が適用されるのは、このマーチャントのみです
merchants[].x402Versions	このマーチャントへの支払いに使用できる x402 のバージョン。デフォルトは [2] です。引き続き x402 v1 に対応しているマーチャント（例：Heurist Mesh）には [1, 2] を設定してください
confirmOnChain	デフォルトは true です。マーチャントのレシートが見つからないか読み取れない場合、再送信する代わりに、支払いが実行されたかを USDC にオンチェーンで（rpcUrl 経由で）問い合わせます。標準外のレシートを返すマーチャント（CoinMarketCap、JustaName、Glim）で必要です。この設定が使われるのは、その失敗経路のみです
planWindowHours	起動時にこのファイルからプランを確定し、期間ごとにこのファイルから更新します
periodBudget	期間内の全マーチャントを合計した予算：{ "amount": "1.00", "hours": 24 }
approvalAbove	これを超える支払いは拒否されます（このサーバーには、モデルがアクセスできない承認チャネルがありません）
sessionHasSensitiveData	エージェントがプライベートデータも読み取れる場合、すべての支払いに人間の承認が必要となるため（Rule of Two）、すべて拒否されます
auditLog	あらゆる判断を記録した、ハッシュチェーン付きの JSONL ログ
maxResponseChars	モデルに返すレスポンス本文の最大文字数（デフォルト 20000、最大 1000000）。これを超える本文は切り詰められ、その旨が示されます
allowPrivateNetwork	デフォルトは false です。true にすると、paid_fetch が http:// URL、およびこのファイルに登録されていないループバック、プライベート、リンクローカル、CGNAT ホストにアクセスできるようになります

不明なキーは拒否されるため、タイプミス（approvalabove）があると、上限を黙って無視するのではなく、サーバーが停止します。

0.2.0 以降、テスト済みのすべてのマーチャントで MCP 経由の動作が確認されています。v1 のマーチャント（Heurist Mesh）には x402Versions: [1, 2] を設定し、標準外のレシートを返すマーチャント（CoinMarketCap、JustaName、Glim）では confirmOnChain を有効のままにしてください。Vault を使用しない場合、起動時に各マーチャントの支払者アドレスが出力されるため、どのアドレスに入金すべきか確認できます。

支払いが拒否されると、Payment refused by policy: … というエラー結果が返されます。0.1.8 以降では、同梱の @deepfirstsearch/agent-pay が 0.8.0 以降の場合、拒否理由の安定したコードと対処方法がテキストに含まれます。例：Payment refused by policy [price_changed → ask the owner]: …（コードの一覧は SDK README の「Refusal codes」を参照してください）。ブロックにもコードが含まれます（Payment blocked [settlement_pending → …]: …。ほかに settled_not_delivered、rate_limited、kill_switch）。さらに resend_same という操作も示されます。この場合は、同じ URL に対して paid_fetch を呼び出してください。SDK は新たな認可に署名せず、同じ署名済み認可を再送信します。 paid_fetchは、モデルが要求した公開https URLを取得します。制限されるのは決済のみで、対象は設定に登録した加盟店です。未登録のオリジンからの402以外のレスポンスはデータとして返されます（信頼できないデータとしてフェンスで囲まれます）。そのため、モデルに渡すほかの取得ツールと同様に扱ってください。ループバック、プライベート、リンクローカル、またはCGNATアドレスに該当するホストや解決されるホスト、localhost名、プレーンなhttpは、設定に加盟店として登録されている場合、またはallowPrivateNetworkを設定している場合を除き拒否されます。リダイレクトは返されますが、追跡されません。ポリシーによる拒否以外のエラー（たとえば、メッセージにrpcUrlが含まれる可能性があるRPC障害）は、固定テキストとしてモデルに返されます。詳細はサーバーのstderrに出力されます。

開発

npm ci && npm run typecheck && npm test   # tests drive the server through an MCP client against a mock x402 merchant