# cardzero-mcp

[![npm version](https://img.shields.io/npm/v/cardzero-mcp.svg)](https://www.npmjs.com/package/cardzero-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

MCP Server for [CardZero](https://cardzero.ai) — 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](https://www.x402.org)-protected HTTP resources (HTTP 402 paywall)
- Run [ERC-8183](https://github.com/ethereum/ERCs/pull/942) **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](https://cardzero.ai) after claiming a wallet.

## Configuration

### Claude Desktop

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

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

### Claude Code

```bash
claude mcp add cardzero -- npx -y cardzero-mcp
```

Or add to `.mcp.json` in your project:

```json
{
  "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`:

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

```bash
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](https://cardzero.ai/docs/reference/contracts)

## License

MIT