DOCS
SETUP GUIDE · FOR HUMANS

Connect your agent to Z-ZERO

Four steps. Sign in first — your dashboard then carries a checklist that ticks each one off as you go.

  1. 1. Fund your wallet
  2. 2. Create a Passport Key
  3. 3. Connect your agent
  4. 4. Give it a first task
For AI agents — machine-readable install summary
## Z-ZERO MCP — install summary (for agents)

Package: z-zero-mcp-server (npm). Needs Node.js 18+.

### Config (JSON apps)
{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": [
        "-y",
        "z-zero-mcp-server@latest"
      ],
      "env": {
        "Z_ZERO_API_KEY": "<ASK_USER_FOR_KEY>"
      }
    }
  }
}

### Where it goes
- Claude app, Chat (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json — the human must quit (⌘Q) and reopen Claude
- Claude app, Chat (Windows): %APPDATA%\Claude\claude_desktop_config.json
- Claude Code: claude mcp add z-zero --scope user -e Z_ZERO_API_KEY=<KEY> -- npx -y z-zero-mcp-server@latest
- Codex: ~/.codex/config.toml → [mcp_servers.z-zero] with command = "npx", args = ["-y", "z-zero-mcp-server@latest"], env = { Z_ZERO_API_KEY = "<KEY>" }
- Antigravity: ~/.gemini/antigravity/mcp_config.json (same JSON)
- Cursor: ~/.cursor/mcp.json (same JSON)

### Passport Key
- Your human signs in at https://z-zero.xyz/login → Dashboard → AI Agents (Keys) → Create Agent Key
- Format: zk_live_… · max 3 active keys per account
- A key pasted into the chat is a one-time bootstrap ticket: it rotates the moment the MCP first connects. Write it into the config env, never repeat it back.

### Verify
Call check_balance.

### Before the first purchase
Read https://z-zero.xyz/docs/agent/skill
If a response carries an _mcp_warning field, relay it to your human.

Before you start

A computer with one of these apps: the Claude app, Claude Code, Codex, Antigravity or Cursor. Each of them runs Z-ZERO through Node.js 18 or newer.

Check or install Node.js

Open a terminal (Mac: ⌘ Space, type Terminal) and run node --version. v18 or higher: you're set. Otherwise install the LTS version from nodejs.org, or:

macOS (Homebrew)

brew install node

Windows (PowerShell)

winget install OpenJS.NodeJS

Linux (Ubuntu / Debian)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

STEP 1

Fund your wallet

Sign in with Google. Your Base wallet is created the moment you do; its address is on the Overview. Send USDC on the Base network (chain 8453) to it from any exchange or wallet — the balance shows up within about two minutes.

Send only USDC, and only on Base. Anything else sent to this address may not be recoverable.

STEP 2

Create a Passport Key

On the dashboard, open AI Agents (Keys) and click Create Agent Key. Name it after your agent and set a monthly limit — the agent can never spend past it, and you can revoke the key there at any time.

Up to three active keys per account. One key works on one machine.

STEP 3

Connect your agent

Pick the app your agent runs in. Easiest: the dashboard's Agents page shows these same instructions with your key already filled in — here it reads YOUR_PASSPORT_KEY.

Claude app

Open Settings → Developer → Edit Config, add the z-zero entry under mcpServers and save. Then quit Claude fully (⌘Q) and reopen it.

claude_desktop_config.json

{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": [
        "-y",
        "z-zero-mcp-server@latest"
      ],
      "env": {
        "Z_ZERO_API_KEY": "YOUR_PASSPORT_KEY"
      }
    }
  }
}

The file lives at ~/Library/Application Support/Claude/ on a Mac and %APPDATA%\Claude\ on Windows.

Claude Code

The Code tab in the Claude app, or Claude Code in a terminal. Paste this and it installs itself:

Paste into Claude Code

Set up Z-ZERO payments for me: read https://z-zero.xyz/agent.md and add the Z-ZERO MCP server to this app's config. My Passport Key: YOUR_PASSPORT_KEY

Or run it yourself

claude mcp add z-zero --scope user -e Z_ZERO_API_KEY=YOUR_PASSPORT_KEY -- npx -y z-zero-mcp-server@latest

Codex

Paste this into Codex and it installs itself:

Paste into Codex

Set up Z-ZERO payments for me: read https://z-zero.xyz/agent.md and add the Z-ZERO MCP server to this app's config. My Passport Key: YOUR_PASSPORT_KEY

Or add to ~/.codex/config.toml

[mcp_servers.z-zero]
command = "npx"
args = ["-y", "z-zero-mcp-server@latest"]
env = { Z_ZERO_API_KEY = "YOUR_PASSPORT_KEY" }

Antigravity

Paste this into the Antigravity agent and it installs itself:

Paste into Antigravity

Set up Z-ZERO payments for me: read https://z-zero.xyz/agent.md and add the Z-ZERO MCP server to this app's config. My Passport Key: YOUR_PASSPORT_KEY

Or add to ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": [
        "-y",
        "z-zero-mcp-server@latest"
      ],
      "env": {
        "Z_ZERO_API_KEY": "YOUR_PASSPORT_KEY"
      }
    }
  }
}

Cursor

The Agents page has a one-click Add to Cursor button. Or add this yourself:

~/.cursor/mcp.json

{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": [
        "-y",
        "z-zero-mcp-server@latest"
      ],
      "env": {
        "Z_ZERO_API_KEY": "YOUR_PASSPORT_KEY"
      }
    }
  }
}

Check it worked: ask your agent “Check my Z-ZERO balance.” It answers with your balance, and the dashboard ticks “Connect your agent”.

One key = one machine. The key you paste rotates itself the moment your agent connects, so a copy left in a chat is already dead. Connecting a different machine with the same key disconnects the first.

STEP 4

Give it a first task

Start small. Paste this into your agent and fill in the brackets:

Buy [item] from [store link]. Spend at most $[amount] and show me the total before you pay.
  • A single-use card is issued for that purchase only, funded to the amount — up to $50 per card and $100 a day in total, plus a $0.10 fee per card.
  • The card number is typed in by an isolated executor. It never enters the model's context.
  • Every card and payment shows up under Transactions.

Before its first purchase, your agent should read the Payment SOP.

If something doesn't work

I sent USDC but the balance hasn't moved.
Give it about two minutes, then reload the Overview. Check it went out as USDC on the Base network (chain 8453) to the address shown there. Still nothing: write to hung@z-zero.xyz with the transaction hash.
My agent can't find the Z-ZERO tools.
Restart the app completely — for the Claude app, quit with ⌘Q, not just the window. Then check node --version shows v18 or newer, and that the config file is still valid JSON; a missing comma is the usual culprit.
My agent says the key is invalid.
The key was revoked, or the same key was connected on another machine — that rotates it and cuts the first one off. Create a new key on the Agents page and tell your agent: “Switch my Z-ZERO key to zk_live_…”
Anything else.
hung@z-zero.xyz — say which app your agent runs in and what it answered.

Security

One credential. The Passport Key is the only credential you configure — there is no second key to find or manage.

Your agent never sees real card numbers — the card number never enters the model's context.

Card payments use single-use tokens that self-destruct.

Purchases run inside the spending limit you set, after one explicit approval.

AI agent? Read the Payment SOP before your first purchase: z-zero.xyz/docs/agent/skill

Package: npmjs.com/package/z-zero-mcp-server