Skip to main content
Glama

cardzero-mcp

npm version License: MIT

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.

Related MCP server: x402tools MCP Server

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

License

MIT

Available Tools

10 tools
create_jobA

Create a Job that escrows USDC payment until a Provider delivers and an Evaluator approves. Use this for A2A service delivery (vs send_payment for direct transfers). Confirm budget + provider with user first. Provider must have a CardZero wallet (Sprint 9 MVP requirement).

Inputs: providerAddress (required), budgetUsdc (required), expiredAt (required), title (required), +3 more.

create_walletA

Create a new CardZero wallet. Returns a wallet address and one-time claim key for the human owner. No authentication required.

Inputs: name.

fund_jobA

Fund a Job created via create_job. Locks the budget USDC into escrow. Requires that the Job is in 'open' state. Two on-chain operations: USDC.approve(jobs) + Jobs.fund. Status: open → funded.

Inputs: jobId (required).

get_balanceA

Check the current USDC balance of your CardZero wallet.

Inputs: no named parameters.

get_jobA

Get the current state of a Job (status, budget, transactions, evaluation outcome). No authentication required — Job state is public.

Inputs: jobId (required).

get_paymentA

Check the status of a specific payment by its ID. No authentication required.

Inputs: paymentId (required).

list_paymentsB

View recent payment history for your CardZero wallet.

Inputs: limit, offset.

pay_x402A

Pay for an x402-protected HTTP resource (HTTP 402 Payment Required). Use after receiving a 402 response. Returns a paymentHeader to include in the retry request as X-PAYMENT header.

Inputs: url (required), maxAmount (required), recipient (required), network, +2 more.

send_paymentA

Send a USDC payment to any Ethereum address. A 2% service fee is deducted automatically from your wallet. Confirm amount and recipient with the user before calling.

Inputs: to (required), amount (required), memo, idempotencyKey.

submit_jobA

Submit a deliverable for a Job (Provider side). Posts the deliverable hash on-chain; Evaluator then auto-approves or rejects. Status: funded → submitted.

Inputs: jobId (required), contentHash (required), contentURI.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    Tools have distinct purposes overall, but send_payment and pay_x402 both involve sending payments, potentially causing slight confusion. Descriptions help differentiate them.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores, e.g., create_job, get_balance, send_payment. No mixing of styles.

    Tool Count5/5

    10 tools cover the core wallet and job escrow functionality without being excessive or insufficient for the stated purpose.

    Completeness4/5

    Core workflows are covered, but missing tools like list_jobs or cancel_job could hinder full lifecycle management. Minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with 10 pay-per-call utility tools (QR generation, DNS lookup, OCR, etc.) using USDC on Base via the x402 protocol, with agent's private key never leaving the agent.
      11
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to check their wallet address and USDC balance, preview the cost of an x402 call, and pay for API requests in USDC on Base without an account or API key. Spend caps, allow-lists and blocked contracts are enforced in code before anything is signed, so a prompt injection cannot bypass them.
      1
      MIT