Agentpay Mcp

AgentPay MCP

AgentPay MCP は、x402 決済とウォレット操作のための stdio Model Context Protocol サーバーです。Agent Wallet SDK の関数を MCP ツールとして公開し、呼び出し元が管理する署名キーをローカルプロセス環境から読み込みます。

現在の npm パッケージは agentpay-mcp v5.0.0 です。

資金なしで開始する

ウォレットの認証情報を読み込まずに、インストール済みコマンドを確認します。

npx -y agentpay-mcp --version
npx -y agentpay-mcp --help

資金なしで、許可・承認必須・ブロックの各ポリシー結果を検証するには、 AgentPay Wallet Starter を使用してください。

MCP クライアントの設定

ウォレットツールは次の環境変数を読み込みます。

変数	ウォレットツールで必須	意味
AGENT_PRIVATE_KEY	はい	ローカルのホットウォレット署名キー
AGENT_WALLET_ADDRESS	はい	デプロイ済みの AgentAccountV2 アドレス
CHAIN_ID	いいえ	8453 または 84532。デフォルトは Base メインネット
RPC_URL	いいえ	呼び出し元が選択する Base RPC エンドポイント
FACTORY_ADDRESS	デプロイ時	ウォレットファクトリーのアドレス
NFT_CONTRACT_ADDRESS	デプロイ時	ウォレットに紐付けられたトークンコントラクト
SESSION_TTL_SECONDS	いいえ	ローカルセッションの有効期間（秒）

オペレーター向け安全性変数です。サーバー環境からのみ読み込まれ、 MCP 経由では変更できません。

変数	デフォルト	意味
AGENTPAY_POLICY_DAILY_LIMIT_ETH	未設定	オペレーターが設定する24時間のローリング上限（ETH 相当）
AGENTPAY_POLICY_PER_TX_CAP_ETH	未設定	オペレーターが設定するトランザクションごとの上限（ETH 相当）
AGENTPAY_POLICY_ALLOWED_RECIPIENTS	未設定	オペレーターが設定する、カンマ区切りの受取先許可リスト
AGENTPAY_ALLOW_UNPOLICED_SPEND	オフ	1 を指定すると、オペレーターポリシーがなくてもオンチェーン上限のみに依存して資金移動を許可します
AGENTPAY_X402_MAX_PAYMENT	未設定	各呼び出しの x402 上限に加えて適用される USDC の上限です。設定中は USDC 以外の x402 決済を拒否します
AGENTPAY_STATE_DIR	未設定	fsync される支出意図ジャーナルのディレクトリです。ロックとキー付きの決済記録は再起動後も保持され、ジャーナルは稼働中の状態に合わせて自動的に圧縮されます。一度にこのディレクトリを使用できるプロセスは1つです（spend-intents.lock）。ジャーナルを読み取れない場合、fsync できない場合、または別の稼働中プロセスがディレクトリを使用している場合は、資金移動を拒否します
AGENTPAY_ALLOWED_PRIVATE_HOSTS	未設定	外向きリクエストでプライベートアドレスへのアクセスを許可する、カンマ区切りのホスト
AGENTPAY_ALLOW_PRIVATE_NETWORK	オフ	開発専用：プライベート宛先と平文の http を許可します

少なくとも1つの AGENTPAY_POLICY_* 変数、または AGENTPAY_ALLOW_UNPOLICED_SPEND=1 が設定されていない場合、資金を移動するすべてのツールは支出を拒否します。

MCP 設定の例：

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "agentpay-mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "<secret-reference-or-local-key>",
        "AGENT_WALLET_ADDRESS": "0x<deployed-wallet-address>",
        "CHAIN_ID": "84532",
        "AGENTPAY_POLICY_PER_TX_CAP_ETH": "0.01",
        "AGENTPAY_POLICY_DAILY_LIMIT_ETH": "0.1",
        "AGENTPAY_X402_MAX_PAYMENT": "1",
        "AGENTPAY_STATE_DIR": "<writable-private-directory>"
      }
    }
  }
}

実際の署名キーをコミットしないでください。利用できる場合は、クライアントまたはオペレーティングシステムのシークレット管理機能を使用してください。Base メインネットを使う前に、Base Sepolia で開始してください。

ツールグループ

src/index.ts のツールレジストリは、次のグループを公開します。

グループ	例
ウォレット	deploy_wallet、get_wallet_info、queue_approval
決済	send_payment、x402_quote、x402_pay、x402 セッションツール
ポリシー	set_spend_policy、check_budget、OTel 予算ツール
トークン	検索、カスタムトークンの登録、残高、送金
実行	スワップ、USDC ブリッジ、相互ステークのエスクロー
信頼	ERC-8004 の ID、レピュテーション、UAID の検証
履歴	ウォレットコントラクトのイベントを対象とする get_transaction_history

ツールのスキーマとハンドラーは src/tools/ の下にあります。

セキュリティ境界

これらの境界は機能一覧よりも重要です。

• サーバーは AGENT_PRIVATE_KEY をローカルの Node.js プロセスに読み込み、署名には viem を使用します。プロセス、環境変数、MCP クライアントの設定を保護してください。
• 支出ポリシーはデフォルトで拒否します。オペレーターポリシーは AGENTPAY_POLICY_* 環境変数から取得して一度だけ読み込まれ、MCP 経由で変更または解除することはできません。ポリシーがない場合、オペレーターが AGENTPAY_ALLOW_UNPOLICED_SPEND=1 を設定しない限り、資金移動は拒否されます。
• set_spend_policy でできるのは制約を厳しくすることだけです。呼び出すたびに対象範囲へレイヤーが追加されます。上限を引き上げる、制約を取り除く、または許可リストの範囲を広げるリクエストは拒否され、以前のレイヤーのローリングウィンドウの集計は維持されます。制約を緩めるにはオペレーターによる再起動が必要です。ポリシーの状態はすべて引き続きプロセス内に保持され、再起動するとリセットされます。
• x402_pay と x402_session_start には max_payment_eth と pay_to が必要です。アセットは常に指定されます。デフォルトではチェーンの USDC が使用され、asset で別のアセットを指定できます。network も指定できます。別の受取人、アセット、ネットワークを指定する 402、ゼロアドレス、または上限を超えるデビット（元本と 0.77% のプロトコル手数料の合計）は、ウォレットへの書き込み前に拒否されます。 AGENTPAY_X402_MAX_PAYMENT は USDC の上限です。これを設定すると、USDC 以外の支払いは拒否されます。まず x402_quote で提示された条件を確認してください。
• 支払いが確定しても応答が配信されない場合、つまり応答の送信に失敗した場合、または支払い済みのリクエストに 2xx 以外のステータスが返された場合、オペレーターが照合するまで、そのホスト（パス、ポート、名前の表記を問わない）へのすべての新しい x402 支払いと、その受取人（ホストを問わない）へのすべての新しい x402 支払いがロックされます。ロックはウォレット呼び出し前に書き込まれるため、クラッシュしても失われません。
• 呼び出し元が選択する送信リクエスト（x402、見積もり、セッション、OTel のキルコールバック）には安全なトランスポートが使用されます。使用できるのは https のみです（キルコールバックは、AGENTPAY_KILL_CALLBACK_ALLOWED_HOSTS に含まれるホストに限り http を使用できます）。プライベート、ループバック、リンクローカル、メタデータの各宛先は拒否されます。DNS は一度だけ解決し、ソケットは検証済みアドレスに固定されます。リダイレクトは自動で追跡されず、応答本文は最大 2 MiB（レンダリング時は 1 MiB）に制限されます。
• send_payment、send_token、swap_tokens、bridge_usdc、create_escrow、x402_pay、x402_session_start は支出インテント内で実行されます。同一の再試行は再生されます。idempotencyKey によって同額の支払いを区別します。ブロードキャスト後の結果が不明な場合は、タイマーなしでインテントがロックされます。AGENTPAY_STATE_DIR でジャーナリングしない限り、ロックはプロセス内だけに保持されます。agentpay-mcp spend-intents list と resolve <id> settled|unsettled で照合します。これらはローカル CLI であり、MCP ツールではありません。 <id> は、list が各インテントに対して出力するシェルで安全に扱える id: ハンドルです。 settled（資金が移動した）にするとロックが解除され、キー付きインテントの idempotencyKey は永久に使用済みになります。キーなしインテントには使用済みにするキーがないため、同一の新しいリクエストは新しい支払いになります（再試行の安全性を確保するには idempotencyKey を使用してください）。unsettled（資金が移動していない）にするとロックが解除され、再試行で支払えるようになります。 状態ディレクトリを使用できるプロセスは一度に 1 つだけです。resolve を実行する前にサーバーを停止してください（サーバーの実行中に list を実行すると、読み取り専用のスナップショットが表示されます）。各サーバーにはそれぞれ別の AGENTPAY_STATE_DIR を指定してください。
• idempotencyKey に制御文字、不可視の書式文字、行区切り文字を含めることはできません。キーはエスケープされて出力され、シェルで実行されない形式になります。
• send_payment はトークンレジストリまたはトークンコントラクトから小数桁数を取得します。これと異なる token_decimals は署名前に拒否されます。
• オンチェーンの上限が存在するのは、ウォレット所有者が AgentAccountV2 で直接設定した場合のみです。アプリケーションポリシーによってコントラクトの上限が設定されることはありません。また、上限超過のトランザクションが人間による確認待ちになるのは、所有者キーがエージェントキーと分離されている場合のみです。
• get_transaction_history はオンチェーンのウォレットイベントを読み取ります。また、範囲を指定しない all クエリでは、このサーバープロセスが行った x402 決済も一覧表示します（支払い済み応答の最終 URL。リダイレクトにより 402 発行元と異なる場合があります。メソッド、金額、トークン、受取人、トランザクションハッシュ、再生回数も含まれます）。これらの x402 レシートが示すのは、支払いがブロードキャストされた（トランザクションハッシュが返された）ことだけであり、レシートが確認されたことではありません。レシートはメモリ内のみに保存され、最大 256 件で、再起動すると失われます。ブロック範囲を指定したクエリでは省略されます。これは MCP リクエストログではなく、オンチェーン処理前に拒否された試行や読み取り専用の呼び出しは記録されません。
• ランタイムのウォレット設定が現在サポートしているのは、Base mainnet と Base Sepolia です。未対応のチェーン ID は src/utils/client.ts でフェイルクローズされます。
• スワップ、ブリッジ、エスクロー、支払いの各ツールは資金を移動し、ガスを消費することがあります。上限を設定した金額と独立したウォレットの上限を使用してテストしてください。 詳細なコントロールマップと既知の制限については、docs/security-posture.mdをお読みください。

4.x からのアップグレード

v5.0.0は、互換性を破るセキュリティリリースです。アップグレードする前に、次の対応を行ってください。

• オペレーターポリシー（AGENTPAY_POLICY_*）を設定するか、AGENTPAY_ALLOW_UNPOLICED_SPEND=1で明示的にオプトアウトしてください。いずれも設定しない場合、すべての支払いが拒否されます。
• すべてのx402_payおよびx402_session_startの呼び出しに、max_payment_ethとpay_toを渡してください。先にx402_quoteを使って条件を確認してください。
• set_spend_policyで上限を引き上げたり、解除したりすることに依存しないでください。
• httpまたはプライベートネットワークのx402エンドポイントをhttpsに変更するか、AGENTPAY_ALLOWED_PRIVATE_HOSTS（本番環境）またはAGENTPAY_ALLOW_PRIVATE_NETWORK=1（開発環境のみ）で許可してください。
• 長時間稼働するサーバーではAGENTPAY_STATE_DIRを設定してください。

docs/security-remediation-2026-10.mdでは、各指摘事項とその修正およびテストの対応関係を確認できます。

技術的証拠の索引

リポジトリには、相互運用性と購入者の安全性に関する詳細な証拠を、バージョン管理されたドキュメントとして保管しています。

• docs/agentpay-buyer-flow-parity.mdでは、型付きの支払いエラーと購入者フローの動作を説明しています。
• docs/paid-mcp-gateway-hardening.mdでは、デフォルト拒否の制御とクォータの上限を説明しています。
• docs/agentpay-five-tool-parity-proof.mdでは、5つのツールの同等性チェックを記録しています。
• docs/agentpay-escrow-reputation-boundary.mdでは、エスクローとレピュテーションの境界を定義しています。
• docs/paid-mcp-proxy-discovery-readiness.mdでは、検出準備状況の証拠を記録しています。
• docs/x402-chain-neutral-gateway-profile.mdでは、パッケージ化されたチェーン中立プロファイルを定義しています。
• docs/x402-dynamic-paid-mcp-manifest-drift.mdでは、古くなった有料ツールのメタデータを検出するチェックを説明しています。
• docs/mcp-registry-listing-proof.mdとllms.txtで、ディレクトリのメタデータを公開しています。
• docs/smithery-paid-mcp-installation.mdとexamples/smithery-paid-mcp-installationでは、公開中の掲載を主張することなく、パッケージ化されたSmitheryの利用手順を説明しています。
• docs/paid-provider-health-proof.mdでは、プロバイダーの健全性を示す証拠を定義しています。
• docs/hosted-x402-proxy-verification.mdでは、ホスト型プロキシの事前確認を定義しています。
• docs/x402-native-vs-stripe-proxy.mdでは、ローカルの支出制御とホスト型プロキシの請求を区別しています。
• docs/dependency-pin-policy.mdでは、支払いに不可欠なパッケージのリリースゲートを定義しています。

AgentPayはviemのバージョンを2.57.4に厳密に固定しています。

ディレクトリの比較は[email protected]を対象に実施しました。このREADMEの冒頭に記載されているパッケージバージョンが、現在のリリースです。

クリーンなチェックアウトを検証する

npm ci
npm run build
npm run typecheck
npm test
npm run lint
npm run security
npm run smoke:clean-install

CIワークフローは、毎日の定期レビューおよび修復ワークフローとは別です。定期レビューの失敗は製品テストの結果ではなく、修復の成功もCIの代わりにはなりません。

関連リポジトリ

• Agent Wallet SDKは、このサーバーが使用するウォレットおよびポリシーライブラリを提供します。
• AgentPay Wallet Starterは、資金不要のオンボーディング手順をまとめて提供します。
• NVIDIA NeMo Agent Toolkit Examples PR 17は、独立してマージされた統合例です。

サポートと脆弱性の報告

• 製品のバグはGitHubのイシューキューから報告してください。
• セキュリティ上の問題はSECURITY.mdに従って報告してください。
• 貢献に関するルールはCONTRIBUTING.mdに記載されています。

License

MIT. See LICENSE.