Aifinpay

@aifinpay/mcp

永続的なエージェント ID、Agent Passport の解決、ルートの検出、署名を伴わない決済請求書に対応する AiFinPay MCP サーバーです。正式なドメイン： aifinpay.io。

バージョン 2.11.4 は、このチェックアウトで公開済みの agent 2.9.0 と正式な skill 2.10.2（AiFinPay/skill 48285cf、2026-10-19 公開）を基に準備されています。別の正式なプロデューサーによる最終的な不変ソースピンは必須の引き継ぎ項目であり、移動するブランチへの差し替えはできません。 2026-10-04 に確認した公開済みベースラインは MCP2.5.0 でした。パッケージの公開と実際のレジストリ依存関係／ロックファイルの更新は、引き続きリリースゲートです。ソースコホートのビルドだけでは、これらの手順が完了したことは証明できません。payable_fetch を使った所有者有効化済み v1.4 の購入はリリース済みです。Polygon では 2.2.0 以降、Base（ETH または USDC）では 2.5.0 以降に対応しています。scope: "merchant" を指定するサイト全体の一括購入は 2.4.1 以降に対応しています。決済設定がない場合、サーバーは payable_fetch を含むすべてのツールを一覧表示しますが、署名は行いません。payable_fetch と payment_setup_status は、代わりに設定チェックリストを返します。

5つの手順で最初の決済を行う

各手順は1つのコマンドまたはツール呼び出しです。署名は手順5でのみ行われ、手順4で所有者がすべての上限を設定した後に限り、1回だけ行われます。

1. 価格を確認します。 リソースに GET を実行します。402 には、加盟店（merchant_id）、リクエストあたりの価格、最小バッチ（標準リクエスト200件で $0.10）が示されます。

2. 設定を確認します。 payment_setup_status を呼び出します。ウォレット（永続または一時）、決済が有効かどうか、設定済みの所有者上限、RPC が応答した場合の残高、funding（永続ウォレットに必要な額を本日のレートで算出）、および next_step（未完了の項目のうち最初のもの）が返されます。

3. 永続ウォレットを用意します。 wallet.persistent が false の場合は、npx @aifinpay/mcp init を実行します。ターミナルがない場合は、JSON ドキュメントを1つ出力します。その env（パスフレーズはここにのみ含まれます）を MCP クライアント設定の aifinpay サーバーエントリにコピーし、サーバーを再接続してから agent_reload を呼び出します。一時アドレスには絶対に入金しないでください。

4. 入金して有効化します。 所有者に addresses.evm と payment_setup_status の funding に記載された金額を伝えます。最小バッチ（$0.10）を本日のレートで POL に換算した額にガス上限を加えた金額です（最悪ケースの手数料が上限を超える場合、SDK は署名前に処理を拒否します）。レートは変動します。2026-10-19 時点では $0.10 は 1.08 POL でした。そのため、記憶した金額を伝えてはいけません。funding に amount ではなく rate_error が含まれている場合は、所有者に「本日のレートで算出したバッチ価格（POL）にガス上限を加えた額」を入金するよう依頼し、具体的な金額は伝えないでください。所有者が入金を確認したら、同じ env に決済設定を追加し、クライアント内で aifinpay MCP サーバーを再起動します（agent_reload は環境変数を読み込みません）。

   {
     "AIFINPAY_PAYMENTS_ENABLED": "1",
     "AIFINPAY_GATEWAY_ORIGINS": "https://dev.ratersapp.com",
     "AIFINPAY_GATEWAY_PATH_MODE": "direct",
     "AIFINPAY_MAX_USD": "5",
     "AIFINPAY_DAILY_USD": "20",
     "AIFINPAY_MAX_GAS_POL": "0.3"
   }
   

   USD の値は所有者が一度設定する上限であり、予算ではありません。実際の上限はダッシュボードにあります（下記の「所有者の上限」を参照）。 その後、payment_setup_status は ready: true を返します。

5. 決済します。 payable_fetch({"url": "https://dev.ratersapp.com/api/agent/genres/list"}) を呼び出すと、Polygon（splitter v1.4）でバッチを購入し、コンテンツとレシートの概要を返します。以降のリクエストでは同じバッチが再利用されます。

現在、Polygon と Base は v1.4 で提供されています。settlement_routes ではこれらが先に一覧表示され、live: true となっています。その legacy_v13 セクションには、payable_fetch が使用しない旧 splitter v1.3 のルートが記載されています。

有料の GET リクエストをネイティブに有効化する

公開されている npx @aifinpay/mcp init で作成した永続ウォレット、または既存の設定済み ID を使用します。パスフレーズは秘密にしてください。所有者はサーバーの env に以下を追加します（init は同じブロックを出力します）。

{
  "AIFINPAY_PAYMENTS_ENABLED": "1",
  "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
  "AIFINPAY_GATEWAY_PATH_MODE": "direct",
  "AIFINPAY_MAX_USD": "5",
  "AIFINPAY_DAILY_USD": "20",
  "AIFINPAY_MAX_GAS_POL": "0.3"
}

上限は設定例であり、承認を意味するものではありません。USD の上限は購入を対象とし、ガスには独自の POL 上限があります。オリジンは、所有者が許可した HTTPS の完全一致オリジンです。direct はセルフホストのサイトで完全なパスを使用し、gateway はホスト型ゲートウェイで加盟店スラッグを使用します。環境を変更した後は、MCP プロセスを再起動／再接続してください。

オーナー上限：環境変数で設定する上限と、ダッシュボードで設定する運用上限

AIFINPAY_MAX_USD と AIFINPAY_DAILY_USD は、オーナーのキーで署名する前に SDK が要求する上限です。一度、後から変更する必要がない程度に十分高い値（例の、決済あたり 5、1 日あたり 20 は予算ではなく上限です）に設定し、そのままにしておきます。日々の運用上限はダッシュボードで管理します。agent_claim_self でエージェントをリンクしたら、オーナーは https://dash.aifinpay.io の Controls で決済ごとの上限、1 日あたりの上限、一時停止、許可するサイトを管理できます。バックエンドは、該当エージェントのすべての /v1/quote と /v1/pay でそのポリシーを適用します。環境変数の変更もサーバーの再起動も不要です。環境変数で設定した上限も引き続き適用されるため、決済は両方の条件を満たす必要があります。

インデックス付きウォレットの導出

ウォレット CLI と MCP は、1 つのリカバリーシードから決定論的な子ウォレットを使用できます。npx @aifinpay/wallet new --index 0 で MCP 対応ウォレットを作成します。キーストアにはルートシードが保持され、既存のフィールドは変更せずに、インデックスがオプションのメタデータとして追加されます。MCP は保存されたインデックスを自動的に使用します。別の MCP プロセスで別の子ウォレットを選択するには、AIFINPAY_WALLET_INDEX にその 10 進数のインデックスを設定します。同じ変数は、SEED_HASH または agents.json レコードからシードが指定される場合にも適用されます。

各チェーンはそれぞれ独自のインデックス付きキーを導出します。たとえば、EVM = SHA-256("aifinpay:evm:v1\0" || decimalIndex || recoverySeed)、Solana = Ed25519(SHA-256("aifinpay:solana:v1\0" || decimalIndex || recoverySeed)) です。10 進数の UTF-8 インデックスは、そのチェーンのドメイン NUL 区切り文字の後に続きます。インデックス 0 が最初のウォレットです。インデックスは 0 以上 4294967295 以下である必要があります。インデックスを選択しない場合、既存のアイデンティティは現在の導出方法を維持します。

AIFINPAY_MAX_GAS_POL は、支払うと見込まれる手数料ではなく、最悪の場合の上限を設定します。署名前に、クライアントは Polygon RPC が提示する 1 ガスあたりの最大手数料で、推定ガス量に 20% を加えた金額を算出します。その金額が上限を超える場合は、V14_GAS_BUDGET_EXCEEDED を返して処理を拒否します。最悪の場合の金額はガス価格に応じて変わります。2026 年 9 月時点で約 280 gwei の場合、POL 決済では約 0.10 POL、トークンの承認と決済が必要な USDC では約 0.21 POL です。その価格であれば 0.3 で両方をカバーできます。現在の Polygon のガス価格を確認し、それより高い場合は上限を引き上げてください。実際に請求される手数料は通常、上限の一部ですが、署名前にウォレットにはバッチの価格と最悪の場合の金額の両方が必要です。

ネイティブ POL の代わりに USDC で支払うには、オーナーが "AIFINPAY_PAY_ASSET": "USDC" も設定します。この場合、ウォレットにはバッチ分の USDC とガス分の POL が必要です。正確な金額のトークン承認と決済の両方を合わせて、AIFINPAY_MAX_GAS_POL の範囲内に収める必要があります。未設定または "POL" の場合は、ネイティブ POL が使用されます。

別のチェーンでの支払い

AIFINPAY_PAY_CHAIN では、payable_fetch が決済に使用するチェーンを明示的に選択します。 デフォルトは polygon で、以下の機能一覧に記載された正確なサポート対象名も指定できます。 設定できるのは所有者のみです。また、加盟店への支払いは、その見積もりが指定したチェーン向けの場合に限られます。それ以外のチェーン向けの見積もりは拒否され、決してそのまま処理されることはありません。Base ではバッチ料金を ETH（または AIFINPAY_PAY_ASSET: "USDC"）で支払い、ガス代も ETH で支払うため、上限には ETH 建ての AIFINPAY_MAX_GAS を使用します。

{
  "AIFINPAY_PAY_CHAIN": "base",
  "AIFINPAY_MAX_GAS": "0.0002"
}

AIFINPAY_MAX_GAS は、支払いチェーンのネイティブ通貨建てのガス上限です。 AIFINPAY_MAX_GAS_POL は Polygon では引き続き使用できますが、Base では ETH として読み取らずに拒否されます（0.3 POL は約 0.04 ドルですが、0.3 ETH は数百ドルです）。 Base では最大コストに L1 データ料金とオペレーター手数料が含まれるため、所有者は最新の見積もりに基づいて上限を設定する必要があります。ウォレットの EVM アドレスはすべてのチェーンで同じなので、Ethereum メインネットではなく、Base 上の ETH で資金を用意してください。AIFINPAY_RPC_URL を設定すると、チェーンのパブリック RPC（https://mainnet.base.org、 https://polygon.drpc.org）を置き換えられます。

あるチェーンで保留中の支払いは、そのチェーンを設定した場合にのみ復旧されます。チェーンを切り替えても、支払いが再送されたり、失われたりすることはありません。

payable_fetch({"url":"https://merchant.example/api/data"}) を呼び出します。このツールは、元の署名付き v1.4 見積もり、独立して取得した最新のネイティブ通貨／米ドル価格、SDK のランタイム／署名者の検証、所有者の上限を使用します。送信前に準備済みトランザクションを永続化し、レシートを検証して、購入済みのバッチを再利用します。特別な加盟店用スクリプト、代替コントラクト、ファシリテーターへのフォールバックは使用しません。設定済みチェーン上の GET リクエストに対応します。EVM レシートによる支払いはライブモードのみで、ネイティブ通貨または設定済みのステーブルコインで行います。Amoy の支払いレシートには対応していません。最小バッチ料金は 0.10 ドルにガス代を加えた額です。AIFINPAY_MAX_USD は、購入予定のバッチ額以上に設定するだけで十分です。

1 つのエンドポイントではなくサイト全体へのアクセスを購入するには、 payable_fetch({"url":"https://merchant.example/api/data","scope":"merchant"}) を呼び出します。 これにより 1 つのバッチでその加盟店のすべてのパスを利用できます。ただし、リクエストごとに表示価格が適用されるため、プレミアムページでは通常の API 呼び出しより多くの残高が消費されます。価格、所有者の上限、承認済みオリジンは変わりません。AIFINPAY_GATEWAY_ORIGINS にないオリジンは名前を示して拒否されます。追加できるのは所有者のみです。

ネットワークアクセス

送信先ホストを許可リストで制限するサンドボックスでは、api.aifinpay.io（見積もりとレシート）と、支払いチェーンの RPC を許可する必要があります。独立したネイティブ通貨／米ドルレートには、Polygon／Base 上ではピン留めされた Chainlink フィードを使用し、次に api.coinbase.com、続いて api.coingecko.com を使用します。それ以外のチェーンでは、これらの HTTP 価格情報ソースを使用します。有効な最新レートを取得できるソースがない場合、payable_fetch は支払い前に停止し、エラーに試行した各ホストが示されます。

どの AI クライアントが支払ったか

payable_fetch は、支払いを行う AI クライアントを加盟店に伝えます。サーバーは、初期化時に MCP クライアントから送信された clientInfo.name を、支払いリクエスト（および保留中の支払いの復旧時）に付与する AIFP-Agent-Framework ヘッダーへ対応付けます。

clientInfo.name	AIFP-Agent-Framework
claude-ai, claude-code	claude
cursor, cursor-vscode	cursor
windsurf	windsurf
chatgpt, openai	chatgpt
codex-mcp-client	codex
gemini	gemini
perplexity	perplexity

名前は完全一致で照合されます。それ以外のクライアントはヘッダーを送信しません。サーバーが推測することはありません。支払い、上限、レシートのいずれも、この情報には依存しません。初期化時にサーバーは、受信した名前を含む 1 行を stderr に記録します。たとえば、[aifinpay-mcp] client "codex-mcp-client" → framework codex のように記録されるため、この表にないクライアントは正確な名前を添えて報告できます。

エージェントを所有者のダッシュボードにリンクする

所有者は、https://dash.aifinpay.io → My Agents でエージェントの残高、支払い、受領書を確認できます。ここで Claim via MCP を選ぶと一度限りの URL が生成されるので、agent_claim_self に渡します。このツールが接続するのは AiFinPay のオリジンのみで、このエージェント自身のアドレスに対する請求チャレンジにのみ署名し、資金を移動することはありません。所有者が選択した支払い方式は、正常に確認される必要があります。2 つ目のウォレットはベストエフォートで処理されます。利用可能なネットワークとアセットは、選択したウォレットの Fund パネルで確認してください。リンクしても無効化されたネットワークは有効になりません。init の後に所有者へこの操作を案内してください。以降、所有者はダッシュボードの Controls でエージェントの利用上限を管理します（上記の「所有者による上限設定」を参照）。

すべての支払い方式のプライベートな復旧状態は、AIFINPAY_HOME/payments/<evm-address>/state.json（デフォルトのホームは ~/.aifinpay）に保存されます。状態ファイルのパーミッションは600、ディレクトリのパーミッションは700に設定され、アトミックに書き込まれて fsync されます。1 つの操作ロックで、プロセス間におけるウォレットの操作を直列化します。再試行時は、次の購入を許可する前に保留中の受領書を復旧します。プロセスがクラッシュすると、所有者が照合するまでロックが残り、自動的に解除されることはありません。準備済みのトランザクションがブロードキャストされていない場合、または結果が不明なままの場合は、何かをクリアする前にその正確なハッシュを照合してください。生のトランザクション、受領書の JWT、状態ファイルをチャットに貼り付けないでください。未確認の支払いは、予算を保守的に消費します。

ツール

ツール	用途
agent_address	現在の Solana、EVM、Casper のアドレスを読み取ります。
agent_claim_self	このエージェントを所有者のダッシュボードにリンクします（一度限りの URL）。
agent_reload	現在の MCP 接続でローカルのウォレットファイルを再読み込みします。
agent_quota	エージェントの利用枠を読み取ります。
agent_passport_resolve	グローバルな Agent Passport の ID を解決します。
payment_setup_status	次の next_step を 1 つ示す、読み取り専用のセットアップチェックリストです。
settlement_routes	まず Splitter v1.4 のルート（現在稼働中）、次に従来の v1.3 のルートを返します。
settlement_invoice	署名を行わない精算インボイスを準備します。
agent_history	インデックス済みの精算、または保持されている受領書バッチを読み取ります。
settlement_solana	署名を行わない Solana 精算インボイスを作成します。
settlement_casper	署名を行わない Casper 精算インボイスを作成します。
deployment_info	デプロイ情報（アドレス、アセット、精算ステータス）を読み取ります。

payable_fetch は常に一覧に表示されます。永続ウォレットと AIFINPAY_PAYMENTS_ENABLED=1 が設定され、すべての所有者による上限が設定済みの場合にのみ署名します。それ以前は、payment_setup_status のチェックリストをツールエラーとして返し、どこにも接続しません。支払いが有効で、所有者による上限が 1 つでも未設定または無効な場合、サーバーはツールを非表示にするのではなく、起動を拒否します。受け付けるのは url、max_amount_usd、scope、expected_merchant_id のみです。max_amount_usd は 1 回の呼び出しで所有者の支払いごとの上限を引き下げることはできますが、引き上げることはできません。

各ゲートウェイサイト（オリジン + スラッグ）は、このウォレットが最初に支払ったときのマーチャントに固定されます。エージェント SDK はこの固定情報を ~/.aifinpay/merchant-pins または AIFINPAY_STATE_DIR/merchant-pins に保持します。AIFINPAY_HOME を変更しても、固定情報の保存先は変わりません。サイトが別のマーチャントとして応答すると、payable_fetch は見積もりの取得前に停止し、両方のマーチャント ID を示します。支払いは行われず、エージェント自身が変更を承認することはできません。所有者が新しいマーチャントを確認した後、expected_merchant_id にその ID を設定して呼び出すと、支払いが行われ、サイトの固定先が更新されます。「あらゆるマーチャント変更を許可する」包括的な引数はありません。410 gateway_retired のサイトは終端状態であり、このツールは再試行しないよう伝えます。dev_payment_quote は AIFINPAY_MODE=dev の場合にのみ登録されます。従来の agent_call、agent_quote、pay_with_split、quote_split は引き続き登録されません。

永続的なウォレットの選択

CLI（init および stdio）、プログラムによるサーバー、agent_reload では、同じ優先順位が適用されます。

1. SEED_HASH：64 桁の 16 進文字列でエンコードされた既存の 32 バイトのシード。0x を先頭に付けることもできます。これは AiFinPayAgent.fromSeed に直接渡されます。再度ハッシュ化したり、ニーモニックを指定したりしないでください。
2. MCP プロセスの作業ディレクトリを基準とする ./aifinpay/agents.json。デスクトップクライアントの作業ディレクトリがプロジェクトディレクトリと異なる場合は、絶対パスを AIFINPAY_AGENTS_FILE に設定してください。このファイルには、id フィールドと非公開の seed_hash フィールドを持つレコードの agents 配列が含まれます。レコードが複数ある場合は、AIFINPAY_AGENT_ID を使って正確に 1 つ選択してください。
3. AIFINPAY_AGENT_SECRET：従来の Base58 形式の Solana シークレット。
4. ~/.aifinpay/agent.json または AIFINPAY_HOME/agent.json：従来の CLI キーストア。暗号化されたファイルには AIFINPAY_WALLET_PASSPHRASE が必要です。

シードとウォレットファイルは非公開に保ち、チャット、ソース管理、ログに含めないでください。設定された入力が無効、または曖昧な場合はエラーになり、代わりのウォレットが生成されることはありません。ウォレットがまったく設定されていない場合、サーバーは一時的なアイデンティティを使用します。このウォレットに資金を送らないでください。

外部 EVM ウォレットを埋め込む

ホスト側のプログラムは、viem の WalletClient を createServer に直接渡すことができます。これはプログラムからの利用に限られます。npx @aifinpay/mcp と環境変数では、ウォレットクライアントを渡せません。Solana やその他のアイデンティティ関連機能には、既存のローカルアイデンティティ設定を維持してください。指定すると、クライアントのアカウントが EVM 決済アイデンティティとなり、決済ジャーナルはそのアドレスに紐付けられます。そのチェーンは、所有者が選択した AIFINPAY_PAY_CHAIN（デフォルトは Polygon）と一致する必要があります。一致しない場合、SDK はプロバイダーの切り替えやローカルの EVM キーへのフォールバックを行わず、処理を拒否します。

import { createServer, loadConfigFromEnv } from "@aifinpay/mcp";
import type { EvmWalletClient } from "@aifinpay/agent";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Constructed by the host from its chosen external signer/provider.
declare const walletClient: EvmWalletClient;

const { server } = await createServer({
  ...loadConfigFromEnv(),
  evmWalletClient: walletClient,
});
await server.connect(new StdioServerTransport());

ホストは、選択したチェーンに紐付けられた signTransaction を持つ viem の LocalAccount を提供する必要があります。v1.4 では、SDK が検証済み RPC を通じてブロードキャストする前に、署名済みトランザクションの正確なバイト列が永続化されます。JSON-RPC のみのクライアント、送信専用クライアント、スマートアカウントクライアントは、永続的な復旧を回避することにつながるため、拒否されます。MCP は引き続き、設定された支出上限、ランタイムとルートのチェック、レシートの検証、および復旧を適用します。決済の復旧が保留中の状態で注入するアカウントを変更するには、照合して再接続する必要があります。これはツールレベルでのウォレット切り替えではありません。

初期化と接続

見積もりや請求書は、決済の完了を意味しません。payable_fetch は、上記の所有者設定を使用する場合にのみ決済を行います。

ローカル設定

AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init

キーストアは保存時に暗号化されており、MCP サーバーが読み込むには同じ AIFINPAY_WALLET_PASSPHRASE が必要です。使い捨てのテスト用ウォレットに限り、 npx @aifinpay/mcp init --plaintext を実行すると暗号化せずに書き込みます（モード 600）。どちらも指定されていない場合、ターミナル上での init は、資金を入れる可能性のあるウォレットを暗号化せずに作成することを拒否します。

標準入力がターミナルではない場合（エージェントのサブプロセスなど）、または AIFINPAY_NONINTERACTIVE=1 が設定されている場合、init はプロンプトを表示しません。192 ビットのパスフレーズを生成してキーストアを暗号化し、JSON ドキュメントを 1 つ出力します。

{
  "keystore": "/home/me/.aifinpay/agent.json",
  "created": true,
  "encrypted": true,
  "source": "legacy-keystore",
  "addresses": { "evm": "0x…", "solana": "…", "casper": "account-hash-…" },
  "env": { "AIFINPAY_WALLET_PASSPHRASE": "<generated>" },
  "passphrase_note": "…",
  "payment_env_example": { "AIFINPAY_PAYMENTS_ENABLED": "1", "…": "…" },
  "next_step": "Put \"env\" into the aifinpay server entry of the MCP client config …"
}

呼び出し元がクライアント設定に設定する必要があり、ほかに渡す手段がないため、パスフレーズは env の中にのみ表示されます。その出力を取得したプロセスはパスフレーズも取得するため、出力は秘密情報として扱ってください。2 回目の実行ではウォレットはそのまま保持され、パスフレーズの代わりにプレースホルダーが出力されます。AIFINPAY_HOME が設定されている場合、env にその絶対パスも含まれ、サーバーは init が書き込んだキーストアを読み込みます。同じ理由で、payment_setup_status はサーバーの AIFINPAY_HOME を指定した init コマンドを提示します。暗号化されたキーストアが存在し、AIFINPAY_WALLET_PASSPHRASE が未設定の場合、init はキーストアに手を加えず、変数名を示す JSON 行を 1 つ出力してステータス 2 で終了します。その場合の next_step は、新しく空の AIFINPAY_HOME（~/.aifinpay/agent-<yyyymmdd>）で init を実行し、出力された env をクライアント設定に追加することです。

ウォレットは次の優先順位で選択します：SEED_HASH → ./aifinpay/agents.json → 従来の AIFINPAY_AGENT_SECRET → ~/.aifinpay/agent.json。 SEED_HASH は 32 バイトの 16 進数シードで、SDK の fromSeed に直接渡します。 正確なプロジェクトファイルのスキーマと複数エージェントの選択方法については、スキルを参照してください。 init は選択したウォレットの公開アドレスを出力します。シードまたはプロジェクトウォレットがすでに設定されている場合、従来のウォレットを追加作成することはありません。ウォレットがない場合は、モード 600 で従来のキーストアを作成します。既存のキーストアはそのまま保持されます。そのファイルは安全な場所にバックアップしてください。公開済みリリースを使用するか、このソースチェックアウトをビルドしてください。

ホストの作業ディレクトリがプロジェクトディレクトリではない場合は、絶対パスを AIFINPAY_AGENTS_FILE に設定してください。シード自体を共有設定に記載しないでください。 クライアント設定では、シークレットを埋め込まずにキーストアを使用できます。

{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp"],
      "env": {
        "AIFINPAY_AGENTS_FILE": "/absolute/project/aifinpay/agents.json",
        "AIFINPAY_AGENT_ID": "research-agent"
      }
    }
  }
}

この npx コマンドでインストールするには、上記のリリースが公開されている必要があります。 固定された依存関係が公開された後は、ソースチェックアウトから mcp/ で npm ci && npm run build を実行し、代わりに node /absolute/path/to/mcp/bin/aifinpay-mcp.js を設定できます。

従来のキーストアを使用する場合は、npx @aifinpay/mcp init を 1 回実行し、プロジェクトファイル関連の変数は省略してください。AIFINPAY_WALLET_PASSPHRASE は作成時に従来のファイルを暗号化するために使用されます。ファイルを開くには、サーバーの env に同じ値が必要です。init は、その値にプレースホルダーを入れたブロックを出力します。Claude Code の .mcp.json など、設定内の変数を展開するクライアントでは、パスフレーズをファイルに直接記述する代わりに "${AIFINPAY_WALLET_PASSPHRASE}" を使用できます。すでに接続済みのサーバーでは agent_reload を呼び出して読み込めるため、新しい会話は必要ありません。パッケージまたは起動環境を変更した場合は、ホストのサポート状況に応じてサーバーを再接続する必要があります。

履歴

MCP サーバーに 1 回接続します。init の実行後、またはウォレットファイルの更新後は、同じ接続で agent_reload を呼び出してください。新しい会話は必要ありません。再読み込みに失敗した場合、以前のウォレットが保持されます。シェルの環境変数を変更した場合、プロセスの環境は起動時のスナップショットであるため、MCP プロセスを再接続する必要があります。agent_address が使用する予定のウォレットと一致することを確認してください。

その他の環境変数

変数	デフォルト	用途
AIFINPAY_BASE_URL	https://aifinpay.io	バックエンドのURLです。未設定の場合、payable_fetchはhttps://api.aifinpay.ioで見積もりと検証を行います。
AIFINPAY_TIMEOUT_MS	30000	リクエストのタイムアウトです。
AIFINPAY_MAX_USD	—	payable_fetchの1回あたりの支払い上限（USD）です。支払いを有効にする場合は必須です。
AIFINPAY_GATEWAY_ORIGINS	—	エージェントが支払いを行える、カンマ区切りのHTTPSオリジンの完全一致リストです。支払いを有効にする場合は必須です。
AIFINPAY_GATEWAY_PATH_MODE	gateway	マーチャントのスラッグを識別子として使用する場合はgateway、完全なリクエストパスを識別子として使用する場合はdirectを指定します。
AIFINPAY_PAY_CHAIN	polygon	オーナーが選択する支払いチェーンです。2.8.1のソース機能一覧を参照してください。
AIFINPAY_MAX_GAS	—	支払いチェーンのネイティブ通貨（POL、ETH、AVAX、BNB、XRP）での、1回あたりの支払いのガス上限です。
AIFINPAY_RPC_URL	チェーンのパブリックRPC	支払いチェーン用のHTTPS RPCです。
AIFINPAY_CLAIM_ORIGINS	AiFinPayダッシュボード	agent_claim_selfがエージェントをリンクできるオリジンの完全一致リストです。

agent_history({address, source:"transactions", network:"polygon"})は、バックエンドの永続インデクサーが対応している場合、そのネットワークのインデックス済み決済を読み取ります。日付が明記された本番環境の基準ではPolygonのインデックス作成に対応していますが、別のクライアントチェーン記述子があるだけでは、履歴に対応しているとは確認できません。source:"receipts"は、テストモードの支払いを含む、保持されたバッチを読み取ります。公開パスポートを先に解決するには、addressの代わりに、またはaddressと併せてpassportを渡します。パスポート解決機能がないバックエンドでは、パスポートのみのクエリに対応できません。公開メタデータの取得に秘密のAPIキーは不要です。

レスポンスにはベアラー領収書は含まれません。上限は1～100です。next_offsetに従ってください。履歴のソースと対応範囲は明示されており、すべてのウォレットを網羅するエクスプローラーではありません。テストモードのインデックス作成はバックエンドの機能に依存します。保持された領収書の履歴は別のソースであり、メインネットが有効化されていることを示すものではありません。

const { server } = await createServer(loadConfigFromEnv());
await server.connect(new StdioServerTransport());

ID環境オプションに対応するプログラム上の設定は、seedHash、agentsFile、agentId、agentSecretB58、walletHome、walletPassphraseです。

• AIFINPAY_BASE_URL：バックエンドのオリジンです。デフォルトはhttps://aifinpay.ioです。

• AIFINPAY_HOME：レガシーエージェントのagent.jsonキーストアが置かれたディレクトリです。

• AIFINPAY_MODE=dev：dev_payment_quoteを公開します。別の開発用ベースURLが必要です。

• AIFINPAY_TIMEOUT_MS：SDKリクエストのタイムアウトです。

• AIFINPAY_MAX_USD：payable_fetchの1回あたりの支払い上限（USD）です。支払いを有効にする場合は必須です。

• AIFINPAY_TRUSTED_HOSTS：DNS事前チェックを省略できるホストの完全一致リストです。

• AIFINPAY_ALLOW_PRIVATE_FETCH=1：ローカル開発環境でのネットワークアクセスを明示的に許可します。 公開ホスト型MCPでは決して有効にしないでください。

セルフホスト可能なAIFP-1ゲートウェイを使用する場合は、AIFINPAY_GATEWAY_ORIGINSにHTTPSオリジンの完全一致リストを設定します。AIFINPAY_GATEWAY_PATH_MODE=directにすると、プロセスは各リクエストの完全なパス名をAIFP-1のリソース識別子として使用します。gatewayではマーチャントのスラッグを使用します。このモードはプロセス全体に適用され、信頼済みオリジンの許可リストを拡張することも、本番RCで廃止された署名ツールを有効にすることもありません。

開発用の見積もりでは、ウォレット署名、発行者の検証、領収書の計測は省略されません。バックエンドの前提条件については、同梱のスキルを参照してください。低レベルSDKにはAmoy実行機能がありますが、このMCPはAmoyでの有料領収書の購入を公開していません。

ライセンス

MIT。

2.8.1 ソース候補における追加の EVM ネットワーク

オーナーの AIFINPAY_PAY_CHAIN では、polygon、base、optimism、arbitrum、avalanche、 bnb、unichain、xrplevm、robinhood を指定できます。AIFINPAY_MAX_GAS は、選択したネイティブ通貨 POL／ETH／AVAX／BNB／XRP 建てです。従来の POL 上限が適用されるのは Polygon のみです。アセットはチェーンごとに 固定する必要があります。これには、BNB の小数点以下 18 桁の USDC／USDT と、Robinhood の 小数点以下 18 桁の USDe／小数点以下 6 桁の USDG が含まれます。XRPL EVM で使用できるネイティブ通貨は XRP のみです。 メタデータは agent 2.6.1 から取得しますが、バックエンドは引き続き、その加盟店／ネットワークを認可して提供する必要があります。 ソースでのサポートによって、本番環境でネットワークが有効になることはありません。保留中のジャーナルには元のチェーンが保持され、 追加の決済を行わずに復旧されます。チェーン情報のない従来のジャーナルを引き継げるのは、オーナーが設定したチェーンと、 実際に署名されたトランザクションのチェーン ID、支払者、固定された宛先、および完全に一致する呼び出しが一致する場合のみです。 証拠が不十分な場合は、レシートを手動で照合する必要があります。後から見積もりの有効期限が切れても、既存の支払いに対するレシートの復旧には影響しません。

最終リリースゲートの通過後、次の順序でリリースします。レビュー済みの正式な skill2.9.0 と agent2.6.1 を公開し、実際のレジストリリリースから MCP の依存関係とロックファイルを更新して、単独 MCP CI に合格した後、MCP2.8.0 を公開します。この候補には、新たにソースからパックした agent2.6.0 と skill2.9.0、および正確な Python2.5.1 リリースターゲットが必要です。既存のレジストリの agent2.5.0／skill2.8.0 エントリーは公開まで維持されます。 npm のインテグリティや解決結果を捏造してはなりません。古い agent2.3.x では新しいディスクリプター／ヘルパーのインポートをビルドできず、古い skill2.6.0 では正確なリリースターゲットのチェックを満たせません。ホスト型ソース CI では scripts/check-mcp-source-cohort.mjs を使用します。これは、バイト列を保持したパッチ適用済みレジストリブートストラップと、同一コミットの Node、および完全に固定された正式な skill パッケージを使い、使い捨てディレクトリで実行します。Node プロデューサーの正式なソースロックファイルを使って正式なランタイムを初期化します。このロックファイルは別個の解決証拠であり、npm はこれを tarball に含めません。パッケージの正確なバイト列とバージョン、バンドルされた skill、高／重大度の監査、およびすべてのテストに合格する必要があります。また、対応する実際のレジストリロックファイルがないソースコホートを、レジストリ公開ガードが引き続き拒否する必要があります。単独リリース CI では、更新済みの実際のレジストリロックファイルが必要です。古いレジストリ依存関係ロックファイルのまま、この候補を公開してはなりません。

ウォレットの台帳／ジャーナルには、共通のローカルファイルシステムを使用し、ダウングレード前に保留中のトランザクションを照合してください。 Node 2.4 では、結果が不明な場合、予約は期限切れになりません。レシートのエラーによって、確定済みの支出が返金されることもありません。古い SDK バージョンでは、この状態が期限切れになったりリセットされたりする可能性があります。カスタムの上限付き v1.4 台帳アダプターには、新しいバインド済みの準備／復旧／完了フックが必要です。フックがない場合、支払いは拒否されます。

Solana ソース候補

Version2.7 は NodeSDK2.5 と canonical skill2.8 を対象としています。これらは連携したリリース目標です。ソースを統合しても、npm への公開やネットワークの有効化が行われるわけではありません。公開済みの deployments1.1.3 の Solana エントリーは引き続き無効です。payable_fetch は SDK の利用可否チェックを維持し、これを回避することはできません。

別途承認され、提供される Solana ルートでは、所有者が AIFINPAY_PAY_CHAIN=solana、ライブモードの場合は明示的に AIFINPAY_SOLANA_NETWORK=mainnet（開発モードの場合は devnet）、および信頼できる HTTPS の AIFINPAY_RPC_URL を設定します。AIFINPAY_MAX_FEE_LAMPORTS は、トランザクション手数料と必要なアカウントのレンタル料を合わせた上限となる正の整数です。EVM のガス上限を Solana で使用することはできません。ネイティブ SOL とネットワークが固定されたクラシック SPL アセットは、AIFINPAY_PAY_ASSET で選択します。既存の決済に対するオプトイン、承認済みオリジン、および決済ごと・日ごとの USD 上限も引き続き必要です。

Solana の見積もりをリクエストする前に、SDK2.5 は署名済み認可、nonce、所有者コンテキストを正確な形で共有プライベート台帳に保存します。タイムアウトまたは再起動後は、新しい nonce を生成せず、その認可を再送します。日次の切り替わりがあっても、その認可に対する決済ごとの上限は固定されたままです。MCP は送信前に現在の日次利用可能額を引き続き確認します。認証済みの正確な未承認レスポンスによって終了できるのは、予約されていないローカルインテントのみです。発行済みのバックエンド見積もり予約が返金されることはありません。アップグレード時には保留中の2.5台帳状態を保持してください。ダウングレードの前に照合し、決済を再試行するために状態を削除しないでください。

プライベートの永続ジャーナルは、送信前に完全な署名済み Solana トランザクションと base58 署名を保存し、認可額には手数料とレンタル料を含めます。支払者の ID では大文字と小文字を区別します。再起動や再試行では元のレシートを復元します。タイムアウトやブロックハッシュの有効期限切れによって、代替の決済が実行されることはありません。同じローカルウォレット予算は、引き続き決済ファミリー間で共有されます。

Solana トランザクションの失敗が確定済みと証明された場合は、レシートや代替決済を伴わず、エラーとして返されます。SDK が署名済みトランザクションと正規の確定済みブロックを正確に検証し、紐づけられた台帳を永続的に照合した後、MCP は実際の手数料の引き落としをアトミックに保持し、保留中の購入ガードを解除します。プライベートジャーナルには元の署名と失敗ステータスが保持されます。証拠がない場合、または一致しない場合は、予約全額が保持されます。有効期限が切れたというだけでは予約を解除できません。永続化に失敗した場合は、再送せずに再試行できます。

公開前に、実際に公開された連携対象の Node／skill バージョンをインストールし、実際のレジストリロックを更新してください。ローカルでパックしたソースコホートはテスト上の証拠にすぎません。以前の依存関係ロックを使って公開しないでください。

Solana の agent_history と agent_quota は、大文字と小文字を区別する正確なローカル Solana アドレス、所有者が設定したクラスター、および独立して固定されたプログラムを使用します。新しいプログラムのインデックス済み決済と保持済みレシートをリクエストします。レガシープログラムや別のクラスターは、それぞれ独立した履歴です。EVM の履歴を明示的に選択した場合は、引き続きウォレットの EVM アドレスが使用されます。