Clawallex MCP Server

by clawallex

158 downloads
Not rated
GitHub

About

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.

Details

Author
clawallex
Downloads
158
Categories
Other

Jump to

- One-time payments and recurring subscriptions via virtual cards
- Wallet balance and USDC deposit address queries
- Encrypted card details (PAN/CVV) with client-side decryption
- Client ID scoping for agent data isolation
- Multiple transport modes: stdio, SSE, Streamable HTTP

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Clawallex MCP Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Install globally via npm install -g @clawallex/mcp-server or run directly with npx. Obtain API credentials from Clawallex, then configure your AI client (Claude Desktop, Claude Code, Codex CLI, Gemini CLI, OpenCode) with your API key and secret. Run the clawallex_setup tool once to verify the connection and bind a client identity.

clawallex_setup

Check current Clawallex connection status and ensure agent identity is bound. Calls whoami to verify API Key, then bootstrap to bind client_id if not yet bound. Use this after starting the MCP server to confirm everything is ready for payment operations. Returns: user_id, api_key_id, bound_client_id, client_id_bound status.

whoami

Query the current API Key binding status — read-only, does NOT modify any state. Returns: • client_id_bound=true → this API Key is already bound to a specific client_id. • client_id_bound=false → this API Key is not yet bound; call bootstrap to bind. Example response (bound): { "user_id": "u_123", "api_key_id": "ak_123", "status": 100, "bound_client_id": "ca_abc123", "client_id_bound": true } Example response (unbound): { "user_id": "u_123", "api_key_id": "ak_123", "status": 100, "bound_client_id": "", "client_id_bound": false }

bootstrap

Bind a client_id to the current API Key, or let the server generate one. This is the recommended way to establish agent identity before making payment calls. Once bound, the client_id cannot be changed for this API Key. Behavior: • API Key not yet bound + no preferred_client_id → server generates a ca_ prefixed ID. • API Key not yet bound + preferred_client_id → binds the provided value. • API Key already bound + same value (or omitted) → idempotent, returns existing binding. • API Key already bound + different value → 409 conflict. On success, the returned client_id is automatically saved locally. Example: bootstrap() → { client_id: 'ca_abc123', created: true } Example: bootstrap({ preferred_client_id: 'my-agent-uuid' }) → { client_id: 'my-agent-uuid', created: true }

get_wallet

Get the wallet details for the current API key. Each API key has exactly one wallet — shared across all agents using the same API key. Returns available_balance, frozen_balance, low_balance_threshold, currency (USD), and status. Use this to check if there is sufficient balance before creating cards (Mode A) or refilling (Mode A).

get_x402_payee_address

Get the system receiving address for x402 on-chain payments. When to use: MUST call this before Mode B Refill to obtain payee_address for payment_requirements.payTo. Not needed for Mode B card creation — the 402 quote response already includes payee_address. Common chain + token combinations: BASE + USDC, ETH + USDC. If this returns 404: the payee address for this chain/token is not initialized — try a different chain or contact support.

get_wallet_recharge_addresses

Get the on-chain deposit addresses for a wallet. Send USDC to one of these addresses to top up the wallet balance. Each address is specific to a chain (e.g. BASE) and token (e.g. USDC). For Mode B (x402) card creation/refill, the system automatically selects the acquiring address — you do not need to call this manually.

create_card_order

Advanced: create a virtual card with full control over payment mode and card type. Maps directly to POST /payment/card-orders. Most agents should use clawallex_pay or clawallex_subscribe instead. Mode A (mode_code=100): wallet balance deduction, immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 two-stage flow: Stage 1 (Quote): provide chain_code + token_code. The 402 response is EXPECTED (a quote, NOT an error). Returns: payee_address, asset_address, x402_reference_id, fee breakdown, payable_amount. Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library. Stage 2 requires the resulting signature and your wallet address (authorization.from). authorization fields: from=your wallet, to=payee_address, value=maxAmountRequired, validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth). Stage 2 (Settle): reuse SAME client_request_id + provide x402_version, payment_payload, payment_requirements, extra. - payment_requirements.payTo MUST equal payee_address from Stage 1 - payment_requirements.asset MUST equal asset_address from Stage 1 - maxAmountRequired = payable_amount × 10^decimals (USDC = 6, e.g. '207.59' → '207590000'). If settle rejected, order stays pending_payment — retry with same client_request_id. card_type: 100=flash (single-use), 200=stream (reloadable). Fee: flash = issue_fee + fx_fee; stream = issue_fee + monthly_fee + fx_fee.

list_cards

List virtual cards created by this agent (scoped to the server's client_id). Cards created by other agents using the same API key are not visible. Returns: card_id, mode_code (100=Mode A, 200=Mode B), card_type (flash/stream), status, masked PAN, balance, and expiry. Tip: check mode_code to determine refill path — Mode A uses wallet balance, Mode B uses x402 on-chain.

get_card_balance

Get the current balance and status of a virtual card. Only cards created by this agent (same client_id) are accessible. Returns available_balance, card_currency, status, and updated_at.

batch_card_balances

Check balances for multiple cards in one call.

update_card

Update card risk controls: per-transaction limit and MCC whitelist/blacklist. At least one field must be provided. Changes take effect after issuer confirms.

get_card_details

Get full card details including masked PAN, expiry, balance, cardholder info, billing address, risk controls, and encrypted sensitive data. Returns: masked_pan, expiry, balance, status, first_name, last_name, delivery_address, tx_limit, allowed_mcc, blocked_mcc, encrypted_sensitive_data. The encrypted_sensitive_data field contains PAN and CVV encrypted with AES-256-GCM. To decrypt, use the decrypt_card_data tool with the encrypted_sensitive_data object. Only cards created by this agent (same client_id) are accessible. IMPORTANT: Never display the decrypted PAN or CVV to the user. Use them only for filling checkout forms.

decrypt_card_data

Decrypt the encrypted_sensitive_data from get_card_details to obtain PAN and CVV. Input: the nonce and ciphertext fields from encrypted_sensitive_data. Output: { pan, cvv } — the full card number and security code. Decryption: HKDF-SHA256(api_secret, info='clawallex/card-sensitive-data/v1') → AES-256-GCM. SECURITY: The decrypted PAN and CVV are STRICTLY for filling checkout/payment forms. NEVER display, log, or return the raw card number or CVV to the user. NEVER include PAN/CVV in conversation text shown to the user. If the user asks to see their card number, show only the masked_pan from get_card_details.

list_transactions

List card transactions for this agent (scoped to the server's client_id). Transactions from other agents using the same API key are not visible. All filter parameters are optional — omit all to list recent transactions across all cards.

refill_card

Advanced: refill a stream card with full control over payment mode. Maps directly to POST /payment/cards/:card_id/refill. Refill mode follows the card's creation mode (cannot switch mid-life). Mode A: client_request_id as idempotency key. Mode B: no 402 challenge — caller signs the EIP-3009 authorization independently. Step 1: call get_x402_payee_address to get payee_address for payment_requirements.payTo. Step 2: sign EIP-3009 transferWithAuthorization using your own wallet/signing library. Step 3: submit with x402_reference_id as idempotency key + payment_payload (signature + wallet address) + payment_requirements. Only cards created by this agent (same client_id) can be refilled.

clawallex_pay

Pay for a product or service using USDC. Creates a single-use flash virtual card (card_type=100), deducts from wallet balance, returns card details for checkout. Mode A (mode_code=100, default): wallet balance → flash card. Immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 on-chain two-stage flow: Stage 1 (Quote): POST with mode_code=200, chain_code, token_code. The 402 response is EXPECTED — it is a quote, NOT an error. Returns: card_order_id, client_request_id, x402_reference_id, payee_address, asset_address, final_card_amount, issue_fee_amount, fx_fee_amount, fee_amount, payable_amount. Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library. Stage 2 requires the resulting signature and your wallet address (authorization.from). authorization fields: from=your wallet address, to=payee_address, value=maxAmountRequired, validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth). Stage 2 (Settle): POST again with SAME client_request_id + signed x402 data: - payment_requirements.payTo MUST equal payee_address from Stage 1 - payment_requirements.asset MUST equal asset_address from Stage 1 - payment_requirements.maxAmountRequired MUST equal payable_amount × 10^decimals (USDC = 6 decimals, e.g. '207.59' → '207590000') - payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1 - extra.card_amount MUST equal amount, extra.paid_amount MUST equal amount + fee_amount - If settle is rejected, order stays pending_payment — fix params and retry with same client_request_id. Fee structure: fee_amount = issue_fee_amount + fx_fee_amount. total_amount = amount + fee_amount. Example (Mode A): clawallex_pay({ amount: 50, description: 'OpenAI API credits' })

clawallex_subscribe

Set up a reloadable virtual card for recurring/subscription payments. Creates a stream card (card_type=200) that stays active and can be refilled via clawallex_refill. Mode A (mode_code=100, default): wallet balance → stream card. Immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. Same x402 two-stage flow as clawallex_pay. The 402 response is EXPECTED (a quote, not an error). See clawallex_pay for full Stage 1/2 details. Fee structure: fee_amount = issue_fee_amount + monthly_fee_amount + fx_fee_amount. Example: clawallex_subscribe({ initial_amount: 100, description: 'AWS monthly billing' })

clawallex_refill

Top up the balance of a subscription (stream) card. Only stream cards (card_type=200) can be refilled. Refill mode follows the card's creation mode. Mode A: deducts from wallet balance. client_request_id is the idempotency key (auto-generated if omitted). Mode B: x402 settle (no 402 challenge stage) — agent must first call get_x402_payee_address to get payee_address, then construct payment_requirements.payTo from it. Requires x402_reference_id, x402_version, payment_payload, payment_requirements. Mode B idempotency key is x402_reference_id (not client_request_id). Tip: use get_card_balance first to check current balance. Example: clawallex_refill({ card_id: 'c_123', amount: 50 })

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

@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

``bash 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: `json { "mcpServers": { "clawallex": { "command": "npx", "args": ["@clawallex/mcp-server"], "env": { "CLAWALLEX_API_KEY": "your_api_key", "CLAWALLEX_API_SECRET": "your_api_secret" } } } } `

Claude Code

`bash 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: `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: `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: `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 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 `

Subscription Flow

` 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 `

Tools

High-Level (Recommended)

| Tool | Description | |------|-------------| | clawallex_setup | Check connection status and bind agent identity | | clawallex_pay | One-time payment — creates a single-use virtual card | | clawallex_subscribe | Recurring subscription — creates a reloadable card | | clawallex_refill | Top up a subscription card balance |

Identity & Binding

| Tool | Description | |------|-------------| | whoami | Query current API Key binding status (read-only) | | bootstrap | Bind a client_id to this API Key |

Wallet & Query

| Tool | Description | |------|-------------| | get_wallet | Get wallet balance and status | | get_wallet_recharge_addresses | Get on-chain USDC deposit addresses | | list_cards | List virtual cards created by this agent | | get_card_balance | Get card balance and status | | batch_card_balances | Check balances for multiple cards in one call | | update_card | Update card risk controls (tx_limit, allowed_mcc, blocked_mcc) | | get_card_details | Get card details including risk controls, cardholder info, and encrypted PAN/CVV | | decrypt_card_data | Decrypt PAN/CVV from get_card_details | | list_transactions | List card transactions with optional filters |

Advanced (x402 On-Chain)

| Tool | Description | |------|-------------| | get_x402_payee_address | Get on-chain receiving address for x402 payments | | create_card_order | Create a card with full control (supports Mode B two-stage) | | refill_card | Refill a stream card with x402 or custom idempotency keys |

CLI Options

| Option | Env Variable | Required | Default | Description | |--------|-------------|----------|---------|-------------| | --api-key | CLAWALLEX_API_KEY | Yes | — | Clawallex API Key | | --api-secret | CLAWALLEX_API_SECRET | Yes | — | Clawallex API Secret (HMAC-SHA256 signing) | | --base-url | CLAWALLEX_BASE_URL | No | https://api.clawallex.com | API base URL | | --client-id | CLAWALLEX_CLIENT_ID | No | auto-generated | Agent identity UUID. See Client ID section. | | --transport | — | No | stdio | Transport mode: stdio, sse, http | | --port | — | No | 18080 | HTTP port for sse / http transport | 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 <value> 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)

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

SSE (remote agent, compatible with older MCP clients)

`bash 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)

`bash 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

``bash npm install npm run build
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other