What this playbook is and is not

If you have built an MCP server that exposes useful tools to AI agents and you are looking at the bill from the upstream APIs it calls, you already know why monetization matters. The cheap-to-run servers are happy to stay free. The ones doing real work, calling premium APIs, running expensive models, hitting rate limits because everyone uses them - those need a revenue side or they shut down.

This is the playbook for adding paid tools to an existing MCP server in an afternoon. We will gate a single premium tool with the x402 protocol, wire a Redis receipt cache, deploy, and walk through the first-day operator metrics. The complete reference shape lives at /use-cases/mcp-server-operators; this post is the inline-code version.

What this playbook is not: a Stripe-style subscription billing tutorial. MCP servers monetize differently. The unit is the tool call, not the user, and the payer is usually an agent, not a human. If you try to wrap an MCP server in a SaaS-shaped product (signup flow, dashboard, monthly invoice), you build the wrong thing. The paid MCP tool is the right primitive.

The shape of a paid MCP tool

Before any code, the architecture in one paragraph: an MCP server exposes tools. A free tool returns a 200 with its result. A paid tool returns a 402 with a payment URL and a price the first time it is called by a given caller. The caller's agent wallet settles the payment, gets back a receipt, and retries the call with the receipt attached. The server validates the receipt and runs the tool. From the agent's planner's perspective, nothing changes except a slight delay on the first call to each tool per session.

You do not need to understand crypto, gas, or chain mechanics to operate this. The protocol gives you a "pay this URL, get back a receipt" abstraction. Whatever happens behind the URL is the wallet provider's problem.

Prereqs

Before the code:

• A working MCP server using the official Model Context Protocol SDK in TypeScript or Python. If you do not have one, scaffold from the upstream template first.
• A Blockchain0x account (free signup at wallet.blockchain0x.com/signup) with an agent profile.
• An API key. Use sk_test_ for this guide so you can exercise the full flow on Base Sepolia before flipping live.
• Redis or another shared key-value store for the receipt cache. Optional in dev, required in prod.
• A clear sense of which tool you want to monetize and what to charge. We will use $0.005 per call as a working number for a hypothetical realtime-quotes tool. Tune from your own COGS.

Step 1: install the middleware

The Blockchain0x MCP middleware exposes a single helper - requirePayment in Node, require_payment in Python - that wraps any tool handler. It handles the 402 response, the receipt validation, and the cache lookup.

Node:

npm install @blockchain0x/sdk @blockchain0x/mcp

Python:

pip install blockchain0x blockchain0x-mcp

No other dependencies. If your server already uses Redis, you already have the receipt-store dependency in your tree.

Step 2: gate a single tool

We will gate one premium tool first. The pattern is to wrap the existing handler. Everything else on the server stays free.

TypeScript:

import { Server } from "@modelcontextprotocol/sdk/server";
import { requirePayment } from "@blockchain0x/mcp";

const server = new Server({ name: "premium-data-mcp", version: "1.0.0" });

server.tool(
  "get_quote_realtime",
  { ticker: { type: "string" } },
  requirePayment(
    {
      agentId: process.env.BLOCKCHAIN0X_AGENT_ID!,
      apiKey: process.env.BLOCKCHAIN0X_API_KEY!,
      priceUsdc: "0.005",
      reason: "Real-time quote",
    },
    async ({ ticker }, { receipt }) => {
      // 'receipt' is set only after the caller has paid.
      const quote = await fetchLiveQuote(ticker);
      return { content: [{ type: "text", text: JSON.stringify(quote) }] };
    },
  ),
);

Python:

from mcp.server import Server
from blockchain0x_mcp import require_payment
import os, json

server = Server("premium-data-mcp", version="1.0.0")

@server.tool(
    "get_quote_realtime",
    schema={"ticker": {"type": "string"}},
)
@require_payment(
    agent_id=os.environ["BLOCKCHAIN0X_AGENT_ID"],
    api_key=os.environ["BLOCKCHAIN0X_API_KEY"],
    price_usdc="0.005",
    reason="Real-time quote",
)
async def get_quote_realtime(ticker: str, receipt):
    # 'receipt' is set only after the caller has paid.
    quote = await fetch_live_quote(ticker)
    return [{"type": "text", "text": json.dumps(quote)}]

That is the whole change for one tool. The first call from any new caller now returns a 402 looking like this:

{
  "error": {
    "code": "payment_required",
    "message": "Payment required for tool 'get_quote_realtime'",
    "payment": {
      "amount_usdc": "0.005",
      "hosted_url": "https://wallet.blockchain0x.com/.../pay/pr_01J9R6Y",
      "expires_at": "2026-05-15T09:30:00Z"
    }
  }
}

The agent's wallet runtime hits the URL, settles the payment in USDC on Base, and retries the same MCP call with the receipt attached. The wrapped handler now sees receipt populated and runs the underlying fetchLiveQuote(ticker).

Step 3: add a shared receipt cache

By default, requirePayment keeps validated receipts in process memory. That is fine for development - one server instance, one in-memory cache. In production you run multiple instances behind a load balancer, and a paying caller who hits instance A on the first call should not be charged again when their next call hits instance B. Plug in a shared store.

TypeScript:

import { requirePayment, createRedisReceiptStore } from "@blockchain0x/mcp";
import IORedis from "ioredis";

const redis = new IORedis(process.env.REDIS_URL!);

const paid = requirePayment({
  agentId: process.env.BLOCKCHAIN0X_AGENT_ID!,
  apiKey: process.env.BLOCKCHAIN0X_API_KEY!,
  priceUsdc: "0.005",
  reason: "Real-time quote",
  // Cache receipts so a caller who paid once does not 402 again until the
  // receipt window expires.
  receiptStore: createRedisReceiptStore(redis, { ttlSeconds: 3600 }),
});

Python:

from blockchain0x_mcp import require_payment, RedisReceiptStore
from redis.asyncio import Redis
import os

redis = Redis.from_url(os.environ["REDIS_URL"])

paid = require_payment(
    agent_id=os.environ["BLOCKCHAIN0X_AGENT_ID"],
    api_key=os.environ["BLOCKCHAIN0X_API_KEY"],
    price_usdc="0.005",
    reason="Real-time quote",
    receipt_store=RedisReceiptStore(redis, ttl_seconds=3600),
)

The TTL is the only knob worth thinking about. It controls how long a paying caller gets free re-access before being charged again. The right answer depends on the tool:

One hour is the default we recommend if you have no specific reason to choose otherwise.

Step 4: charge differently for different inputs

A common reality check at this point: not every call costs the same on your side. A web-crawl tool that fetches one page costs less than one that fetches a hundred. A translation tool that handles 100 words costs less than one that handles 5,000. A flat per-call price means you lose money on big inputs and overcharge for small ones.

The middleware supports a price function. The wallet's spend policy checks the quoted price before settling, so dynamic pricing remains safe as long as the price is explicit:

TypeScript:

requirePayment(
  {
    agentId: process.env.BLOCKCHAIN0X_AGENT_ID!,
    apiKey: process.env.BLOCKCHAIN0X_API_KEY!,
    // Price function receives the same args your handler will get.
    priceUsdc: ({ urls }) => {
      const n = Array.isArray(urls) ? urls.length : 1;
      return (0.001 * n).toFixed(3);
    },
    reason: "Web crawl",
  },
  async ({ urls }, { receipt }) => {
    const results = await Promise.all(urls.map(fetchAndParse));
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  },
);

Python:

@require_payment(
    agent_id=os.environ["BLOCKCHAIN0X_AGENT_ID"],
    api_key=os.environ["BLOCKCHAIN0X_API_KEY"],
    price_usdc=lambda args: f"{0.001 * max(1, len(args.get('urls', [])) ):.3f}",
    reason="Web crawl",
)
async def crawl(urls: list[str], receipt):
    results = await asyncio.gather(*(fetch_and_parse(u) for u in urls))
    return [{"type": "text", "text": json.dumps(results)}]

The caller sees the quoted price in the 402 response and can decide to pay or refuse based on its own spend policy. Most agent wallets will refuse a quote that exceeds the agent's per-call cap, so unreasonable prices simply fail rather than cause silent overspend.

Step 5: deploy

The deploy is a normal MCP server deploy. The new dependencies (@blockchain0x/sdk, @blockchain0x/mcp, Redis client) are conventional and your existing deploy story handles them. The only new operational pieces:

• BLOCKCHAIN0X_AGENT_ID and BLOCKCHAIN0X_API_KEY env vars. Store the API key in your secret manager, not in .env files committed to git.
• A boot-time check that the key prefix matches the environment - sk_test_ in dev, sk_live_ in prod. Mixing them silently is the most common production incident.
• The Redis URL. Existing Redis works; no new infrastructure needed if you have it.

// Boot-time guard - fail fast on key/env mismatch.
const apiKey = process.env.BLOCKCHAIN0X_API_KEY!;
const env = process.env.NODE_ENV;

if (env === "production" && apiKey.startsWith("sk_test_")) {
  throw new Error("Test key in production environment - aborting boot.");
}
if (env !== "production" && apiKey.startsWith("sk_live_")) {
  throw new Error("Live key in non-production environment - aborting boot.");
}

Ship the new version. Free tools keep returning 200. The gated tool now returns 402 on first call. Existing free traffic is untouched.

Step 6: the first 24 hours

The day-one operator metrics divide cleanly into three signals. Watch each.

Signal one: the 402 rate. This is the count of payment_required responses your server emits per hour. It is the top of your funnel. If you expected the gated tool to see meaningful traffic and the 402 count is low, the tool is not getting called - go look at why. If the 402 count is huge, the tool is popular; you have demand.

Signal two: the conversion rate. What fraction of 402 responses convert to a successful retry within 60 seconds? In a healthy deployment this number is 60-90 percent. Below 20 percent typically means one of three things:

• Your price is wrong (too high relative to value).
• The agents calling you do not have wallet credit configured.
• Your 402 response is malformed and the agent runtimes cannot parse it (rare, but check the format if you suspect this).

A first-week test is to raise and lower the price by 50 percent and watch the conversion curve. The right price is the one that maximizes (price × conversion × volume).

Signal three: the receipt-cache hit rate. Of all paid invocations (retries with receipt), what fraction hit a cached receipt versus a fresh one? In a healthy deployment with the recommended TTL, the cache hit rate is 70-95 percent. If it is below 50 percent, your TTL is too short - paying clients are being re-charged unnecessarily, which is a bad experience and slows them down. If it is 99 percent, your TTL might be too long for the kind of data you serve - investigate whether you are leaving revenue on the table.

Five mistakes that bite first-time MCP monetizers

The most common things to go wrong in the first week, in rough order of frequency.

Gating the free tools by accident. It is tempting to wrap every tool with requirePayment "just in case". Do not. Free tools coexisting with paid tools is the whole point - clients can use discovery, metadata, and cheap tools for free and pay only for the expensive ones. Gate selectively.

Charging a flat price for variable-cost work. Covered above. Use a price function for any tool where input size drives cost.

Not caching receipts in production. Without a shared receipt store, the same paying caller hits a 402 on every call because their previous receipt is in a different replica's memory. The fix is one extra import and config line. Skipping it is the most common cause of "but I paid!" complaints in the first week.

Trusting the client's claim of payment. Receipts are validated against Blockchain0x's API. Do not be tempted to "speed things up" by trusting an X-Receipt: ok header the client supplies. A malicious client can forge that. The middleware handles validation correctly; do not bypass it in a custom wrapper.

No metrics on paid-tool latency. Adding a payment step adds latency to first-call-per-receipt-window. Instrument both the paid path and the cached path separately so you can tell "tool is slow" from "settlement is slow" when a customer complains. Without the metric you will misdiagnose the bottleneck for hours.

What to ship today

The shortest version of this playbook is six lines:

1. npm install @blockchain0x/sdk @blockchain0x/mcp (or pip equivalent).
2. Wrap one premium tool handler with requirePayment and a price.
3. Plug in a Redis receipt store with ttlSeconds: 3600.
4. Add the boot-time key/env guard so you cannot deploy test keys to prod.
5. Deploy.
6. Watch the three signals (402 count, conversion, cache hit) for the first 24 hours.

That is the entire path from free to paid MCP server. For a deeper dive on the protocol mechanics, see the x402 glossary entry. For the broader use-case framing - what agents look like as buyers of MCP tools, what kinds of tools monetize well, how to position your server in the agent ecosystem - the MCP server operators page is the canonical reference.

Your free MCP server has been giving away the most expensive thing you operate. Now it can stop.