Monetarisieren Sie Ihren MCP-Server in 10 Minuten.
Installieren Sie @blockchain0x/mcp, und rufen Sie innerhalb eines Premium-Tools requirePayment auf, wenn der Anrufer nicht bezahlt hat - es erstellt eine x402 402-Herausforderung mit einer gehosteten Checkout-URL, die Sie zurückgeben. Sobald der payment.received Webhook die Abrechnung bestätigt, markieren Sie den Anrufer als bezahlt in Ihrem eigenen Speicher und das Tool läuft. Kostenlose Tools bleiben kostenlos. Für einen einfachen HTTP-Server erledigt der Empfangs-x402-Adapter dasselbe.
Bevor Sie beginnen.
- Ein funktionierender MCP-Server, der das offizielle Model Context Protocol SDK in Node oder Python verwendet. Wenn Sie noch keinen haben, erstellen Sie zuerst einen mit der upstream-Vorlage.
- Ein Blockchain0x-Konto und ein Agentenprofil (siehe die add-payments-to-agent guide für die 5-minütige Einrichtung).
- Ein API-Schlüssel (verwenden Sie
sk_test_für diesen Leitfaden). - Ein kleiner Speicher, um sich zu merken, wer bezahlt hat (eine Datenbankzeile oder ein Redis-Schlüssel) - Ihr Code besitzt dies, aktualisiert durch den Zahlungs-Webhook.
- Ein klares Verständnis dafür, welche Tools Sie berechnen möchten und den Preis pro Aufruf. Siehe den Glossareintrag für kostenpflichtige MCP-Tools für Designmuster.
Installieren Sie das Paket.
@blockchain0x/mcp exports requirePayment, a pure function that mints an x402 402 challenge for a tool. It is npm (TypeScript) only. If you run a plain HTTP server instead of an MCP one, install the receive-side x402 adapter and gate routes with it.
# Gate your own MCP tools with the requirePayment 402 builder:
npm install @blockchain0x/mcp
# Or gate a plain HTTP server with the receive-side x402 adapter + SDK:
npm install @blockchain0x/x402 @blockchain0x/nodeSperren Sie ein Tool mit 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 }));Der 402-Körper requirePayment wird an einen nicht bezahlenden Anrufer zurückgegeben:
// 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"
}Zahlung bestätigen und dann merken, wer bezahlt hat.
When a caller pays the checkout, Blockchain0x POSTs a signed payment.received event to your webhook. Verify it with webhooks.verify from @blockchain0x/node, then write the paid state to a store you control - a database row, a Redis key, your call. That store is what the tool checks in Step 2. There is no shipped receipt cache; you own where paid-state lives and how long it lasts.
import express from "express";
import { webhooks } from "@blockchain0x/node";
const app = express();
app.use(express.raw({ type: "application/json" }));
app.post("/webhooks/payment", (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body, // RAW bytes
secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
});
if (!result.ok) return res.status(400).json({ code: result.code });
if (result.eventType === "payment.received") {
// Remember the payer however you like - a DB row, a Redis key, your call.
markPaid(result.eventId);
}
res.status(200).send("ok");
});Wie lange eine Zahlung den Zugang gewährt, liegt in Ihrer Entscheidung - ein einzelner Anruf, eine Sitzung, eine Stunde. Setzen Sie ein Ablaufdatum für den bezahlten Schlüssel, das mit der Preisgestaltung des Tools übereinstimmt. Lang genug, dass eine normale Sitzung eine Zahlung wiederverwendet, kurz genug, dass Missbrauch begrenzt ist.
Bereitstellen und verifizieren.
Versenden Sie den Server. Kostenlose Tools sollten immer noch sofort ihr Ergebnis zurückgeben; geschützte Tools sollten den 402-Körper beim ersten Aufruf von einem neuen Client zurückgeben und dann laufen, sobald dieser Aufrufer als bezahlt markiert ist. Überprüfen Sie beide Pfade mit einem sk_test_-Schlüssel gegen Base Sepolia, bevor Sie live gehen.
Zwei Signale, die Sie am ersten Tag beobachten sollten: die Anzahl der zurückgegebenen 402s (Ihr Top-of-Funnel) und die Anzahl der erfolgreichen Toolausführungen nach einer 402 (Ihre Konversion). Wenn die Konversion viel niedriger ist als erwartet, ist der Preis wahrscheinlich falsch. Achten Sie auch auf die Trefferquote Ihres bezahlten Statusspeichers - wenn sie nahe null liegt, ist Ihr Zugangsfenster zu kurz und zahlende Anrufer werden gebeten, erneut zu zahlen.
Fünf Dinge, die Erstmonetarisierer von MCP beißen.
Die kostenlosen Tools versehentlich sperren
Es ist verlockend, jedes Tool 'nur für den Fall' zu sperren. Tun Sie das nicht. Der gesamte Wert von bezahlten MCP-Servern besteht darin, dass kostenlose Tools mit bezahlten auf demselben Server koexistieren, sodass der Client die kostenlosen Entdeckungs- und Metadaten-Tools nutzen kann, ohne zu bezahlen. Erstellen Sie eine 402 nur für die Tools, die tatsächlich Premium-Ressourcen verbrauchen; lassen Sie den Rest als einfache Ergebnisse.
requirePayment ist ein Builder, kein Middleware
requirePayment ist eine reine Funktion: Sie rufen es auf, wenn ein Tool unbezahlte ist, es gibt { status: 402, body } zurück, und Sie geben den Body zurück. Es umschließt Ihren Handler nicht und verfolgt nicht, wer bezahlt hat. Es nimmt amountUsdc, payTo, hostedUrl und ein optionales Netzwerk und eine Beschreibung - nichts anderes. Ob ein Anrufer bezahlt hat, ist eine Überprüfung, die Sie gegen Ihren eigenen Store durchführen.
Es gibt keinen gelieferten Empfangs-Cache.
Blockchain0x liefert den 402-Builder und den Abrechnungs-WebHook, nicht einen Empfangshelfer. Sie entscheiden, wo 'dieser Anrufer bezahlt hat' gespeichert wird - eine Datenbankzeile, ein Redis-Schlüssel, eine In-Memory-Karte für einen einzelnen Prozess - und Sie ändern es, wenn der payment.received WebHook ankommt. Das hält die Richtlinie (wie lange eine Zahlung Zugang gewährt) vollständig in Ihren Händen.
Einen Beleg vertrauen, den der Kunde zu haben behauptet.
Lassen Sie den Anrufer nicht behaupten, dass er bezahlt hat. Die Quelle der Wahrheit ist der payment.received Webhook, der mit webhooks.verify (oder dem dokumentierten HMAC) gegen Ihr Webhook-Geheimnis überprüft wird. Markieren Sie den Zahler erst nach einem verifizierten Ereignis als bezahlt und steuern Sie das Tool basierend auf diesem serverseitigen Zustand - niemals auf etwas, das der Client sendet.
Keine Metriken zur Latenz bezahlter Tools
Einen Zahlungsschritt zwischen dem Client und der Werkzeugausführung hinzuzufügen, erhöht die Zeit, die der Aufrufer benötigt, um beim ersten Aufruf zu bezahlen und abzurechnen, dann nahezu null, sobald Sie sie als bezahlt markiert haben. Instrumentieren Sie beide Zweige, damit Sie 'Werkzeug ist langsam' von 'Zahlung ist langsam' unterscheiden können, wenn ein Kunde sich beschwert. Ohne die Metrik werden Sie den Engpass falsch diagnostizieren.
Sobald bezahlter Verkehr fließt.
Mit der Monetarisierung sind die nützlichsten Folgemaßnahmen zuverlässige Webhook-Verarbeitung (damit Sie keine Zahlungsereignisse verpassen), Ausgabensteuerungen (damit ein MCP-Server, den Sie erstellen, der auch andere Agenten bezahlt, begrenzt bleibt) und ein Testnetz-erstes Fluss (damit Sie Preisänderungen versenden können, ohne echtes Geld zu verbrennen).
Die Webhook-Muster, nach denen Entwickler am häufigsten fragen
Richten Sie Ausgabensteuerungen für Agenten ein, die Eingabeaufforderungsinjektionen überstehen
Testen Sie Agentenzahlungen ohne echtes Geld
Vollständige API-Referenz unter docs.blockchain0x.com. Verwandte Produktoberfläche: MCP-Integration.