phantom-mcp-server

IDPHANTOM MCP Server

@phantomid/mcp-server 将 IDPHANTOM 支付封装为标准 MCP 工具，让 AI Agent 能通过 IDPHANTOM 报价、授权、提交并验证 Agent 间支付。

生产环境默认使用：

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 会泄露到 shell 历史记录和进程列表中）：

变量	用途	说明
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	漏斗	dogfood/QA 流量使用 internal（单独报告——禁止虚增交易量）；默认为 external。

如果未设置 PHANTOM_PAYER_PRIVATE_KEY，phantom_register 会以手动模式运行： 传入 payer_wallet，它会返回注册挑战和逐步签名说明。

漏斗事件（AGP-100 F1.4）

服务会在 stderr 上为每个事件输出一行 JSON，行首带有 [funnel] 前缀：

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

事件依次为：install → register_start → register_complete → first_pay → repeat。抓取这些行以构建引导漏斗 （安装 → 注册 → 首次支付 → 重复支付）。标记为 PHANTOM_FUNNEL_SOURCE=internal 的流量必须与外部 交易量分开汇总。

5 分钟内连接你的 Agent

注册可自助完成，在 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。

非敏感选项支持使用标志。付款方密钥只能通过环境变量传入 （绝不能作为标志——命令行会泄露到 shell 历史记录和进程列表中）：

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_..."
    }
  }
}

限额

生产环境的默认策略限额如下：

• 每笔支付最高 50 美元
• 每天最高 500 美元

超过这些限额的支付会被 PHANTOM ID API 拒绝。

发布

npm publish --access public