cardzero-mcp

MCP Server for CardZero — a smart-contract wallet for AI agents on Base, denominated in USDC.

Gives your AI agent the ability to:

• Create wallets and check USDC balances
• Send direct USDC payments (2% platform fee)
• Pay x402-protected HTTP resources (HTTP 402 paywall)
• Run ERC-8183 escrow Jobs for A2A service delivery (2% platform + 5% evaluator fee)
• Look up payment / job state on-chain

CardZero is the underlying API layer; this MCP wraps the REST endpoints so any MCP-aware client (Claude Desktop, Claude Code, Cursor, VS Code, …) can call them via stdio.

Prerequisites

A CardZero API Key and Wallet ID, obtained from the CardZero Dashboard after claiming a wallet.

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cardzero": {
      "command": "npx",
      "args": ["-y", "cardzero-mcp"],
      "env": {
        "CARDZERO_API_KEY": "czapi_...",
        "CARDZERO_WALLET_ID": "wallet_..."
      }
    }
  }
}

Claude Code

claude mcp add cardzero -- npx -y cardzero-mcp

Or add to .mcp.json in your project:

{
  "mcpServers": {
    "cardzero": {
      "command": "npx",
      "args": ["-y", "cardzero-mcp"],
      "env": {
        "CARDZERO_API_KEY": "czapi_...",
        "CARDZERO_WALLET_ID": "wallet_..."
      }
    }
  }
}

Cursor

Settings → MCP Servers → Add new server:

• Name: cardzero
• Command: npx -y cardzero-mcp
• Environment variables: CARDZERO_API_KEY, CARDZERO_WALLET_ID

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "cardzero": {
        "command": "npx",
        "args": ["-y", "cardzero-mcp"],
        "env": {
          "CARDZERO_API_KEY": "czapi_...",
          "CARDZERO_WALLET_ID": "wallet_..."
        }
      }
    }
  }
}

Environment Variables

Variable	Required	Description
CARDZERO_API_KEY	Yes (for tool calls)	Agent API Key (czapi_...) from CardZero Dashboard
CARDZERO_WALLET_ID	Yes (for wallet-scoped tools)	Wallet ID (wallet_...) from CardZero Dashboard
CARDZERO_API_URL	No	API base URL — default https://api.cardzero.ai/v1

The server starts and responds to tools/list even without these vars — individual tool calls then return a clean config_missing error.

Available Tools (10)

Direct payments

Tool	Description
create_wallet	Create a new CardZero wallet. Returns address + one-time claim key for the human owner. No auth required.
get_balance	Check current USDC balance of your wallet.
send_payment	Send USDC to any Ethereum address. 2% fee deducted from your wallet.
list_payments	View recent payment history.
get_payment	Look up a specific payment by ID. No auth required.

x402

Tool	Description
pay_x402	Pay for an x402-protected HTTP resource. Returns a payment header to retry the request with.

ERC-8183 Jobs (escrow / A2A service delivery)

Tool	Description
create_job	Create a Job that escrows USDC until a Provider delivers and an Evaluator approves.
fund_job	Lock the budget into escrow. Status: open → funded.
submit_job	Provider submits a deliverable. Status: funded → submitted → auto-evaluated.
get_job	Read current state (status, txs, evaluation outcome). No auth required — Job state is public.

How it works

This MCP server is a thin client that calls the CardZero REST API. It runs locally on your machine and communicates with your AI assistant over stdio. No data is stored locally.

AI Assistant (Claude / Cursor / VS Code)
  ⇅ stdio (JSON-RPC)
cardzero-mcp (local Node process)
  ⇅ HTTPS
api.cardzero.ai → Base mainnet (USDC + ERC-4337 + ERC-8004 + ERC-8183)

Development

git clone https://github.com/mrocker/cardzero-mcp.git
cd cardzero-mcp
npm install
npm run dev   # tsx-watch the source
npm run build # compile to ./dist

Resources

• Website: https://cardzero.ai
• Docs: https://cardzero.ai/docs
• API reference: https://cardzero.ai/docs/api-reference/overview
• Full LLM-friendly corpus: https://cardzero.ai/llms-full.txt
• Mainnet contracts: documented in /docs/reference/contracts

License

MIT