Zero to MCP Server in 5 Minutes: A Developer Guide to x402 Micropayments

#ai #web3 #tutorial #api

Why Another MCP Tutorial?

Most MCP Server tutorials show you how to expose a single tool to Claude. But what if you want to expose 47 AI endpoints -- OCR, text-to-speech, LLM chat, image generation -- and charge per call using crypto micropayments?

That is what I built with GoldBean. This article walks through the architecture and shows you how to build your own.

The Stack

Layer	Technology
Protocol	MCP (Model Context Protocol) over SSE
Payments	x402 Protocol -- HTTP 402 to USDC on Base
AI Backend	Baidu AI APIs (OCR, TTS, ASR, LLM, Image Gen)
Runtime	Node.js on VPS
Package	npx goldbean-mcp on npm

How x402 Micropayments Work

The x402 protocol turns HTTP 402 (Payment Required) from an error code into a payment flow:

Client calls a paid endpoint
Server returns 402 Payment Required with payment details (USDC amount, wallet address, chain ID)
Client pays 0.01 USDC on Base mainnet via their wallet
Client retries the request with the transaction hash
Server verifies the on-chain transaction and returns the API response

No API key. No registration. No monthly subscription. You pay per call.

Adding MCP Layer

The MCP protocol sits on top of the HTTP server. Clients connect via SSE. Claude Desktop config:

The tools/list response includes all available tools with their input schemas. GoldBean exposes 10 tools through MCP: baidu_ocr, baidu_tts, ai_chat, image_gen, translate, weather, web_search, eth_price, btc_price, and code_run.

Free Tier Strategy

Here is the key insight: users who see HTTP 402 leave. Conversion rates for payment-required APIs are near zero.

So GoldBean offers:

21 free endpoints (no payment needed): weather, crypto prices, web search, translation, code runner
20 free credits for paid endpoints (OCR, TTS, LLM, Image Gen)
After free credits: 0.01 to 0.08 USD per call via USDC, PayPal, or Alipay

The free tier is the acquisition funnel. Users try it, find it useful, then pay when they need more.

Quick Start

Or add to Claude Desktop config:

That is it. No API key, no registration, no credit card. 20 free credits to start.

What I Learned Building This

1. Zero conversion is the real problem. Having a working payment system does not mean people will pay. The 402 response scares users away. The free tier exists to build trust before asking for payment.

2. MCP discovery matters. Being listed on Smithery, Glama, and awesome-mcp-servers drives organic traffic.

3. Multi-payment options are essential. Not everyone has USDC. PayPal and Alipay are necessary for global reach.

DEV Community