Monétisez votre serveur MCP en 10 minutes.
Installez @blockchain0x/mcp, et à l'intérieur d'un outil premium, appelez requirePayment lorsque l'appelant n'a pas payé - cela crée un défi x402 402 avec une URL de paiement hébergée, que vous retournez. Une fois que le webhook payment.received confirme le règlement, vous marquez l'appelant comme payé dans votre propre magasin et l'outil s'exécute. Les outils gratuits restent gratuits. Pour un serveur HTTP classique, l'adaptateur x402 côté réception fait le même travail.
Avant de commencer.
- Un serveur MCP fonctionnel utilisant le SDK officiel Model Context Protocol en Node ou Python. Si vous n'en avez pas encore, créez-en un avec le modèle en amont d'abord.
- Un compte Blockchain0x et un profil d'agent (voir le ajouter-des-paiements-à-l-agent guide pour la configuration en 5 minutes).
- Une clé API (utilisez
sk_test_pour ce guide). - Un petit magasin pour se souvenir de qui a payé (une ligne de base de données ou une clé Redis) - votre code en est propriétaire, mis à jour par le webhook de paiement.
- Une idée claire des outils pour lesquels vous souhaitez facturer et du prix par appel. Consultez l'entrée du glossaire des outils MCP payants pour les modèles de conception.
Installez le package.
@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/nodeRestreindre un outil avec 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 }));Le corps 402 requirePayment retourne à un appelant non payé :
// 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"
}Confirmez le paiement, puis souvenez-vous de qui a payé.
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");
});La durée pendant laquelle un paiement accorde l'accès est votre décision - un seul appel, une session, une heure. Définissez une date d'expiration sur la clé d'état payée qui correspond à la façon dont vous tarifez l'outil. Assez long pour qu'une session normale réutilise un paiement, assez court pour que les abus soient limités.
Déployez et vérifiez.
Expédiez le serveur. Les outils gratuits devraient toujours renvoyer leur résultat immédiatement ; les outils restreints devraient renvoyer le corps 402 lors du premier appel d'un nouveau client, puis fonctionner une fois que cet appelant est marqué comme payé. Vérifiez les deux chemins avec une clé sk_test_ contre Base Sepolia avant de passer en production.
Deux signaux à surveiller dès le premier jour : le nombre de 402s retournés (votre haut de l'entonnoir) et le nombre d'exécutions d'outils réussies après un 402 (votre conversion). Si la conversion est beaucoup plus basse que prévu, le prix est probablement incorrect. Surveillez également le taux de succès de votre magasin d'état payant - s'il est proche de zéro, votre fenêtre d'accès est trop courte et les appelants payants se voient demander de payer à nouveau.
Cinq choses qui piquent les monétisateurs MCP pour la première fois.
Gestion accidentelle des outils gratuits
Il est tentant de restreindre chaque outil 'juste au cas où'. Ne le faites pas. La valeur entière des serveurs MCP payants est que les outils gratuits coexistent avec les payants sur le même serveur, de sorte que le client puisse utiliser les outils de découverte et de métadonnées gratuits sans payer. Créez un 402 uniquement pour les outils qui consomment réellement des ressources premium ; laissez le reste comme des résultats simples.
requirePayment est un constructeur, pas un middleware
requirePayment est une fonction pure : vous l'appelez lorsqu'un outil est impayé, elle renvoie { status: 402, body }, et vous renvoyez le corps. Il n'enveloppe pas votre gestionnaire et ne suit pas qui a payé. Il prend amountUsdc, payTo, hostedUrl, et un réseau et une description optionnels - rien d'autre. Que l'appelant ait payé est une vérification que vous effectuez contre votre propre magasin.
Il n'y a pas de cache de reçus expédié
Blockchain0x expédie le constructeur 402 et le webhook de règlement, pas un assistant de stockage de reçus. Vous décidez où 'cet appelant a payé' se trouve - une ligne de base de données, une clé Redis, une carte en mémoire pour un seul processus - et vous l'inversez lorsque le webhook payment.received arrive. Cela garde la politique (combien de temps un paiement accorde l'accès) entièrement entre vos mains.
Faire confiance à un reçu que le client prétend avoir
Ne laissez pas l'appelant affirmer qu'il a payé. La source de vérité est le webhook payment.received, vérifié avec webhooks.verify (ou le HMAC documenté) par rapport à votre secret de webhook. Marquez le payeur comme payé uniquement après un événement vérifié, et contrôlez l'outil sur cet état côté serveur - jamais sur quelque chose que le client envoie.
Pas de métriques sur la latence des outils payants
Mettre une étape de paiement entre le client et l'exécution de l'outil ajoute le temps que le demandeur prend pour payer et régler lors du premier appel, puis presque zéro une fois que vous les avez marqués comme payés. Instrumentez les deux branches afin que vous puissiez distinguer 'l'outil est lent' de 'le paiement est lent' lorsque un client se plaint. Sans la métrique, vous allez mal diagnostiquer le goulet d'étranglement.
Une fois que le trafic payant est en cours.
Avec la monétisation en place, les suivis les plus utiles sont la gestion fiable des webhooks (pour que vous ne manquiez pas d'événements de paiement), les contrôles de dépenses (pour qu'un serveur MCP que vous construisez et qui paie également d'autres agents reste limité) et un flux testnet-first (pour que vous puissiez expédier des changements de prix sans brûler de l'argent réel).
Les modèles de webhook dont les développeurs parlent le plus
Mettre en place des contrôles de dépenses d'agent qui survivent à l'injection d'invite
Testez les paiements d'agents sans argent réel
Référence API complète à docs.blockchain0x.com. Surface produit associée : Intégration MCP.