Model Context Protocol Integration

Zero MCP Server

Accept micropayments in your MCP tools. AI agents pay per call.

The Model Context Protocol (MCP) lets AI agents use tools. Zero adds a payment layer — tools can charge per use, and agents auto-pay. No subscriptions, no API keys, no invoices. Just frictionless value exchange at machine speed.

01 How It Works

1
Agent calls MCP tool
The AI agent discovers and invokes a tool via the Model Context Protocol, passing the required parameters.
2
Tool returns payment_required
Instead of executing, the tool responds with a Zero address and the amount required to proceed.
3
Agent sends Z payment
The agent's wallet automatically sends the requested amount to the tool's Zero address.
4
Agent resubmits with payment proof
The agent re-calls the tool, this time including the transaction hash as proof of payment.
5
Tool executes and returns result
The tool verifies the payment on-chain, executes the request, and returns the result to the agent.

02 MCP Server Implementation

Build an MCP server that charges per tool call. The server returns a payment_required response on the first call, then verifies the payment and executes on the second.

server.py Python 
from zero import ZeroWallet
from mcp import Server

server = Server("paid-search")
wallet = ZeroWallet.from_env()

@server.tool("web_search")
async def web_search(query: str, zero_payment: str = None):
    """Search the web. Costs 0.10 Z per query."""

    if not zero_payment:
        return {
            "error": "payment_required",
            "network": "zero",
            "address": wallet.address,
            "amount": 10,
            "description": "Web search query"
        }

    verified = await wallet.verify_payment(
        tx_hash=zero_payment,
        min_amount=10,
        from_any=True
    )

    if not verified:
        return {"error": "payment_invalid"}

    return {"results": await do_search(query)}

03 MCP Client Implementation

Agents use the Zero-aware MCP client to automatically handle payment flows. The client detects payment_required responses, sends payment, and retries — all transparently.

client.py Python 
from zero.mcp import ZeroPaidClient

# Create a client with spending limits
client = ZeroPaidClient(
    wallet=my_wallet,
    max_per_call=100,       # max 1.00 Z per tool call
    max_per_session=1000   # max 10.00 Z per session
)

# Tool calls auto-pay when needed
result = await client.call_tool("web_search", {"query": "test"})
# 1. Calls tool -> gets payment_required
# 2. Sends Z to tool's address
# 3. Retries with tx hash -> gets result

04 x402 HTTP Integration

The same payment pattern extends to standard HTTP APIs using the x402 protocol. Servers return 402 Payment Required, clients pay and retry automatically.

Server Side

api_server.py Python 
from zero.x402 import paywall

@app.get("/api/search")
@paywall(amount=10, address="zr_merchant")
async def search(q: str):
    return do_search(q)

Client Side

api_client.py Python 
from zero.x402 import HttpClient

client = HttpClient(wallet=w)
result = client.get("https://api.example.com/search?q=test")
# Auto-handles 402 -> pays -> gets response

05 Pricing Examples

Tools set their own prices. Here are some common use cases and typical costs.

Tool Cost USD Equivalent
Web search 0.10 Z $0.001
Image generation 1.00 Z $0.01
Code execution 0.50 Z $0.005
Data query 0.05 Z $0.0005
Premium API call 5.00 Z $0.05

06 Spending Limits

Control how much agents can spend. Set limits per transaction, per minute, per hour, or per day. No surprises.

limits.py Python 
wallet.set_limits(
    per_transaction=25,       # max 0.25 Z per tx
    per_minute=100,          # max 1.00 Z per minute
    per_hour=1000,           # max 10.00 Z per hour
    per_day=10000,           # max 100.00 Z per day
    auto_refill=False       # don't auto-refill from main wallet
)

07 Quick Start

Get up and running in under a minute.

1

Install the SDK

Add the Zero SDK to your project.

pip install zero-sdk
2

Set your key

Export your Zero wallet key as an environment variable.

export ZERO_KEY="your_key"
3

Add to your MCP server

Import ZeroWallet and add payment checks to your tool handlers. See the server example above.

4

Agents auto-pay

Any Zero-enabled agent can now discover and pay for your tools automatically. No configuration needed on their end.