Agent402 MCP Server

Agent402.Tools — the open x402 index (Find · Route · Leaderboard) + a catalog of 500+ tools & skill packs for AI agents

What makes it different: Agent402 is open-source and self-hostable — and a single integration gives a buyer three free primitives over the whole x402 ecosystem:

• Find — /api/find?q={task} resolves a task description to the best-matching tools (route, price, schema, ready example).
• Route — POST /api/route is the neutral Smart Order Router: rank tools across every x402 seller crawled (auto-discovered from the Coinbase CDP Bazaar), health-aware, with include=external to exclude us.
• Leaderboard — GET /api/leaderboard is the public on-chain ranking of every x402 seller by Base USDC settled volume — calls served, totalUsd, unique buyers per seller. Pipeline: Bazaar → eth_getLogs → per-call ceiling → aggregate by payTo. Hourly snapshot.

Plus the catalog — 500+ strong: 400+ tools + 100 curated skill packs (multi-tool workflows callable as MCP prompts) — all runnable yourself, plus agent402-tollbooth — an open pay-per-crawl gate for the other side of x402.

Framework adapters (drop-in tools for the major agent stacks — auto-payment underneath):

500+ strong — 400+ ready-to-use web tools + 100 multi-tool skill packs for your AI agent, from one server. Every one tested, priced, and settled on-chain; every one earns its place. Browser rendering, web search, PDFs, images, OCR, live financial/crypto/macro data, SEC EDGAR, deterministic stats, forecasting, and options/bond pricing (Black-Scholes, YTM), compression, and 216 pure-CPU utilities. Run it yourself for free in 30 seconds (MCP or plain HTTP, no API keys, no signup), connect it to Claude/ChatGPT/any MCP client, and add your own tools in a few lines. Every tool is deterministic — no LLM in the serving path — and re-tested against its own example before every release.

Optionally, the same server can charge per call over the x402 protocol (USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Stellar & Algorand, plus USDG on Robinhood Chain — 11 chains) — so the instance you self-host for free can also be a hosted, monetized one. That part is opt-in; by default everything runs free.

🟢 Hosted demo: agent402.tools · 📖 Wiki · 📦 npm · 🔌 MCP Registry

Run it yourself in 30 seconds

Pick whichever fits — all three are free and need no wallet:

1. Zero install — add the hosted connector to Claude (claude.ai → Settings → Connectors → Add custom connector):

https://agent402.tools/mcp

2. One command — run the MCP server locally (the pure-CPU tools work with no key; it pays the tiny proof-of-work for you):

npx -y agent402-mcp
# in Claude Code:  claude mcp add agent402 -- npx -y agent402-mcp

3. Clone and host the whole thing (all 500+ tools as an HTTP API + MCP, free mode, no payments):

git clone https://github.com/MikeyPetrillo/Agent402 && cd Agent402
npm install
FREE_MODE=true npm start          # → http://localhost:3000  (HTTP API + /mcp)

# try a tool over HTTP — no auth in free mode
curl -s -X POST localhost:3000/api/hash -H 'content-type: application/json' \
  -d '{"text":"hello world","algo":"sha256"}'

4. One-click deploy to Railway (full self-hosted instance — adds optional Postgres + Redis plugins for analytics + response caching):

Boots straight from the repo's railway.toml + Dockerfile. Optional plugins are auto-detected via env: add Redis → REDIS_URL enables the upstream response cache (X-Cache: hit|miss), add Postgres → DATABASE_URL enables the public /api/analytics dashboard and the tollbooth waitlist. No env vars required to boot in free mode.

What's in the catalog (500+ tools)

Every tool earns its place: deterministic, tested against its own example on every CI run, priced to market, settled on-chain. CI holds a 400-entry catalog floor and verifies the “500+” claim against the running catalog (scripts/sync-count.js --check). The catalog grows only when a tool is worth calling.

Full schemas live in /openapi.json; a machine-readable catalog is at /api/pricing and /llms.txt. Don't know which tool you need? /api/find?q=<task> resolves a task description to the right tool — route, price, schema, and a ready example — so an agent skips the token-heavy "search around to find a tool" step.

OpenAI-compatible LLM gateway (/v1) — chat, embeddings & images, pay per call

Point any OpenAI SDK at base_url = https://agent402.tools/v1 and pay per call in USDC over x402 — no API key, no signup, no account:

Streaming (stream: true), full tools/function-calling passthrough, an opt-in prompt cache on the chat tiers (cache: true → byte-identical repeats free for 10 minutes), upstream failover chains that end in a canary-proven model, and a free GET /v1/models listing every model with its tier and caps. A real-money canary buys from every one of these surfaces daily — streaming, routing disclosure, and both cache behaviors included.

Two companion tools close the loop: POST /api/route/execute ($0.01, or the $0.55 execute-max tier for pricier tools) resolves a task description to the best tool and runs it in one paid call, including, with include:"external", tools sold by other x402 sellers (it routes only to sellers with proven on-chain settled volume, pays them on your behalf on the chain you paid on — Base or Algorand — and relays the result; see the Smart Order Router guide), and POST /api/my-usage ($0.005) returns the paying wallet's own purchase history — no wallet parameter; the x402 payment is the identity, so nobody can read another wallet's profile.

Skill packs — 100 multi-tool workflows

For jobs that span several tools — "audit a domain", "diagnose deliverability", "work up a time-series", "peel an opaque blob" — Agent402 ships curated skill packs: ordered, typed sequences of tool calls with a Claude-ready prompt template. Callable as MCP prompts (prompts/list → prompts/get { name, arguments }) or plain HTTP at /api/skill-packs/{slug}/prompt. A task-shaped query to search_tools returns the matching pack alongside individual tools.

All 100 packs at /skills · JSON index at /api/skill-packs.json · on MCP the packs appear under prompts/list so any MCP-aware client picks them up automatically.

x402 Index — Find · Route · Leaderboard

Agent402 is also the open routing + ranking layer for the whole x402 ecosystem: it crawls public x402 sellers (the local catalog + an auto-discovered set from the Coinbase CDP Bazaar, refreshed hourly) and exposes them through three free surfaces — same logic as /api/find: discovery primitives shouldn't cost money.

# "I need an OCR tool — find me the cheapest healthy one anywhere on x402"
curl -X POST https://agent402.tools/api/route \
  -H 'content-type: application/json' \
  -d '{"query":"ocr image to text","top":5}'

# "Who are the most-used x402 sellers right now? (on-chain proof, not self-reports)"
curl 'https://agent402.tools/api/leaderboard?top=25&include=external'

Health-aware: sellers whose last few crawls errored are excluded from the router (a buyer routed to a dead seller wastes money). Healthier sellers also break ties at equal match score and price, so flaky-but-cheap sellers lose to reliable ones. Brand-new sellers (no history yet) get the benefit of the doubt.

Operators get 3-rail attribution on the dashboard (/api/stats, /__operator): USDC vs. proof-of-work vs. heartbeat-probe traffic are counted separately — and the heartbeat rail is gated on a POW_SECRET-signed token (not a spoofable User-Agent), so the operator view reflects real external demand.

For API sellers: /sell is the front door — list an existing x402-speaking API on the index for free with POST /api/index/register (health-routed, 0% take, self-serve, no signup), or install agent402-tollbooth to put a pay-per-crawl gate in front of a site that isn't x402-native yet.

From code, the agent402-client npm package wraps all of this — find() a tool, then call() it, paying automatically (a built-in proof-of-work for free tools, your x402 wallet for paid ones), with caching and idempotent retries:

npm install agent402-client

import { Agent402 } from "agent402-client";
const a = new Agent402();                       // free tier (proof-of-work)
const out = await a.call("hash", { text: "hello world", algo: "sha256" });

Plug into your agent framework (zero-dep adapters)

If you're already on OpenAI / Anthropic / Vercel AI SDK / LangChain / LlamaIndex, skip the wiring — there's a drop-in package that turns the Agent402 catalog into native tool objects for your framework, with payment handled underneath (proof-of-work for free tools, x402+USDC when you pass an @x402/fetch):

// e.g. OpenAI — every adapter has the same surface.
import OpenAI from "openai";
import { agent402Tools } from "agent402-openai-tools";

const openai = new OpenAI();
const { tools, execute } = await agent402Tools({ slugs: ["extract", "hash", "render"] });
const res = await openai.chat.completions.create({ model: "gpt-4o-mini", tools, messages: [...] });
// when the model returns a tool call: await execute(call.function.name, JSON.parse(call.function.arguments));

Already a Claude/MCP user? agent402-mcp is still the better path — paste https://agent402.tools/mcp into your client. The adapters are for direct API integrations where MCP isn't available. Sources: adapters/.

OpenClaw agents: drop in skills/openclaw/agent402/SKILL.md — teaches an OpenClaw agent to find, pay (x402 USDC on Base, seven other chains accepted, or free proof-of-work), and call any of the 400 tools (or 100 packs).

Add your own tool (~15 lines)

A tool is just an object in a kit array. Drop this into any file in src/tools/ (e.g. append to AGENT_TOOLS in src/tools/agent-kit.js) and it's live — routed, schema-published, MCP-exposed, and covered by the "every tool answers its own example" CI check:

{
  route: "POST /api/reverse",
  name: "Reverse text",
  slug: "reverse",
  category: "text",
  price: "$0.001",                       // free via proof-of-work for pure-CPU tools
  description: "Reverse a string. Example: {\"text\":\"abc\"} → {\"reversed\":\"cba\"}",
  discovery: {
    inputSchema: { properties: { text: { type: "string" } }, required: ["text"] },
    example: { text: "abc" },            // CI calls this and checks it works
  },
  handler: (input) => {
    if (typeof input.text !== "string") { const e = new Error('"text" required'); e.statusCode = 400; throw e; }
    return { reversed: [...input.text].reverse().join("") };
  },
}

That's the whole contract: handler(input) returns a JSON-serializable object (or throws an Error with .statusCode for a 4xx). Pure-CPU tools are automatically free-via-proof-of-work; tools that hit the network or disk stay wallet-only. See CONTRIBUTING.md for the full walkthrough.

Optional: charge per call with x402

The same server can require payment per call — useful if you host a public instance. Payments are the default posture: a bare npm start fails closed, exiting unless WALLET_ADDRESS is set — running without payments is the explicit opt-in (FREE_MODE=true npm start). To charge, set WALLET_ADDRESS

• CDP facilitator keys (free at portal.cdp.coinbase.com) and agents pay in USDC on Base (or Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Stellar, Algorand — or USDG on Robinhood Chain via PAYMENT_NETWORKS=…,robinhood + ROBINHOOD_FACILITATOR_URL) via standard x402 clients:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agent402.tools/api/extract", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/article" }),
});

MPP dual-stack. The paywall also speaks MPP (Machine Payments Protocol — the IETF-track Payment HTTP auth scheme from tempoxyz/mpp): the same 402 carries a WWW-Authenticate: Payment challenge, Authorization: Payment credentials settle identically (EIP-3009 USDC, same facilitator, same price), and settled responses return a Payment-Receipt. An mppx client works out of the box; set MPP_SECRET_KEY to enable it on your own instance. Same URL either way — the buyer's client picks the dialect.

Agents without a wallet still use every pure-CPU tool by solving a single-use sha256 proof-of-work (sub-second; the MCP servers do it automatically). Details: wiki: Paying with x402 · Paying with Compute.

Why it's solid

• Everything is tested — CI calls all 500+ tools with their own documented examples and blocks the release on any failure; a production heartbeat checks the live instance every 15 minutes.
• Hardened — connect-time SSRF guard on every URL tool (DNS-rebind safe), proof-of-work that's signed/single-use/slug-scoped, per-IP rate limits, and security headers. See wiki: Security Model.
• Deterministic — no model in the serving path, so the same input always gives the same output, with full OpenAPI schemas.
• Auditable, on-chain revenue — every paid call settles in USDC to agent402.base.eth (a Base name resolving to the public receiving wallet) — verifiable by anyone on Basescan; live counts at /api/stats.
• AGPL-3.0 licensed, self-host-friendly — clone it, strip what you don't need, add what you do.

Agent402 in the x402 ecosystem

x402 is an open payment protocol built on HTTP 402 Payment Required for machine-to-machine, pay-per-call payments in stablecoins (USDC). Most projects in the space are the protocol + SDKs, a starter template, or a payment facilitator. Agent402 is the applied layer — a ready-to-run x402 server that already speaks the protocol and ships 500+ working tools, so you don't have to build the catalog yourself.

• Want the protocol or an SDK? → coinbase/x402.
• Want a server you can run today that actually does things over x402 + MCP? → you're here.
• Self-hostable, deterministic, free via proof-of-work without a wallet, and non-custodial on the payment tools (your agent signs with its own key — Agent402 never holds funds).

Listed in the official MCP Registry and discoverable in the Coinbase x402 Bazaar.

Works with AWS Bedrock AgentCore Payments out of the box — AgentCore orchestrates x402, which is the protocol Agent402 already speaks. Point the AgentCore Gateway at https://agent402.tools/mcp for all 500+ tools, or use agent402-strands for a curated subset inside a Strands agent. Five-minute recipe: wiki: AWS Bedrock AgentCore.

Tollbooth — pay-per-crawl for your site (the other side of x402)

Charge AI crawlers that hit your site. Humans browse free; known bots get 402 Payment Required and can pay in USDC over x402 — or solve a free proof-of-work. The open, crypto-native answer to Cloudflare's closed pay-per-crawl: no CDN lock-in, no Stripe, no merchant-of-record, no signup.

• Product page · pricing · live install: agent402.tools/tollbooth
• Managed Tollbooth Cloud (Solo / Team / Agency / Enterprise): agent402.tools/tollbooth/cloud — join the waitlist
• Run it yourself (MIT, npm): npm i agent402-tollbooth · tollbooth/ · tollbooth/README.md

Runs as Express middleware, a Next.js / Vercel Edge middleware, a Cloudflare Worker, a reverse proxy, or a WordPress plugin (beta). Drop-in templates in tollbooth/deploy/. One Web-Crypto core powers all of them.

Repository map

Legal

• The hosted instance at agent402.tools is provided under its Terms of Service (acceptable-use policy included — using the service, including programmatically, constitutes acceptance) and Privacy Policy.
• AI-gateway traffic (/v1 chat, embeddings, images, speech) is additionally subject to the upstream model providers' usage policies. Wallets used for prohibited content are blocked before settlement (WALLET_BLOCKLIST).
• The server code is AGPL-3.0-licensed (the client SDK, MCP connector, and tollbooth packages are MIT) and provided as-is, without warranty (see LICENSE and NOTICE). "Agent402" and the logo are trademarks of Havok Holdings LLC — the license covers the code, not the name; forks must rename (see TRADEMARKS.md). If you self-host, you are the operator: your deployment, your terms, your compliance — Havok Holdings LLC operates only the hosted instance and is not responsible for third-party deployments.

Contact

• Email: mike@agent402.tools
• X / Twitter: @Agent402Tools
• GitHub: MikeyPetrillo/Agent402

Contributing

PRs that add useful tools, fix bugs, or improve docs are very welcome — see CONTRIBUTING.md. AGPL-3.0 licensed (packages MIT). Maintained by Havok Holdings LLC.