Clawallex MCP

@clawallex/mcp-server

MCP Server for the Clawallex payment API. Pay for anything with USDC — Clawallex converts your stablecoin balance into virtual cards that work at any online checkout.

Quick Start

1. Install

npm install -g @clawallex/mcp-server

Or use directly via npx (no install needed).

2. Get API Credentials

Sign up at Clawallex and create an API Key pair (api_key + api_secret).

3. Configure Your AI Client

Choose your client and add the configuration:

Claude Desktop

Add to your 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

Add to your ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.clawallex]

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

Gemini CLI

Add to your ~/.gemini/settings.json:

{

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

OpenCode

Add to your opencode.json:

{

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

4. Initialize Connection

After configuring, tell your AI agent:

"Run clawallex_setup to check the connection"

clawallex_setup verifies your API Key and automatically binds a client_id for data isolation. You only need to do this once.

5. Start Using

One-time payment:

"Pay $50 for OpenAI API credits"

Agent calls clawallex_pay → creates virtual card → get_card_details → decrypt_card_data → fills checkout.

Subscription:

"Set up a $100 card for AWS monthly billing"

Agent calls clawallex_subscribe → creates reloadable card → clawallex_refill when balance is low.

6. Smoke Test

Verify everything works:

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)

Typical Flows

Payment Flow (Mode A — Wallet Balance)

1. clawallex_setup                           → verify connection & bind identity

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

Subscription Flow

1. clawallex_setup                                          → verify connection

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

Tools

High-Level (Recommended)

Identity & Binding

Wallet & Query

Advanced (x402 On-Chain)

CLI Options

CLI arguments take precedence over environment variables. You can mix both — e.g. set credentials via env vars and override --transport via CLI.

Requirements

• Node.js >= 22

Client ID

client_id is the agent's stable identity, separate from the API Key. It is sent as X-Client-Id on every /payment/* request.

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.

Data isolation:

• Wallet: user-level, shared — all agents using the same API key see the same wallet balance
• Cards & Transactions: client_id-scoped — each agent only sees data it created

Binding rules:

• clawallex_setup automatically calls bootstrap to bind client_id on first use
• Once bound, the client_id cannot be changed for that API Key (TOFU — Trust On First Use)
• Losing the client_id = losing access to all cards created under it

Resolution order at startup:

1. --client-id CLI argument (must be >= 36 characters)
2. ~/.clawallex-mcp/client_ids.json local file (from a previous run)
3. Auto-generate UUID v4 and save locally

Recommendation: Always pass --client-id explicitly in production to avoid relying on the local file.

Transport Modes

stdio (default — local agent / Claude Desktop)

npx @clawallex/mcp-server \

--api-key your_api_key \ --api-secret your_api_secret

SSE (remote agent, compatible with older MCP clients)

npx @clawallex/mcp-server \

--api-key your_api_key \ --api-secret your_api_secret \ --transport sse \ --port 18080

Agent connects to: http://localhost:18080/sse

Streamable HTTP (MCP SDK 1.0+ recommended)

npx @clawallex/mcp-server \

--api-key your_api_key \ --api-secret your_api_secret \ --transport http \ --port 18080

Agent connects to: http://localhost:18080/mcp

Local Development

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

Security

Authentication

Every API request is signed with HMAC-SHA256:

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + hex(sha256(body))

X-Signature = base64(hmac_sha256(api_secret, canonical))

Signing is handled automatically by the MCP server.

Card Details Encryption

get_card_details returns encrypted_sensitive_data containing card PAN and CVV. Use decrypt_card_data to decrypt:

1. Derive key: HKDF-SHA256(ikm=api_secret, info="clawallex/card-sensitive-data/v1", length=32)
2. Decrypt: AES-256-GCM(key, nonce, ciphertext)
3. Result: { "pan": "4111...", "cvv": "123" }

Decrypted PAN/CVV must NEVER be displayed to the user — only used for filling checkout forms.