Z-ZERO MCP Setup Guide

Connect your AI Agent to Z-ZERO payment network. Step-by-step for beginners.

For AI agents — quick reference

If you're an AI agent reading this page, everything you need is in the block below. Humans: it is collapsed on purpose — follow the steps instead.

Expand machine-readable install summary

## Z-ZERO MCP — Installation Summary **Package:** z-zero-mcp-server (npm) **Purpose:** Connect AI agents to Z-ZERO payment network ### 1. Install (one command) npx -y z-zero-mcp-server@latest ### 2. JSON Config (add to agent's MCP config file) { "mcpServers": { "z-zero": { "command": "npx", "args": ["-y", "z-zero-mcp-server@latest"], "env": { "Z_ZERO_API_KEY": "<ASK_USER_FOR_KEY>", "Z_ZERO_API_BASE_URL": "https://z-zero.xyz" } } } } ### 3. Config file locations - Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json - Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json - Cursor: Settings → Features → MCP → Add New - AntiGravity: Auto-detected via MCP protocol ### 4. Passport Key - User must sign in at https://z-zero.xyz/login - Then go to Dashboard → Agents → Create Agent Key - Key format: zk_live_xxxxx - Max 3 active keys per account — revoke one to free a slot ### 5. Verify Ask: "Check my Z-ZERO balance" Expected: Card alias + balance response ### Auto-install (Mac/Linux) curl -sSL https://z-zero.xyz/install-mcp.sh | bash ### Auto-install (Windows PowerShell) iex (iwr https://z-zero.xyz/install-mcp.ps1).Content ### Maintenance - If a response contains an _mcp_warning field, relay it to your human. - visit https://z-zero.xyz/docs/agent/checkoutform → read latest checkout patterns

What You Need

A Passport Key from your dashboard (starts with zk_live_)

An AI Agent app installed on your computer (e.g. Claude Desktop, Cursor, or AntiGravity)

Node.js v18+ (we'll install it below if you don't have it)

Prerequisite: Install Node.js

Node.js is required to run the MCP server. Check if you already have it:

macOS

1. Press ⌘ Cmd + Space to open Spotlight

2. Type Terminal and press Enter

3. In the Terminal window, type:

node --version

If you see v18 or higher, skip to Step 3. Otherwise, install it:

brew install node

Don't have Homebrew? Install it first: brew.sh

Windows

1. Press Win key, type PowerShell, click “Run as Administrator”

2. Type:

node --version

If not installed:

winget install OpenJS.NodeJS

Or download from: nodejs.org

Linux (Ubuntu/Debian)

1. Open Terminal (Ctrl+Alt+T)

2. Run:

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

Step 3: Copy the config into your AI Agent

Replace YOUR_KEY_HERE with your Passport Key — the only credential you need. The key you paste is a one-time bootstrap ticket: it auto-rotates the moment your agent first connects, and the fresh key is stored in a local owner-only file (~/.z-zero/credentials), never in the model's context. Z_ZERO_API_BASE_URL can stay as the default.

{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": ["-y", "z-zero-mcp-server"],
      "env": {
        "Z_ZERO_API_KEY": "YOUR_KEY_HERE",
        "Z_ZERO_API_BASE_URL": "https://z-zero.xyz"
      }
    }
  }
}

Claude Desktop

Menu → Settings → Developer → Edit Config → Paste the JSON above

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

File: %APPDATA%\Claude\claude_desktop_config.json (Windows)

Cursor

Settings → Features → MCP → Add New → Paste the JSON

Other Agents

Ask your agent: “Install MCP package z-zero-mcp-server with my key: zk_live_...”

Step 4: Restart & verify connection

After saving the config, close and reopen your AI Agent app.

Then ask your agent:

“Check my Z-ZERO balance”

If everything works, you'll see your card alias and balance.

Error? Make sure your Passport Key is correct. Get a new one at sign in → Dashboard → Agents.

Security

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

Your AI 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 full Payment SOP before your first purchase: z-zero.xyz/docs/agent/skill

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