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