Antes de comenzar.

• Un servidor MCP funcional utilizando el SDK oficial Model Context Protocol en Node o Python. Si aún no tienes uno, primero crea uno con la plantilla de upstream.
• Una cuenta de Blockchain0x y un perfil de agente (consulta la guía para agregar pagos al agente para la configuración de 5 minutos).
• Una clave de API (usa sk_test_ para esta guía).
• Una pequeña tienda para recordar quién ha pagado (una fila de base de datos o una clave de Redis) - tu código posee esto, actualizado por el webhook de pago.
• Una clara comprensión de qué herramientas deseas cobrar y el precio por llamada. Consulta la entrada del glosario de herramientas MCP pagadas para patrones de diseño.

Restringe una herramienta con requirePayment.

Inside the tool, check your own paid-state for the caller. If they have not paid, call requirePayment and return the resulting 402 body; if they have, run the work. requirePayment is a pure builder - it does not wrap the handler and does not track payment, so the gating policy stays in your code.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { requirePayment } from "@blockchain0x/mcp";
import { z } from "zod";

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

server.tool(
  "get_quote_realtime",
  "Real-time quote (paid)",
  { ticker: z.string() },
  async ({ ticker }, extra) => {
    if (!hasPaid(extra)) {
      // Pure function: mint an x402 402 challenge and hand the body back.
      const { body } = requirePayment({
        amountUsdc: "0.005",
        payTo: "0xYourWallet",
        hostedUrl: "https://pay.blockchain0x.com/checkout/abc",
      });
      return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
    }
    const quote = await fetchLiveQuote(ticker);
    return { content: [{ type: "text", text: JSON.stringify(quote) }] };
  },
);

import express from "express";
import { createX402Middleware } from "@blockchain0x/x402/server/express";
import { createClient } from "@blockchain0x/node";

const sdk = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! });
const app = express();

// Not an MCP server? Gate a plain HTTP route the same way. The middleware
// answers unpaid requests with a 402 and lets paid ones through.
// Configure the price and recipient per the x402 docs.
app.use("/quote", createX402Middleware({ sdk }));

El cuerpo 402 requirePayment devuelve a un llamador no pagado:

// requirePayment returns { status: 402, body }. The body an unpaid caller sees:
{
  "error": "payment_required",
  "amountUsdc": "0.005",
  "payTo": "0xYourWallet",
  "hostedUrl": "https://pay.blockchain0x.com/checkout/abc",
  "network": "mainnet"
}

Despliega y verifica.

Envía el servidor. Las herramientas gratuitas aún deben devolver su resultado de inmediato; las herramientas restringidas deben devolver el cuerpo 402 en la primera llamada de un cliente nuevo, luego ejecutarse una vez que ese llamador esté marcado como pagado. Verifica ambos caminos con una clave sk_test_ contra Base Sepolia antes de ir en vivo.

Dos señales a observar en el primer día: el conteo de 402s devueltos (tu embudo superior) y el conteo de ejecuciones exitosas de herramientas después de un 402 (tu conversión). Si la conversión es mucho más baja de lo esperado, el precio probablemente esté mal. Observa también la tasa de aciertos de tu tienda de estado pagado - si está cerca de cero, tu ventana de acceso es demasiado corta y se está pidiendo a los llamadores que paguen nuevamente.

Una vez que el tráfico pagado esté fluyendo.

Con la monetización en su lugar, los seguimientos más útiles son el manejo confiable de webhooks (para que no te pierdas eventos de pago), controles de gasto (para que un servidor MCP que construyas que también pague a otros agentes se mantenga limitado) y un flujo primero en testnet (para que puedas enviar cambios de precios sin gastar dinero real).

Referencia completa de la API en docs.blockchain0x.com. Superficie de producto relacionada: integración MCP.