DEV Community

Toolstem Team
Toolstem Team

Posted on

I built an MCP server that charges AI agents per call using x402 micropayments

#mcp #webmonetization #typescript #ai

I built an MCP server that charges AI agents per call using x402 micropayments

By Toolstem

You built an MCP server. Agents call it. You pay the API costs. They pay nothing. Every tools/call invocation burns a few cents of your budget while the agent that triggered it has no idea — and no incentive to care. The standard answer is "wrap it in a SaaS subscription," but that requires a human in the loop to sign up, enter a card, and manage a billing relationship. Most agents don't have humans watching every call. What if the agent just paid for its own data, automatically, without a human anywhere in the loop?

That's what I built. Here's what I learned.

What x402 actually is

HTTP 402 — "Payment Required" — has existed since 1996. It was reserved for future use and then essentially forgotten for 28 years. The x402 protocol revives it as a machine-to-machine payment standard built on EIP-3009.

The flow looks like this:

  1. Agent hits your endpoint with a normal request
  2. Server returns HTTP 402 with a JSON body: payment amount, recipient address, network, token, nonce
  3. Agent signs an EIP-3009 transferWithAuthorization — a pre-authorized USDC transfer that the server can submit on behalf of the agent
  4. Agent retries the request with an X-Payment header containing the signed authorization
  5. Server verifies the signature on-chain, submits the transfer, and responds with data
  6. Settlement confirmed in under 2 seconds on Base mainnet; gas is roughly $0.001

No Stripe account. No OAuth flow. No human sign-up. No waiting for a monthly invoice. The agent pays exactly what it used, settled atomically, without ever needing ETH for gas (the server submits the transfer, so only the server needs a small ETH float for gas — the agent only needs USDC).

This is the "HTTP + payment" primitive that should have existed all along. It's pre-product-market-fit, but the underlying mechanic is sound.

The architecture

The core infrastructure is a Cloudflare Worker acting as a paywall proxy. It sits between the public internet and your upstream MCP server, intercepting every request before forwarding it.

Agent → Cloudflare Worker (x402 paywall) → Upstream MCP Server → Data sources
Enter fullscreen mode Exit fullscreen mode

The Worker handles the payment lifecycle:

  • Receives request
  • Checks for a valid X-Payment header
  • If absent: returns 402 with payment details
  • If present: verifies the EIP-3009 signature, checks nonce freshness and amount, submits the on-chain transfer
  • Forwards to upstream MCP only on successful verification

One non-obvious constraint: initialize and tools/list must be free. Agents need to discover your tool surface before they can decide whether to pay. If you charge for discovery, you never get called at all. Any directory health-check probe (Glama, mcp.so, PulseMCP) also expects a free tools/list response — paywall those and you fall off the listings. The Cloudflare Worker routes those two MCP message types to an unmetered path.

Per-tool pricing is where the model gets interesting. Our SEC EDGAR server runs three tiers:

Tool Tier Per call
getCompanyFilingsSummary Cheap $0.005
getInsiderSignal Standard $0.05
getInstitutionalSignal Standard $0.05
getMaterialEventsDigest Premium $0.50
compareDisclosureSignals Premium $0.50

A filings summary is one EDGAR lookup. compareDisclosureSignals cross-references insider trades, 13F institutional moves, and 8-K clusters across multiple companies. The compute difference is roughly 100x — so the price difference is 100x. Flat pricing treats them identically, which means you're subsidizing every expensive call with revenue from cheap ones.

The Finance MCP server (our first server) launched at a flat $0.005 across all tools. Six weeks in, we had $0 revenue. That table above is the lesson.

Code: agent side

The LangChain integration wraps the payment layer into a custom fetch function. Everything else is standard agent code.

TypeScript / LangChain.js:

import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { createFinanceTools } from "langchain-toolstem/finance";
import { createX402Fetch } from "langchain-toolstem/x402";

// fetch that auto-signs USDC payments on HTTP 402
const fetchPay = await createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY!,
  maxPaymentUsd: 0.05, // per-call safety cap
});

// discovers tools live via MCP tools/list (free)
const tools = await createFinanceTools({ fetch: fetchPay });

const agent = createReactAgent({ llm, tools });
// each tools/call costs $0.01 USDC, settled on Base mainnet
Enter fullscreen mode Exit fullscreen mode

The createX402Fetch wrapper intercepts any 402 response, signs the EIP-3009 authorization using the agent's private key, and retries transparently. The maxPaymentUsd cap is a safety rail — the agent refuses to sign any authorization above that threshold, protecting against a misconfigured or malicious server quoting an unexpected price.

Tools are discovered live via tools/list on startup (free, not metered), so the agent always sees the current tool surface without anything hardcoded into the package.

Python / LangChain:

from langchain_toolstem import create_finance_tools, create_x402_httpx_client

client = create_x402_httpx_client("0xYOUR_PRIVATE_KEY")
tools = await create_finance_tools(client=client)
# same pattern — agent signs payments, settles on Base
Enter fullscreen mode Exit fullscreen mode

For environments where you need a plain http:// URL rather than a custom fetch (e.g., MultiServerMCPClient), createX402Proxy spawns a local reverse proxy at localhost:4021 that handles payment signing, so you can point any standard MCP client at it directly.

The package is langchain-toolstem on npm (~1,400 installs/month) and langchain-toolstem on PyPI.

What we learned shipping this

Flat pricing was wrong. The Finance server ran flat $0.005 per call for six weeks. Zero meaningful revenue. The math is brutal: even if you hit the plateau of ~1,400 monthly active users typical for popular Apify actors, $0.005 flat yields ~$7/month. The ceiling is too low for a server with real API costs underneath it. Tiered pricing maps price to actual compute — it was the right call, and we should have done it from day one.

The free discovery layer is non-negotiable. Agents must be able to call tools/list without triggering a payment. This isn't just good UX — it's a technical requirement for every MCP directory that health-checks your listing. We had one bug early on where an unbilled discovery path was missing, and the server briefly vanished from Glama's listings because the probe got a 402 instead of a tools manifest.

The heartbeat problem is real. Coinbase's x402 Bazaar delists your endpoint if it goes 30 days without a confirmed paid call. For a server that's still building an audience, that's a serious risk — you could drop off the directory just as someone is about to discover you. We solved this with a GitHub Actions cron that runs every 6 hours, makes a real paid call from a funded heartbeat wallet, and posts the result to a log. Cost: roughly $0.06/day in USDC. Insurance against delisting: worth it.

The heartbeat revealed another bug: our initial implementation was calling tools/call without first completing the MCP initialize handshake. The server was rejecting the call silently. Fixing it required tracing the raw MCP message sequence. A reminder that the protocol has state — it's not a stateless REST API.

One external paying customer. $0.01. I want to be direct about this. The payment rail works end-to-end — 49 self-test transactions confirmed on Base mainnet, and one external payment from wallet 0x9CC4 on 2026-06-03 for $0.01. That's the full external revenue picture. The mechanism is proven; adoption is the open question.

We're self-audited on the security side (no third-party audit yet), and we've run independent AI reviewer passes on the codebase. The x402 verification logic, nonce handling, and private key isolation are the parts that matter most and got the most scrutiny.

Where this is going

x402 is a protocol looking for a distribution moment. The primitive is correct: HTTP-native, cryptographic, machine-to-machine, no humans required. What it lacks is the agent wallet layer becoming standard.

That moment is approaching. Coinbase AgentKit and CDP wallets are building the infrastructure for agents to hold and spend funds natively. When agent wallets are as common as agent LLM clients, x402 becomes the obvious way to monetize any agent-facing API — a single fetch wrapper is all the integration a developer needs.

Until then, the pattern is in early-adopter territory. The agents that can use it today are ones whose operators have explicitly provisioned a funded wallet and a private key in their environment. That's not zero — it's the population of developers actively building agentic systems who care about cost attribution.

The server is live at mcp.toolstem.com. Try it with a funded Base wallet. initialize and tools/list are always free — you can inspect the full tool surface before committing a cent.

The Finance and SEC EDGAR MCP servers are listed in Coinbase's x402 Bazaar. Source: github.com/toolstem/toolstem-mcp-server and github.com/toolstem/toolstem-sec-mcp-server. Walletless demo at toolstem.com/playground.

Top comments (0)