You have an MCP server. It works. Now make it pay you.
This tutorial takes you from pip install to a working paid MCP server in under 5 minutes. We'll build a weather service, put a USDC paywall on it, and test the full buyer-seller flow.
No prior crypto experience needed.
What You'll Need
python3 --version
# Python 3.10.x or higher ✓
Step 1: Install (30 seconds)
pip install ag402-core fastmcp
Verify:
ag402 --version
This installs the ag402 CLI (wallet management + reverse proxy), the ag402_core Python SDK (buyer-side auto-payment), and fastmcp (for our demo server).
Step 2: Create Your Wallet (30 seconds)
ag402 init
This generates a Solana keypair and loads it with test USDC for development. Wallet details are stored encrypted at ~/.ag402/wallet.json.
Save your wallet address — you'll need it in Step 4.
In test mode, ag402 mints devnet USDC so you can experiment for free. For production, set X402_MODE=production and fund with real USDC.
Step 3: Build a Simple MCP Server (2 minutes)
mkdir my-paid-mcp && cd my-paid-mcp
Create weather_server.py:
from fastmcp import FastMCP
mcp = FastMCP("Weather Service")
WEATHER_DATA = {
"san francisco": {"temp_c": 18, "condition": "foggy", "humidity": 75},
"new york": {"temp_c": 22, "condition": "sunny", "humidity": 45},
"tokyo": {"temp_c": 25, "condition": "cloudy", "humidity": 60},
"london": {"temp_c": 15, "condition": "rainy", "humidity": 82},
}
@mcp.tool()
def get_weather(city: str) -> dict:
"""Get current weather for a city."""
data = WEATHER_DATA.get(city.lower())
if not data:
return {"error": f"No data for {city}"}
return {"city": city, **data}
if __name__ == "__main__":
# Use HTTP transport so ag402 can proxy requests
mcp.run(transport="streamable-http", port=3000)
Start in Terminal 1:
python weather_server.py
# Server running on http://localhost:3000
Why not stdio? ag402's reverse proxy needs an HTTP endpoint to sit in front of. The stdio transport communicates via stdin/stdout, which can't be proxied. streamable-http exposes your MCP server as a standard HTTP service. If your MCP server already runs on HTTP (e.g., behind Flask or FastAPI), skip this step and point ag402 at your existing endpoint.
Step 4: Add the Paywall (30 seconds)
Open Terminal 2:
ag402 serve \
--target http://localhost:3000 \
--price 0.02 \
--address
┌─────────────────────────────────────┐
│ 🚀 ag402 Payment Proxy │
│ ───────────────────────────────── │
│ 🎯 Target: http://localhost:3000 │
│ 💵 Price: 0.02 USDC/request │
│ 🔗 Proxy: http://localhost:4020 │
└─────────────────────────────────────┘
Done. Here's what happens on each request:
Agent → :4020 → payment header? ─── No ──→ 402 + price/wallet info
│ ↑
Yes Agent auto-pays
│ USDC on Solana
▼ │
Verify on-chain ←────────────────┘
│
▼
Forward to :3000 (your MCP)
│
▼
Response ✓
Your MCP code: zero changes.
Step 5: Test as a Buyer (1 minute)
Create test_buyer.py:
import ag402_core
import httpx
# One line — patches httpx/requests to auto-pay 402s
ag402_core.enable()
response = httpx.post(
"http://localhost:4020/mcp",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {"city": "Tokyo"}
}
}
)
print(response.json())
python test_buyer.py
Behind the scenes: httpx hits proxy → gets 402 → ag402_core intercepts → auto-pays $0.02 USDC (~0.5s) → retries with proof → weather data ✓
The buyer code has zero payment logic. Even simpler — wrap any existing script:
ag402 run -- python my_existing_agent.py
Bonus: Prepaid Mode (~1ms)
Standard payments take ~0.5s. ag402's prepaid system drops that to ~1ms with zero gas:
One Solana tx → buy N credits → HMAC credential
Each call → credential header → local verify → ~1ms, $0 gas
HMAC-SHA256 verified locally — no blockchain calls after the initial purchase. (How prepaid works under the hood)
Bonus: Production
Mainnet:
X402_MODE=production ag402 serve \
--target http://your-server:3000 \
--price 0.02 \
--address
Claude Code / Cursor:
ag402 install claude-code # or: ag402 install cursor
Troubleshooting
Limitations
Security Checklist (Before Production)
What We Built
Your server code: unchanged. Your revenue: non-zero.
Next Steps
→ ⭐ ag402 on GitHub — source, docs, examples
→ 🧪 Colab demo — try in browser, zero install
→ 📖 Why charge? — the business case
→ 📝 Case study — real lessons from a $0.02 paywall
ag402 is open source (MIT). Built by AetherCore on Coinbase x402.
More...
This tutorial takes you from pip install to a working paid MCP server in under 5 minutes. We'll build a weather service, put a USDC paywall on it, and test the full buyer-seller flow.
No prior crypto experience needed.
What You'll Need
- Python 3.10+
- Two terminal windows
- 5 minutes
python3 --version
# Python 3.10.x or higher ✓
Step 1: Install (30 seconds)
pip install ag402-core fastmcp
Verify:
ag402 --version
This installs the ag402 CLI (wallet management + reverse proxy), the ag402_core Python SDK (buyer-side auto-payment), and fastmcp (for our demo server).
Step 2: Create Your Wallet (30 seconds)
ag402 init
This generates a Solana keypair and loads it with test USDC for development. Wallet details are stored encrypted at ~/.ag402/wallet.json.
Save your wallet address — you'll need it in Step 4.
In test mode, ag402 mints devnet USDC so you can experiment for free. For production, set X402_MODE=production and fund with real USDC.
Step 3: Build a Simple MCP Server (2 minutes)
mkdir my-paid-mcp && cd my-paid-mcp
Create weather_server.py:
from fastmcp import FastMCP
mcp = FastMCP("Weather Service")
WEATHER_DATA = {
"san francisco": {"temp_c": 18, "condition": "foggy", "humidity": 75},
"new york": {"temp_c": 22, "condition": "sunny", "humidity": 45},
"tokyo": {"temp_c": 25, "condition": "cloudy", "humidity": 60},
"london": {"temp_c": 15, "condition": "rainy", "humidity": 82},
}
@mcp.tool()
def get_weather(city: str) -> dict:
"""Get current weather for a city."""
data = WEATHER_DATA.get(city.lower())
if not data:
return {"error": f"No data for {city}"}
return {"city": city, **data}
if __name__ == "__main__":
# Use HTTP transport so ag402 can proxy requests
mcp.run(transport="streamable-http", port=3000)
Start in Terminal 1:
python weather_server.py
# Server running on http://localhost:3000
Why not stdio? ag402's reverse proxy needs an HTTP endpoint to sit in front of. The stdio transport communicates via stdin/stdout, which can't be proxied. streamable-http exposes your MCP server as a standard HTTP service. If your MCP server already runs on HTTP (e.g., behind Flask or FastAPI), skip this step and point ag402 at your existing endpoint.
Step 4: Add the Paywall (30 seconds)
Open Terminal 2:
ag402 serve \
--target http://localhost:3000 \
--price 0.02 \
--address
┌─────────────────────────────────────┐
│ 🚀 ag402 Payment Proxy │
│ ───────────────────────────────── │
│ 🎯 Target: http://localhost:3000 │
│ 💵 Price: 0.02 USDC/request │
│ 🔗 Proxy: http://localhost:4020 │
└─────────────────────────────────────┘
Done. Here's what happens on each request:
Agent → :4020 → payment header? ─── No ──→ 402 + price/wallet info
│ ↑
Yes Agent auto-pays
│ USDC on Solana
▼ │
Verify on-chain ←────────────────┘
│
▼
Forward to :3000 (your MCP)
│
▼
Response ✓
Your MCP code: zero changes.
Step 5: Test as a Buyer (1 minute)
Create test_buyer.py:
import ag402_core
import httpx
# One line — patches httpx/requests to auto-pay 402s
ag402_core.enable()
response = httpx.post(
"http://localhost:4020/mcp",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {"city": "Tokyo"}
}
}
)
print(response.json())
python test_buyer.py
Behind the scenes: httpx hits proxy → gets 402 → ag402_core intercepts → auto-pays $0.02 USDC (~0.5s) → retries with proof → weather data ✓
The buyer code has zero payment logic. Even simpler — wrap any existing script:
ag402 run -- python my_existing_agent.py
Bonus: Prepaid Mode (~1ms)
Standard payments take ~0.5s. ag402's prepaid system drops that to ~1ms with zero gas:
One Solana tx → buy N credits → HMAC credential
Each call → credential header → local verify → ~1ms, $0 gas
| Starter | 100 | $1.50 | $0.015 | 3 days |
| Pro | 1,000 | $8.00 | $0.008 | 30 days |
| Business | 5,000 | $35.00 | $0.007 | 365 days |
HMAC-SHA256 verified locally — no blockchain calls after the initial purchase. (How prepaid works under the hood)
Bonus: Production
Mainnet:
X402_MODE=production ag402 serve \
--target http://your-server:3000 \
--price 0.02 \
--address
Claude Code / Cursor:
ag402 install claude-code # or: ag402 install cursor
Troubleshooting
| ag402 init fails | Ensure Python 3.10+ and pip is current |
| Proxy can't reach target | Confirm MCP server is running on the correct port |
| Payment not going through | ag402 init provides test USDC — run again if needed |
| 402 but no auto-pay | ag402_core.enable() must be called before HTTP requests |
| Import errors | pip install --upgrade ag402-core |
Limitations
- Buyers need a Solana wallet with USDC — this is real friction for non-crypto developers. Test mode removes this barrier for development, and prepaid reduces on-chain interactions, but production buyers need crypto.
- Solana network dependency — standard payments require network availability. Prepaid mode (HMAC-based) works independently of the network after the initial purchase.
- Simple pricing only — ag402 handles per-request pricing. For subscriptions, usage tiers, or invoicing, you'll need additional tooling.
Security Checklist (Before Production)
- [ ] Private key in environment variable (SOLANA_PRIVATE_KEY), never in code
- [ ] Tested on devnet before mainnet
- [ ] Price set slightly above your per-request cost
- [ ] Reviewed built-in protections: per-tx cap ($5), rate limit, daily cap ($10), circuit breaker, auto-rollback, key redaction
- [ ] 588+ tests, 4 security audits, MIT licensed → GitHub
What We Built
| Install | 30s | ag402 + FastMCP ready |
| Wallet | 30s | Solana wallet + test USDC |
| MCP server | 2min | Weather service on :3000 |
| Paywall | 30s | Reverse proxy on :4020 |
| Test | 1min | Auto-pay verified ✓ |
Your server code: unchanged. Your revenue: non-zero.
Next Steps
→ ⭐ ag402 on GitHub — source, docs, examples
→ 🧪 Colab demo — try in browser, zero install
→ 📖 Why charge? — the business case
→ 📝 Case study — real lessons from a $0.02 paywall
ag402 is open source (MIT). Built by AetherCore on Coinbase x402.
More...