phantom-mcp-server

IDPHANTOM MCP サーバー

@phantomid/mcp-server は IDPHANTOM の決済機能を標準的な MCP ツールとして公開するため、AI エージェントは IDPHANTOM を通じてエージェント間決済の見積もり、承認、送信、検証を行えます。

本番環境では、次の設定がデフォルトで使用されます。

https://pay.idphantom.com

インストール

npx @phantomid/mcp-server

MCP クライアントでは、サーバーのコマンドと環境変数を設定してください。

{
  "mcpServers": {
    "phantom-id": {
      "command": "npx",
      "args": ["@phantomid/mcp-server"],
      "env": {
        "PHANTOM_API_URL": "https://pay.idphantom.com",
        "PHANTOM_API_KEY": "pk_live_..."
      }
    }
  }
}

本番環境を使用する場合、PHANTOM_API_URL は任意です。登録後に通常の有料 API を使用するには、PHANTOM_API_KEY が必要です。

セルフサービスツールの環境設定（AGP-100）

MCP ツールの phantom_register と phantom_authorize_budget は、署名鍵を環境変数からのみ読み込みます（コマンドライン引数からは読み込みません。argv はシェル履歴やプロセス一覧に漏れるためです）。

変数	使用元	目的
PHANTOM_PAYER_PRIVATE_KEY	phantom_register（自動モード）	2 USDC の登録費用を支払います。署名はローカルで行われ、プロセスの外に出ることはありません。
PHANTOM_FUNDER_PRIVATE_KEY	phantom_authorize_budget	EIP-712 の AgentWalletAuthorization に使用する、人間の資金提供者の鍵です。
PHANTOM_ROUTER_ADDRESS	両方	EIP-712 ドメインの検証コントラクトである PhantomRouter です。
PHANTOM_FUNNEL_SOURCE	ファネル	ドッグフーディング／QA トラフィックには internal を指定します（別途報告されます。自社間での取引量は許可されません）。デフォルトは external です。

PHANTOM_PAYER_PRIVATE_KEY が設定されていない場合、phantom_register は手動モードで実行されます。payer_wallet を渡すと、登録チャレンジと署名手順が返されます。

ファネルイベント（AGP-100 F1.4）

サーバーは、stderr に [funnel] をプレフィックスとして付けた JSON 形式のイベントを1行ずつ出力します。

[funnel] {"event":"install","ts":"...","source":"external",...}

イベントは install → register_start → register_complete → first_pay → repeat の順です。これらの行を収集して、オンボーディングファネル（インストール → 登録 → 初回決済 → リピート）を構築できます。PHANTOM_FUNNEL_SOURCE=internal のタグが付いたトラフィックは、外部の取引量とは分けて集計する必要があります。

5分でエージェントを接続

登録はセルフサービスで、Base メインネット上で2 USDCかかります。CLI はローカルで署名し、秘密鍵を表示することはありません。

export PHANTOM_PAYER_PRIVATE_KEY="0x..."
export PHANTOM_ROUTER_ADDRESS="0x..."
npx @phantomid/mcp-server init --name my-agent

初期化フローでは、次の処理が呼び出されます。

1. POST /v1/register
2. POST /v1/intents/:id/authorize
3. POST /v1/intents/:id/submit
4. GET /v1/register/:reference
5. POST /v1/register/:reference/claim

成功すると、アカウント ID と API キーが一度だけ表示されます。返されたキーは PHANTOM_API_KEY として保存してください。

機密情報以外のオプションにはフラグを使用できます。支払者の鍵は環境変数でのみ指定できます（フラグでは指定できません。コマンドラインはシェル履歴やプロセス一覧に漏れるためです）。

export PHANTOM_PAYER_PRIVATE_KEY="0x..."
npx @phantomid/mcp-server init \
  --api-url https://pay.idphantom.com \
  --router-address 0x... \
  --name my-agent

ツール

このサーバーは、stdio を介した改行区切り JSON-RPC をサポートしています。

quote_payment

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "quote_payment",
    "arguments": {
      "payer_wallet": "0x...",
      "recipient_wallet": "0x...",
      "asset_contract": "0x...",
      "amount": "1000000",
      "chain_id": 8453,
      "idempotency_key": "quote-001",
      "payer_agent_id": "buyer-agent",
      "recipient_agent_id": "seller-agent"
    }
  }
}

authorize_payment

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "authorize_payment",
    "arguments": {
      "payment_intent_id": "pi_...",
      "payer_signature": "0x..."
    }
  }
}

submit_payment

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "submit_payment",
    "arguments": {
      "payment_intent_id": "pi_..."
    }
  }
}

verify_payment

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "verify_payment",
    "arguments": {
      "payment_intent_id": "pi_...",
      "receipt_id": "rcpt_..."
    }
  }
}

上限

本番環境のデフォルトのポリシー上限は次のとおりです。

• 決済1件あたり最大50 USD
• 1日あたり最大500 USD

これらの上限を超える決済は、PHANTOM ID API によって拒否されます。

公開

npm publish --access public