Clawallex MCP Server

@clawallex/mcp-server

用于 Clawallex 支付 API 的 MCP 服务。使用 USDC 支付任何费用——Clawallex 会将你的稳定币余额转换为虚拟卡，可在任何在线结账页面使用。

快速开始

1. 安装

npm install -g @clawallex/mcp-server

也可以直接通过 npx 使用（无需安装）。

2. 获取 API 凭据

在 Clawallex 注册并创建一组 API Key（api_key + api_secret）。

3. 配置你的 AI 客户端

选择你的客户端并添加配置：

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "clawallex": {
      "command": "npx",
      "args": ["@clawallex/mcp-server"],
      "env": {
        "CLAWALLEX_API_KEY": "your_api_key",
        "CLAWALLEX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Claude Code

claude mcp add --scope local clawallex -- npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret

Codex CLI

添加到你的 ~/.codex/config.toml 或 .codex/config.toml：

[mcp_servers.clawallex]
command = "npx"
args = [
  "@clawallex/mcp-server",
  "--api-key",
  "your_api_key",
  "--api-secret",
  "your_api_secret",
]

Gemini CLI

添加到你的 ~/.gemini/settings.json：

{
  "mcpServers": {
    "clawallex": {
      "command": "npx",
      "args": [
        "@clawallex/mcp-server",
        "--api-key", "your_api_key",
        "--api-secret", "your_api_secret"
      ]
    }
  }
}

OpenCode

添加到你的 opencode.json：

{
  "mcp": {
    "clawallex": {
      "type": "local",
      "command": ["npx", "@clawallex/mcp-server", "--api-key", "your_api_key", "--api-secret", "your_api_secret"],
      "enabled": true
    }
  }
}

4. 初始化连接

完成配置后，告诉你的 AI Agent：

“运行 clawallex_setup 检查连接”

clawallex_setup 会验证你的 API Key，并自动绑定一个 client_id 以隔离数据。只需执行一次。

5. 开始使用

一次性付款：

“支付 50 美元购买 OpenAI API 额度”

Agent 调用 clawallex_pay → 创建虚拟卡 → get_card_details → decrypt_card_data → 填写结账信息。

订阅：

“设置一张 100 美元的卡，用于按月支付 AWS 账单”

Agent 调用 clawallex_subscribe → 创建可充值卡 → 余额不足时调用 clawallex_refill。

6. 冒烟测试

验证一切正常：

clawallex_setup     → should show "ready" with bound client_id
get_wallet          → should return wallet balance
list_cards          → should return card list (empty if no cards yet)

常见工作流

付款流程（模式 A — 钱包余额）

1. clawallex_setup                           → verify connection & bind identity
2. get_wallet                                → check USDC balance
3. clawallex_pay({ amount, description })    → create a one-time virtual card
4. get_card_details({ card_id })             → get encrypted card data
5. decrypt_card_data({ nonce, ciphertext })  → decrypt PAN/CVV for checkout

订阅流程

1. clawallex_setup                                          → verify connection
2. get_wallet                                               → check USDC balance
3. clawallex_subscribe({ initial_amount, description })     → create reloadable card
4. get_card_details({ card_id })                            → get card number
5. clawallex_refill({ card_id, amount })                    → top up when needed

工具

高阶工具（推荐）

工具	描述
clawallex_setup	检查连接状态并绑定 Agent 身份
clawallex_pay	一次性付款——创建单次使用的虚拟卡
clawallex_subscribe	定期订阅——创建可充值卡
clawallex_refill	为订阅卡充值

身份与绑定

工具	描述
whoami	查询当前 API Key 绑定状态（只读）
bootstrap	将 client_id 绑定到此 API Key

钱包与查询

工具	描述
get_wallet	获取钱包余额和状态
get_wallet_recharge_addresses	获取链上 USDC 存款地址
list_cards	列出此 Agent 创建的虚拟卡
get_card_balance	获取卡片余额和状态
batch_card_balances	一次调用检查多张卡的余额
update_card	更新卡片风险控制（tx_limit、allowed_mcc、blocked_mcc）
get_card_details	获取卡片详情，包括风险控制、持卡人信息以及加密的 PAN/CVV
decrypt_card_data	解密 get_card_details 返回的 PAN/CVV
list_transactions	列出卡片交易，并可选择筛选条件

高级工具（x402 链上）

工具	描述
get_x402_payee_address	获取 x402 付款的链上收款地址
create_card_order	创建卡片并进行全面控制（支持模式 B 两阶段流程）
refill_card	使用 x402 或自定义幂等键为流式卡充值

CLI 选项

选项	环境变量	必需	默认值	描述
--api-key	CLAWALLEX_API_KEY	是	—	Clawallex API Key
--api-secret	CLAWALLEX_API_SECRET	是	—	Clawallex API Secret（HMAC-SHA256 签名）
--base-url	CLAWALLEX_BASE_URL	否	https://api.clawallex.com	API 基础 URL
--client-id	CLAWALLEX_CLIENT_ID	否	自动生成	Agent 身份 UUID。请参阅 Client ID 部分。
--transport	—	否	stdio	传输模式：stdio、sse、http
--port	—	否	18080	sse / http 传输使用的 HTTP 端口

CLI 参数优先于环境变量。你可以混合使用两者——例如，通过环境变量设置凭据，并通过 CLI 覆盖 --transport。

要求

• Node.js >= 22

客户端 ID

client_id 是 Agent 的稳定身份，与 API Key 相互独立。每个 /payment/* 请求都会通过 X-Client-Id 发送该 ID。

关键概念： 一个 Agent 可以拥有多个 API Key（用于轮换或撤销），但 client_id 永远不会改变。切换到新的 API Key 时，继续使用相同的 client_id — 新密钥会在首次请求时自动绑定。

数据隔离：

• 钱包：用户级别，共享 — 所有使用同一 API Key 的 Agent 都能看到相同的钱包余额
• 卡片和交易：按 client_id 隔离 — 每个 Agent 只能查看自己创建的数据

绑定规则：

• 首次使用时，clawallex_setup 会自动调用 bootstrap 绑定 client_id
• 绑定后，无法更改该 API Key 对应的 client_id（TOFU — 首次使用即信任）
• 丢失 client_id = 无法再访问在其名下创建的所有卡片

启动时的解析顺序：

1. --client-id <value> CLI 参数（长度必须 >= 36 个字符）
2. ~/.clawallex-mcp/client_ids.json 本地文件（来自之前的运行）
3. 自动生成 UUID v4 并在本地保存

建议： 在生产环境中始终显式传入 --client-id，避免依赖本地文件。

传输模式

stdio（默认 — 本地 Agent / Claude Desktop）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret

SSE（远程 Agent，兼容较旧的 MCP 客户端）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret \
  --transport sse \
  --port 18080

Agent 连接到：http://localhost:18080/sse

Streamable HTTP（推荐用于 MCP SDK 1.0+）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret \
  --transport http \
  --port 18080

Agent 连接到：http://localhost:18080/mcp

本地开发

npm install
npm run build

# List all tools (stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node dist/index.js \
    --api-key your_api_key \
    --api-secret your_api_secret \
  2>/dev/null

安全

身份验证

每个 API 请求都使用 HMAC-SHA256 签名：

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + hex(sha256(body))
X-Signature = base64(hmac_sha256(api_secret, canonical))

签名由 MCP 服务自动处理。

卡片详情加密

get_card_details 会返回包含卡号 PAN 和 CVV 的 encrypted_sensitive_data。使用 decrypt_card_data 进行解密：

1. 派生密钥：HKDF-SHA256(ikm=api_secret, info="clawallex/card-sensitive-data/v1", length=32)
2. 解密：AES-256-GCM(key, nonce, ciphertext)
3. 结果：{ "pan": "4111...", "cvv": "123" }

解密后的 PAN/CVV 绝不能显示给用户 — 只能用于填写结账表单。