{
  "markdown": "# @clawallex/mcp-server\n\nMCP Server for the [Clawallex](https://clawallex.com) payment API. Pay for anything with USDC — Clawallex converts your stablecoin balance into virtual cards that work at any online checkout.\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @clawallex/mcp-server\n```\n\nOr use directly via `npx` (no install needed).\n\n### 2. Get API Credentials\n\nSign up at [Clawallex](https://app.clawallex.com) and create an API Key pair (`api_key` + `api_secret`).\n\n### 3. Configure Your AI Client\n\nChoose your client and add the configuration:\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clawallex\": {\n      \"command\": \"npx\",\n      \"args\": [\"@clawallex/mcp-server\"],\n      \"env\": {\n        \"CLAWALLEX_API_KEY\": \"your_api_key\",\n        \"CLAWALLEX_API_SECRET\": \"your_api_secret\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Code\n\n```bash\nclaude mcp add --scope local clawallex -- npx @clawallex/mcp-server \\\n  --api-key your_api_key \\\n  --api-secret your_api_secret\n```\n\n#### Codex CLI\n\nAdd to your `~/.codex/config.toml` or `.codex/config.toml`:\n\n```toml\n[mcp_servers.clawallex]\ncommand = \"npx\"\nargs = [\n  \"@clawallex/mcp-server\",\n  \"--api-key\",\n  \"your_api_key\",\n  \"--api-secret\",\n  \"your_api_secret\",\n]\n```\n\n#### Gemini CLI\n\nAdd to your `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clawallex\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@clawallex/mcp-server\",\n        \"--api-key\", \"your_api_key\",\n        \"--api-secret\", \"your_api_secret\"\n      ]\n    }\n  }\n}\n```\n\n#### OpenCode\n\nAdd to your `opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"clawallex\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"@clawallex/mcp-server\", \"--api-key\", \"your_api_key\", \"--api-secret\", \"your_api_secret\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### 4. Initialize Connection\n\nAfter configuring, tell your AI agent:\n\n> \"Run clawallex_setup to check the connection\"\n\n`clawallex_setup` verifies your API Key and automatically binds a `client_id` for data isolation. You only need to do this once.\n\n### 5. Start Using\n\n**One-time payment:**\n\n> \"Pay $50 for OpenAI API credits\"\n\nAgent calls `clawallex_pay` → creates virtual card → `get_card_details` → `decrypt_card_data` → fills checkout.\n\n**Subscription:**\n\n> \"Set up a $100 card for AWS monthly billing\"\n\nAgent calls `clawallex_subscribe` → creates reloadable card → `clawallex_refill` when balance is low.\n\n### 6. Smoke Test\n\nVerify everything works:\n\n```\nclawallex_setup     → should show \"ready\" with bound client_id\nget_wallet          → should return wallet balance\nlist_cards          → should return card list (empty if no cards yet)\n```\n\n## Typical Flows\n\n### Payment Flow (Mode A — Wallet Balance)\n\n```\n1. clawallex_setup                           → verify connection & bind identity\n2. get_wallet                                → check USDC balance\n3. clawallex_pay({ amount, description })    → create a one-time virtual card\n4. get_card_details({ card_id })             → get encrypted card data\n5. decrypt_card_data({ nonce, ciphertext })  → decrypt PAN/CVV for checkout\n```\n\n### Subscription Flow\n\n```\n1. clawallex_setup                                          → verify connection\n2. get_wallet                                               → check USDC balance\n3. clawallex_subscribe({ initial_amount, description })     → create reloadable card\n4. get_card_details({ card_id })                            → get card number\n5. clawallex_refill({ card_id, amount })                    → top up when needed\n```\n\n## Tools\n\n### High-Level (Recommended)\n\n| Tool | Description |\n|------|-------------|\n| `clawallex_setup` | Check connection status and bind agent identity |\n| `clawallex_pay` | One-time payment — creates a single-use virtual card |\n| `clawallex_subscribe` | Recurring subscription — creates a reloadable card |\n| `clawallex_refill` | Top up a subscription card balance |\n\n### Identity & Binding\n\n| Tool | Description |\n|------|-------------|\n| `whoami` | Query current API Key binding status (read-only) |\n| `bootstrap` | Bind a client_id to this API Key |\n\n### Wallet & Query\n\n| Tool | Description |\n|------|-------------|\n| `get_wallet` | Get wallet balance and status |\n| `get_wallet_recharge_addresses` | Get on-chain USDC deposit addresses |\n| `list_cards` | List virtual cards created by this agent |\n| `get_card_balance` | Get card balance and status |\n| `batch_card_balances` | Check balances for multiple cards in one call |\n| `update_card` | Update card risk controls (tx_limit, allowed_mcc, blocked_mcc) |\n| `get_card_details` | Get card details including risk controls, cardholder info, and encrypted PAN/CVV |\n| `decrypt_card_data` | Decrypt PAN/CVV from get_card_details |\n| `list_transactions` | List card transactions with optional filters |\n\n### Advanced (x402 On-Chain)\n\n| Tool | Description |\n|------|-------------|\n| `get_x402_payee_address` | Get on-chain receiving address for x402 payments |\n| `create_card_order` | Create a card with full control (supports Mode B two-stage) |\n| `refill_card` | Refill a stream card with x402 or custom idempotency keys |\n\n## CLI Options\n\n| Option | Env Variable | Required | Default | Description |\n|--------|-------------|----------|---------|-------------|\n| `--api-key` | `CLAWALLEX_API_KEY` | Yes | — | Clawallex API Key |\n| `--api-secret` | `CLAWALLEX_API_SECRET` | Yes | — | Clawallex API Secret (HMAC-SHA256 signing) |\n| `--base-url` | `CLAWALLEX_BASE_URL` | No | `https://api.clawallex.com` | API base URL |\n| `--client-id` | `CLAWALLEX_CLIENT_ID` | No | auto-generated | Agent identity UUID. See Client ID section. |\n| `--transport` | — | No | `stdio` | Transport mode: `stdio`, `sse`, `http` |\n| `--port` | — | No | `18080` | HTTP port for `sse` / `http` transport |\n\nCLI arguments take precedence over environment variables. You can mix both — e.g. set credentials via env vars and override `--transport` via CLI.\n\n## Requirements\n\n- Node.js >= 22\n\n## Client ID\n\n`client_id` is the agent's stable identity, separate from the API Key. It is sent as `X-Client-Id` on every `/payment/*` request.\n\n**Key concept:** An agent can have multiple API Keys (for rotation/revocation), but the `client_id` never changes. When switching to a new API Key, keep using the same `client_id` — the new key auto-binds on first request.\n\n**Data isolation:**\n- **Wallet**: user-level, shared — all agents using the same API key see the same wallet balance\n- **Cards & Transactions**: `client_id`-scoped — each agent only sees data it created\n\n**Binding rules:**\n- `clawallex_setup` automatically calls `bootstrap` to bind `client_id` on first use\n- Once bound, the `client_id` cannot be changed for that API Key (TOFU — Trust On First Use)\n- Losing the `client_id` = losing access to all cards created under it\n\n**Resolution order at startup:**\n1. `--client-id <value>` CLI argument (must be >= 36 characters)\n2. `~/.clawallex-mcp/client_ids.json` local file (from a previous run)\n3. Auto-generate UUID v4 and save locally\n\n**Recommendation:** Always pass `--client-id` explicitly in production to avoid relying on the local file.\n\n## Transport Modes\n\n### stdio (default — local agent / Claude Desktop)\n\n```bash\nnpx @clawallex/mcp-server \\\n  --api-key your_api_key \\\n  --api-secret your_api_secret\n```\n\n### SSE (remote agent, compatible with older MCP clients)\n\n```bash\nnpx @clawallex/mcp-server \\\n  --api-key your_api_key \\\n  --api-secret your_api_secret \\\n  --transport sse \\\n  --port 18080\n```\n\nAgent connects to: `http://localhost:18080/sse`\n\n### Streamable HTTP (MCP SDK 1.0+ recommended)\n\n```bash\nnpx @clawallex/mcp-server \\\n  --api-key your_api_key \\\n  --api-secret your_api_secret \\\n  --transport http \\\n  --port 18080\n```\n\nAgent connects to: `http://localhost:18080/mcp`\n\n## Local Development\n\n```bash\nnpm install\nnpm run build\n\n# List all tools (stdio)\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' \\\n  | node dist/index.js \\\n    --api-key your_api_key \\\n    --api-secret your_api_secret \\\n  2>/dev/null\n```\n\n## Security\n\n### Authentication\n\nEvery API request is signed with HMAC-SHA256:\n\n```\ncanonical = METHOD + \"\\n\" + PATH + \"\\n\" + TIMESTAMP + \"\\n\" + hex(sha256(body))\nX-Signature = base64(hmac_sha256(api_secret, canonical))\n```\n\nSigning is handled automatically by the MCP server.\n\n### Card Details Encryption\n\n`get_card_details` returns `encrypted_sensitive_data` containing card PAN and CVV. Use `decrypt_card_data` to decrypt:\n\n1. Derive key: `HKDF-SHA256(ikm=api_secret, info=\"clawallex/card-sensitive-data/v1\", length=32)`\n2. Decrypt: `AES-256-GCM(key, nonce, ciphertext)`\n3. Result: `{ \"pan\": \"4111...\", \"cvv\": \"123\" }`\n\nDecrypted PAN/CVV must NEVER be displayed to the user — only used for filling checkout forms.\n",
  "bytes": 8749,
  "sha": "24c42c943dc1ef3b75a3d21ec4e6ad296c02367f268731efd1425e787b00c6e7",
  "repo_slug": "clawallex/clawallex-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_clawallex_tech_clawallex_mcp_5dee75dd/readme"
}