Agent402 MCP Server

Agent402 — where agents pay agents

A live node in the machine-to-machine economy: 1000+ tools autonomous agents pay for per call in USDC via the x402 protocol — or with proof-of-work, no wallet.

🟢 Live at agent402.tools — USDC on Base mainnet. Built by Mikey Petrillo.

No humans, no signups, no API keys. One program calls an endpoint, gets an HTTP 402 Payment Required quote, settles payment from its own wallet (or with a few seconds of compute), and gets the result. The payment is the identity. Every settled call lands on-chain — live counts and the receiving wallet are at /api/stats.

Watch an agent pay an agent

Run the whole loop yourself — an autonomous buyer discovers the catalog, gets quoted over HTTP 402, settles, and uses the result, with zero human involvement:

node scripts/demo-payment.js                              # pays with compute — no wallet, no funds
AGENT_KEY=0xYOUR_FUNDED_KEY node scripts/demo-payment.js  # settles in real USDC on Base

Connect via MCP (Claude, ChatGPT, any MCP client)

mcp/ ships an MCP server that exposes the whole catalog to any MCP client and settles payment underneath — USDC via x402 with AGENT_KEY set, proof-of-work (free) on the pure-CPU tools without it:

claude mcp add agent402 -- npx -y agent402-mcp          # after npm publish, or:
claude mcp add agent402 -- node /path/to/Agent402/mcp/index.js

High-value tools (extract, render, screenshot, pdf, memory-*, …) are first-class MCP tools; the other ~1000 are reachable through search_tools + call_tool so the model's context window stays small. Test: node mcp/test.js.

The catalogue (1000+ tools, 11 categories — ~1047 free via proof-of-work)

The headline count is real: ~970 of these are individually-discoverable unit conversions (GET /api/convert/{from}-to-{to}), each a genuine endpoint backed by one verified engine and covered by exact-value + round-trip tests (scripts/test-convert.js). The curated tools below are the rest:

Every tool is covered by tests: scripts/test-kit2.js asserts exact outputs for the pure-CPU tools, scripts/test-memory.js covers the coordination layer, and the paid end-to-end test (scripts/agent-e2e.js) buys each endpoint with real USDC and verifies the result.

Free discovery surfaces: /tools (per-tool docs pages), /api/pricing (JSON catalog), /openapi.json (OpenAPI 3.1), /llms.txt (LLM-readable docs), /health.

Memory & coordination — the part agents can't build for themselves

A single, ephemeral, sandboxed agent cannot give itself durable state, a portable identity, a place other agents can reach, atomic coordination primitives, or tamper-evident history. Agent402's memory layer is exactly that — keyed to the paying wallet, no signup:

Two different agents (two wallets) coordinate through one shared namespace: A grants B readwrite, B atomically increments a shared job counter, and the hash-chained log proves who did what. That rendezvous point is not vibe-codable — it requires a persistent, neutral third party with portable identity. See it run:

node scripts/demo-coordination.js   # two wallets: grant → recall → atomic handoff → verifiable audit

Similarity recall (/api/memory/remember + /recall) ships with a local lexical embedder (no key, works out of the box). Point it at any OpenAI-compatible embeddings endpoint for true semantic recall — no code change:

EMBEDDINGS_URL=https://api.openai.com/v1/embeddings
EMBEDDINGS_MODEL=text-embedding-3-small
EMBEDDINGS_API_KEY=sk-...

No wallet? Pay with compute (proof-of-work)

Agents that can't pay USDC can still use the 41 pure-CPU tools by spending CPU instead — a built-in anti-abuse onramp that converts non-payers into integrated users. The browser/network/storage tools (render, screenshot, pdf, memory, extract, http-check, …) stay wallet-only.

import { createHash } from "node:crypto";
const lz = (b) => { let t = 0; for (const x of b) { if (!x) { t += 8; continue; } t += Math.clz32(x) - 24; break; } return t; };
const c = await (await fetch("https://agent402.tools/api/pow/challenge?slug=hash")).json();
let n = 0;                                   // find a nonce with `difficulty` leading zero bits
while (lz(createHash("sha256").update(c.challenge + ":" + n).digest()) < c.difficulty) n++;
const res = await fetch("https://agent402.tools/api/hash", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Pow-Solution": c.token + ":" + n },
  body: JSON.stringify({ text: "hello world" }),
});

Each challenge is signed, single-use, and short-lived; difficulty is tunable via POW_DIFFICULTY. See GET /api/pow for the machine-readable description.

Why agents pay for this instead of building it themselves:

1. Capabilities the sandbox doesn't have. Most agent runtimes have no headless browser, restricted network egress, and no durable disk. render, screenshot, and memory are infrastructure rented by the call.
2. State that survives the session. memory is keyed to the paying wallet — persist findings today, read them next week from a different machine, zero credentials to store or leak.
3. The token math. Writing and debugging a CSV parser or cron calculator mid-task burns 10–100× more in tokens than a tested $0.001 call.
4. One integration, 56 tools. A single x402-wrapped fetch covers the whole catalogue. No per-service SDKs or API-key management.

Deploy on Railway

1. Create the service: in Railway, New Project → Deploy from GitHub repo and pick this repo. The included Dockerfile and railway.toml are picked up automatically.
2. Set environment variables on the service:
   • WALLET_ADDRESS — your Base USDC receiving address (0x…). This is where the money goes.
   • CDP_API_KEY_ID / CDP_API_KEY_SECRET — free keys from portal.cdp.coinbase.com. This enables real-money settlement on Base mainnet and lists your endpoints in the x402 Bazaar so agents can discover and pay you without you lifting a finger.
   • BASE_URL — your public Railway URL (e.g. https://agent402.up.railway.app), used in the docs examples on the landing page.
3. Generate a public domain (Service → Settings → Networking → Generate Domain).

To test without real money first, set NETWORK=base-sepolia and omit the CDP keys (the default x402.org facilitator handles testnet).

Run locally

npm install
FREE_MODE=true npm start          # demo mode, no payments
# or, with payments:
cp .env.example .env              # fill in WALLET_ADDRESS etc.
node --env-file=.env src/server.js

How agents pay

Any x402 v2 client works. Example with @x402/fetch:

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://YOUR-URL/api/extract", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/article" }),
});

Architecture

• src/server.js — Express app and the endpoint catalog (prices, descriptions, discovery schemas).
• src/payments.js — x402 v2 wiring: ExactEvmScheme (USDC on Base), facilitator selection (CDP / custom / testnet default), and Bazaar discovery extensions so agents can find the service.
• src/tools/extract.js — Readability + Turndown for article → markdown; jsdom for metadata parsing.
• src/tools/fetch-guard.js — outbound fetch with SSRF protection (private IP blocking), 5 MB size cap, 15 s timeout.
• src/tools/dns.js — DNS resolution with input validation.