What the integration covers

The Blockchain0x MCP integration is the official bridge between Blockchain0x agent wallets and the Model Context Protocol's tool layer, viewed from the perspective of the MCP server that wants to be paid. It adds four capabilities to a free MCP server: per-tool gating with HTTP 402 responses, server-side receipt validation, a receipt cache that survives multi-instance deployments, and a clean coexistence of free and paid tools on the same server.

The integration's design principle is that the MCP server already knows how to expose tools; the integration only adds the payment-required response and the receipt-acceptance path. Everything else - transport, schemas, descriptions, agent-side discovery - keeps working unchanged. This LP is the integration-cluster reference; the task-oriented walkthrough is how-to-add-payments-to-mcp-server, and the strategy / pricing framing is how-to-monetize-mcp-server. The MCP integration page is the canonical reference.

Compatibility matrix

What works today:

What is not yet supported:

• Tools that bypass the MCP server.tool registration and stream raw bytes - those need direct integration with the Blockchain0x payment API.
• Subscriptions and recurring billing - the model is per-tool-call. For human-driven subscription access, layer Stripe on top via the dual-auth pattern.

Surface area in one screen

The complete integration on a single tool fits in roughly 20 lines:

import { Server } from "@modelcontextprotocol/sdk/server";
import { requirePayment, createRedisReceiptStore } from "@blockchain0x/mcp";
import IORedis from "ioredis";

const redis = new IORedis(process.env.REDIS_URL!);
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",
      receiptStore: createRedisReceiptStore(redis, { ttlSeconds: 3600 }),
    },
    async ({ ticker }, { receipt }) => {
      const quote = await fetchLiveQuote(ticker);
      return { content: [{ type: "text", text: JSON.stringify(quote) }] };
    },
  ),
);

Python's shape is structurally identical (@server.tool + @require_payment + Redis-backed store). The full code with both languages and the 402-response shape is in how-to-add-payments-to-mcp-server.

Server-side receipt validation

The most important property of the integration is that the server never trusts the client about whether the client has paid. Every receipt the wrapper accepts is validated either against the local cache (which holds receipts the wrapper itself validated against Blockchain0x earlier) or against Blockchain0x's API directly. A client cannot mint a fake receipt locally and present it; the API confirms the receipt was issued for the right agent, for the right tool, for at least the quoted price, and has not been revoked.

This matters because the alternative - "trust the client's claim of payment to avoid network round trips" - is the single most common way for paid-API integrations to bleed revenue. The wrapper's strict validation is exactly the discipline a SaaS billing webhook requires; if you write a custom path around the wrapper, do not skip the validation step.

The cache makes the validation fast in steady state. First call against a paying agent: one network round trip to Blockchain0x to validate. All subsequent calls within the TTL window: in-memory or Redis lookup, ~1ms. The trade-off between cache TTL and revenue is tunable per tool (volatile data wants short TTLs, reference data wants long).

What the integration does not touch

The integration stays narrow. These pieces of your MCP server are unaffected:

• Transport. Stdio, Streamable HTTP, SSE - all work the same way.
• Tool registration. The way you call server.tool(...) is unchanged.
• Tool schemas. The input and output schemas pass through.
• Tool descriptions. What you write is what the agent's planner reads; the wrapper does not modify the description.
• Free tools. Unwrapped tools return 200 directly with no wrapper involvement.
• Server-side telemetry. Logs, traces, metrics from your existing observability stack continue to work; the wrapper exposes its own logging hooks that integrate alongside.
• Server identity. Your existing process model, authentication of admin endpoints, deployment infrastructure - none of it changes.

When this is the right integration

Three scenarios where the MCP integration is the right pick over alternatives.

You operate an MCP server where some tools have real upstream cost. Premium data, paid LLMs, expensive compute. The integration converts each call into a wallet-settled transaction without needing a billing portal, a Stripe account, or per-agent signup. The unit economics finally work because the agent pays at call time, not after a sales cycle.

You want monetization to be invisible to free users. The server keeps returning 200 on free tools the same way it always did. Paid tools 402 cleanly; clients with wallets settle silently. Clients without wallets get a useful, machine-readable "payment required" signal rather than a misleading 401 or generic error.

You want a single billing surface for many agent buyers. Without the integration, every agent that wants to use your premium tool has to onboard through your auth flow. With the integration, any agent runtime that speaks x402 - regardless of who built it, how it onboarded its user, what cloud it runs in - can pay your server. The integration is many-to-one by default.

Alternatives where the MCP integration is not the right pick: a tool that costs zero (gate adds friction without revenue), a server where agents are the same legal entity as the operator (internal use, no payment needed), a B2B sale where the customer is one named org buying a contract (Stripe + a contract is faster).

Pricing and tier choices

The integration is free. The wallet API tier you pick for the MCP server's agent profile (Free, Pro, Business) determines transaction-fee rates and feature unlocks - see /pricing/ for the breakdown. The Free tier supports gating, basic spend policy, and email verification on the agent's public profile, with a 5% transaction fee. Pro unlocks GitHub + domain verification badges (which materially improve counterparty trust on agent-marketplace listings), custom branding on the public profile, full webhook event types, and a 2% transaction fee. Business adds the audit log with hash-chain tamper-evidence, advanced spend-policy controls, and priority support.

For a brand-new MCP server, Free is enough to validate that monetization works. The crossover point where Pro pays for itself is around $400-500/month of transaction volume on the server's agent profile - the same crossover as the LangChain integration's tier math, because the underlying fee schedule is identical. Most MCP servers that earn revenue at all cross that line within their first month if the gated tools have real demand. For the broader monetization decision framework, see how-to-monetize-mcp-server.