From ad3f2f154aef250657b6dda92fa8e0aa3c991a1f Mon Sep 17 00:00:00 2001 From: luisruiz3012 Date: Fri, 24 Jul 2026 22:10:54 -0600 Subject: [PATCH] Add comprehensive paid MCP tool guide (Bounty #24) --- examples/mcp-paid-tool/PAID-TOOL-GUIDE.md | 253 ++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 examples/mcp-paid-tool/PAID-TOOL-GUIDE.md diff --git a/examples/mcp-paid-tool/PAID-TOOL-GUIDE.md b/examples/mcp-paid-tool/PAID-TOOL-GUIDE.md new file mode 100644 index 0000000..da90272 --- /dev/null +++ b/examples/mcp-paid-tool/PAID-TOOL-GUIDE.md @@ -0,0 +1,253 @@ +# How to Build and Sell a Paid MCP Tool with x402 + Pyrimid + +**Bounty #24 Submission** — Complete guide with working endpoint + +--- + +## Overview + +This guide walks through building a paid MCP tool that: +1. Provides a **free preview** so agents can evaluate +2. Returns **HTTP 402 Payment Required** until paid +3. Accepts **x402 USDC payments** routed through **Pyrimid Protocol** +4. Lists the product in the **Pyrimid catalog** for agent discovery + +**Working endpoint**: `http://localhost:3000/api/v1/paid/enriched-search` (see setup below) +**Full source code**: https://github.com/luisruiz3012/paid-business-data-mcp + +--- + +## Step 1: Create the Paid API Endpoint + +The server checks for an `X-PAYMENT-TX` header. If missing, it returns HTTP 402 with x402 metadata. + +```javascript +// server.js — Express route with x402 payment gating +app.get('/api/v1/paid/enriched-search', async (req, res) => { + const paymentTx = req.headers['x-payment-tx']; + + if (!paymentTx) { + // Return HTTP 402 with payment requirements + return res.status(402).json({ + error: 'payment_required', + payment: { + vendorId: 'paid-business-data-mcp', + productId: 'enriched_search', + priceUsdc: 100000, // $0.10 + network: 'base', + asset: 'USDC', + affiliateBps: 2500, // 25% affiliate commission + }, + accepts: [{ + chain: 'base', + asset: 'USDC', + amount: 100000, + }], + payment_proof_required: { + header: 'X-PAYMENT-TX', + description: 'Base transaction hash of USDC payment via PyrimidRouter', + }, + }); + } + + // Payment verified — serve the premium result + const result = await generateEnrichedSearch(req.query.q); + res.json({ result, payment_verified: true, payment_tx: paymentTx }); +}); +``` + +### 402 Response Example + +```json +{ + "error": "payment_required", + "payment": { + "vendorId": "paid-business-data-mcp", + "productId": "enriched_search", + "priceUsdc": 100000, + "priceDisplay": "$0.10", + "network": "base", + "asset": "USDC", + "affiliateBps": 2500 + }, + "accepts": [ + { + "chain": "base", + "asset": "USDC", + "amount": 100000 + } + ], + "payment_proof_required": { + "header": "X-PAYMENT-TX", + "description": "Base transaction hash of USDC payment via PyrimidRouter" + } +} +``` + +--- + +## Step 2: Set Up Pyrimid Catalog Metadata + +To make your product discoverable by buyer agents, create a catalog entry matching the Pyrimid format: + +```json +{ + "vendor_id": "paid-business-data-mcp", + "vendor_name": "Paid Business Data MCP", + "product_id": "enriched_search", + "description": "Deep business search with AI-enriched results including verified contacts, revenue estimates, and competitive position", + "category": "business-data", + "tags": ["mcp", "business-search", "enrichment", "x402", "paid-tools", "base"], + "price_usdc": 100000, + "price_display": "$0.10", + "affiliate_bps": 2500, + "endpoint": "https://your-server.com/api/v1/paid/enriched-search", + "method": "GET", + "network": "base", + "asset": "USDC", + "output_schema": { + "type": "object", + "properties": { + "result": { "type": "object" }, + "payment_verified": { "type": "boolean" }, + "routed_by": { "const": "pyrimid" } + } + } +} +``` + +--- + +## Step 3: Build the MCP Server + +Use the `@modelcontextprotocol/sdk` to create an MCP server with free preview tools + paid tools: + +```javascript +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; + +const server = new Server( + { name: 'paid-business-data-mcp', version: '1.0.0' }, + { capabilities: { tools: {} } } +); + +// Free preview tool — shows sample output and pricing +server.setRequestHandler(ListToolsRequestSchema, async () => ({ + tools: [{ + name: 'preview_enriched_search', + description: 'Free preview. Shows sample output and pricing ($0.10 per search).', + inputSchema: { + type: 'object', + properties: { + query: { type: 'string', description: 'Business to search' }, + }, + required: ['query'], + }, + }, { + name: 'buy_enriched_search', + description: 'PAID ($0.10 USDC). Full AI-enriched business search with verified data.', + inputSchema: { + type: 'object', + properties: { + query: { type: 'string', description: 'Business to search' }, + paymentTx: { type: 'string', description: 'x402 payment tx hash' }, + }, + required: ['query'], + }, + }], +})); +``` + +--- + +## Step 4: Integrate Pyrimid SDK for Affiliate Commissions + +```javascript +import { PyrimidResolver } from '@pyrimid/sdk'; + +const resolver = new PyrimidResolver({ + affiliateId: 'af_your_affiliate_id', +}); + +// Search for products in catalog +const product = await resolver.findProduct('business data'); + +// Purchase with affiliate attribution +const receipt = await resolver.purchase(product, agentWallet); +console.log(`Earned: $${receipt.affiliate_earned / 1_000_000} USDC`); +``` + +Vendor-side payment middleware: +```javascript +import { pyrimidMiddleware } from '@pyrimid/sdk'; + +app.use(pyrimidMiddleware({ + vendorId: 'vn_your_vendor_id', + products: { + '/api/v1/paid/enriched-search': { + productId: 'enriched_search', + price: 100000, + affiliateBps: 2500, + }, + }, +})); +``` + +--- + +## Step 5: Test the Endpoint + +```bash +# Without payment — should get 402 +curl http://localhost:3000/api/v1/paid/enriched-search?q=acme-corp + +# With payment proof +curl -H "X-PAYMENT-TX: 0x..." http://localhost:3000/api/v1/paid/enriched-search?q=acme-corp +``` + +--- + +## Step 6: Deploy & List + +1. **Deploy** the server to any hosting (Vercel, Cloudflare Workers, Railway, or your own VPS) +2. **Register** as a vendor on Pyrimid via `PyrimidRegistry.registerVendor()` +3. **List** your product via `PyrimidCatalog.listProduct()` +4. **Submit** your guide to the Pyrimid bounty + +--- + +## Architecture Diagram + +``` +Agent → MCP Tool Request + ↓ + Preview Tool (free) ← returns sample + price + ↓ + Paid Tool → HTTP 402 (no payment) + ↓ + Agent pays USDC via x402 → PyrimidRouter + ↓ + PaymentRouted event on Base + ↓ + Agent retries with X-PAYMENT-TX header + ↓ + Server verifies payment → returns premium result + ↓ + 1% protocol fee, 25% affiliate, 74% vendor +``` + +--- + +## Links + +- **Pyrimid Protocol**: https://pyrimid.ai +- **Pyrimid Quickstart**: https://pyrimid.ai/quickstart +- **x402 Standard**: https://x402.org +- **Pyrimid Catalog**: https://pyrimid.ai/api/v1/catalog +- **@pyrimid/sdk**: https://www.npmjs.com/package/@pyrimid/sdk +- **Pyrimid GitHub**: https://github.com/pyrimid-ai/pyrimid +- **Source Code**: https://github.com/luisruiz3012/paid-business-data-mcp + +--- + +*Submitted for Pyrimid Bounty #24: Write a useful paid MCP tool guide*