Clawallex MCP Server

@clavallex/mcp服务器

MCP服务器 Clawallex 支付API。使用USDC支付任何费用——Clawallex将您的稳定币余额转换为可在任何在线结账处使用的虚拟卡。

快速开始

1.安装

npm install -g @clawallex/mcp-server

或直接通过 npx （无需安装）。

2.获取API凭据

注册地址： Clawallex 并创建一个API密钥对(api_key + api_secret).

3.配置您的AI客户端

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

克劳德桌面

添加到您的 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 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/settings.json:

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

开源代码

添加到您的 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代理：

“运行clavallex_setup检查连接”

clawallex_setup 验证API密钥并自动绑定 client_id 用于数据隔离。你只需要做一次。

5.开始使用

一次性付款：

“支付50美元获得OpenAI API信用”

客服电话 clawallex_pay → 创建虚拟卡→ get_card_details → decrypt_card_data → 填写结账。

订阅：

“为AWS每月账单设置一张100美元的卡”

客服电话 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

工具

高级（推荐）

身份和绑定

钱包和查询

高级（x402链上）

CLI选项

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

需求

• Node.js>=22

客户端ID

client_id 是代理的稳定身份，独立于API密钥。它被发送为 X-Client-Id 在每一个 /payment/* 请求。

关键概念： 一个代理可以有多个API密钥（用于旋转/撤销），但是 client_id 永不改变。当切换到新的API密钥时，请继续使用相同的密钥 client_id --新密钥在第一次请求时自动绑定。

数据隔离：

• 钱包：用户级，共享-使用相同API密钥的所有代理都看到相同的钱包余额
• 卡和交易: client_id-scoped——每个代理只看到它创建的数据

绑定规则：

• clawallex_setup 自动呼叫 bootstrap 绑定 client_id 首次使用时
• 一旦绑定 client_id 无法更改该API密钥（TOFU-首次使用时信任）
• 失去 client_id =无法访问在其下创建的所有卡

启动时的解决顺序：

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

建议： 总是通过 --client-id 明确地在生产环境中使用，以避免依赖本地文件。

运输方式

stdio（默认--本地代理/Claude Desktop）

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

SSE（远程代理，与旧版MCP客户端兼容）

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

代理连接到： http://localhost:18080/sse

流式HTTP（建议使用MCP SDK 1.0+）

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

代理连接到： 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 回报 encrypted_sensitive_data 包含PAN和CVV卡。使用 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不得向用户显示，仅用于填写结账表格。