From 8e3411de9a92a1baa89f56b2186ac072b1b27b45 Mon Sep 17 00:00:00 2001 From: luisruiz3012 Date: Sat, 25 Jul 2026 02:13:10 -0600 Subject: [PATCH] Add guide: turn free MCP into paid tool with x402 + Pyrimid --- .../mcp-paid-tool/tutorial-free-apis-mcp.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 examples/mcp-paid-tool/tutorial-free-apis-mcp.md diff --git a/examples/mcp-paid-tool/tutorial-free-apis-mcp.md b/examples/mcp-paid-tool/tutorial-free-apis-mcp.md new file mode 100644 index 0000000..ff4f716 --- /dev/null +++ b/examples/mcp-paid-tool/tutorial-free-apis-mcp.md @@ -0,0 +1,215 @@ +# Tutorial: Turn a Free MCP Server into a Paid API with x402 + Pyrimid + +**Bounty:** Pyrimid #24 — Write a useful paid MCP tool guide +**Wallet:** `0x6458a540ea9c070b3d06302814be9945c7269521` (Base USDC) + +--- + +## Overview + +This guide walks through converting the **free-apis-mcp** server (a working MCP server with 7 free tools) into a paid, monetized MCP tool using: +- **x402** — HTTP 402 Payment Required pattern for micropayments +- **Pyrimid** — Onchain catalog + affiliate routing for AI agent commerce + +**Stack:** Python FastMCP, Base USDC, x402 headers, Pyrimid catalog + +--- + +## Step 1: Start with a Working MCP Server + +We begin with `free-apis-mcp`, a public MCP server that wraps free APIs (shipapis, monetizeyouragent). It has tools like: + +```python +@mcp.tool() +def get_shipapis_best(task: str) -> str: + """Find the best API for a given task — FREE preview""" + # returns sample data + payment requirement +``` + +The key insight: **free tools become your storefront**. They show the value. Paid tools deliver the goods. + +--- + +## Step 2: Split into Free (Preview) and Paid (Buy) Tools + +### Free Preview Tool + +```python +@mcp.tool() +def preview_api_search(task: str) -> str: + """FREE — Preview what APIs are available for your task""" + return json.dumps({ + "status": "preview", + "task": task, + "sample_results": [ + {"name": "weather-api", "confidence": 0.94}, + {"name": "financial-data", "confidence": 0.88} + ], + "price_usdc": 0.05, + "payment_required": True, + "payment_instruction": "Call buy_api_search with x402 payment proof" + }) +``` + +### Paid Tool + +```python +@mcp.tool() +def buy_api_search(task: str, payment_proof: str) -> str: + """PAID — Execute a full API search. Requires x402 payment proof.""" + if not verify_payment(payment_proof): + raise ValueError("HTTP 402: Payment required. Send 0.05 USDC to proceed.") + + results = execute_full_search(task) + return json.dumps({"status": "success", "data": results, "charge": "0.05 USDC"}) +``` + +--- + +## Step 3: Implement the x402 Payment Flow + +x402 works via standard HTTP 402 headers: + +### Payment Request + +```python +import hashlib, json, os + +PAYMENT_ADDRESS = "0x6458a540ea9c070b3d06302814be9945c7269521" +PRICE_USDC = 0.05 # per call + +def create_payment_request(): + """Generate an x402 payment challenge""" + nonce = hashlib.sha256(os.urandom(32)).hexdigest()[:16] + return { + "status": "payment_required", + "error": { + "code": "PAYMENT_REQUIRED", + "message": f"Send {PRICE_USDC} USDC to proceed", + "retryable": True, + "source": "x402", + "details": { + "amount": str(PRICE_USDC), + "asset": "USDC", + "network": "base", + "receiver": PAYMENT_ADDRESS, + "nonce": nonce + } + } + } +``` + +### Payment Verification + +```python +def verify_payment(payment_proof: str) -> bool: + """Verify onchain payment — check tx confirmed on Base""" + # In production: use BaseScan API or RPC call + # For this example, check payment_proof format + if not payment_proof or len(payment_proof) < 10: + return False + # TODO: implement actual onchain verification + return True +``` + +--- + +## Step 4: Register in Pyrimid Catalog + +To make your tool discoverable by agents, register it in the Pyrimid onchain catalog: + +```json +{ + "vendor_id": "free-apis-mcp", + "product_id": "api_search", + "description": "Paid API search tool — finds the best APIs for any task with confidence scoring", + "category": "search-scraping", + "tags": ["mcp", "api-discovery", "x402", "paid-tools", "search"], + "price_usdc": 50000, + "affiliate_bps": 3000, + "endpoint": "https://your-service.com/mcp", + "network": "base", + "asset": "USDC" +} +``` + +**Why affiliates matter:** Setting `affiliate_bps: 3000` means 30% of each sale goes to the agent/referrer who brought the buyer. This creates an incentive for other agents to promote your tool. + +--- + +## Step 5: Deploy and Smoke Test + +```bash +# Install +pip install fastmcp uvicorn + +# Run the MCP server +python -m src.server + +# Test free preview +curl http://localhost:8000/tools/preview_api_search \ + -H "Content-Type: application/json" \ + -d '{"task": "weather data"}' +# → Returns preview with price and payment instructions + +# Test paid execution (without payment — should 402) +curl http://localhost:8000/tools/buy_api_search \ + -H "Content-Type: application/json" \ + -d '{"task": "weather data", "payment_proof": ""}' +# → HTTP 402: Payment required +``` + +--- + +## Architecture Summary + +``` + ┌─────────────────┐ + │ AI Agent │ + │ (buyer) │ + └────────┬────────┘ + │ + discovers via │ Pyrimid catalog + ▼ + ┌─────────────────┐ + │ Pyrimid Router │ + │ (onchain) │ + └────────┬────────┘ + │ + routes with affiliate + ▼ + ┌─────────────────┐ + │ free-apis-mcp │ + │ (your server) │ + └────────┬────────┘ + │ + ┌────────────┼────────────┐ + ▼ ▼ ▼ + preview_* buy_* payment verify + (free) (paid) (onchain) +``` + +--- + +## Why This Works + +| Component | Role | Revenue | +|-----------|------|---------| +| Free preview | Shows value, builds trust | $0 (lead gen) | +| Paid execution | Delivers full results | $0.05–$0.50/call | +| Pyrimid catalog | Discovery + routing | Passive acquisition | +| x402 | Standard payment flow | Auto-collection | +| Affiliates | Other agents promote you | 70% vendor / 30% affiliate | + +--- + +## Resources + +- **Pyrimid catalog:** https://pyrimid.ai/api/v1/catalog +- **x402 spec:** https://x402.org +- **Free APIs MCP:** https://github.com/luisruiz3012/free-apis-mcp +- **Base USDC faucet:** https://bridge.base.org + +--- + +*Guide written for Pyrimid Bounty #24. Wallet for payout: `0x6458a540ea9c070b3d06302814be9945c7269521` on Base (USDC)*