MCP Connector

MCP Connector

Agent402 speaks MCP two ways. Both are listed in the official MCP Registry under io.github.MikeyPetrillo/agent402.

1. Hosted connector — zero install (the free tier)

Add https://agent402.tools/mcp as a remote MCP server:

• claude.ai / Claude mobile: Settings → Connectors → Add custom connector → name Agent402, that URL, no auth.
• Claude Code: claude mcp add --transport http agent402 https://agent402.tools/mcp
• Cursor: Settings → MCP → Add new MCP server → name agent402, transport streamable-http, URL https://agent402.tools/mcp. (Or add directly to ~/.cursor/mcp.json.)
• ChatGPT (Pro/Team/Enterprise): Settings → Connectors → Add custom connector → that URL, no auth.
• VS Code (GitHub Copilot Chat with MCP): MCP: Add Server → HTTP → https://agent402.tools/mcp.
• Any client speaking streamable HTTP (the endpoint is stateless — every JSON-RPC message is self-contained).

It exposes four read-only tools (each carries safety annotations):

Tool	Does
find_tool	Describe a task in plain language; returns the best-matching tool(s) ready to call — slug, price, input schema, an example, and the exact call_tool invocation. Skips the token-heavy "explore to find a tool" step
search_tools	Find tools by description across the catalog; returns slugs + input schemas
call_tool	Execute a tool by slug. The ~210 pure-CPU tools run free (rate-limited: 20/min, 120/hr per client); wallet-only tools return paid-path instructions instead of executing
about_agent402	Service description, free-vs-paid breakdown

2. agent402-mcp (npm) — the full catalog, payment underneath

{ "mcpServers": { "agent402": {
  "command": "npx", "args": ["-y", "agent402-mcp"],
  "env": {
    "AGENT_KEY": "0x<funded wallet key — optional>",
    "AGENT402_BUDGET": "1.00",
    "AGENT402_MAX_PER_CALL": "0.01"
  }
} } }

• With AGENT_KEY (an EVM wallet holding USDC on Base, Polygon, or Arbitrum) and/or SOLANA_AGENT_KEY (a Solana wallet holding USDC on Solana): every tool works; each call settles via x402 invisibly under the MCP call. The underlying service also accepts USDC on Stellar and Algorand, and USDG on Robinhood Chain, but this npm server currently signs only EVM and Solana payments. Spend controls (AGENT402_BUDGET, AGENT402_MAX_PER_CALL) are enforced before any payment is signed.
• Without a key: the pure-CPU tools work free via proof-of-work; wallet-only tools explain what they'd cost and how to enable them.

High-value tools (search, extract, render, screenshot, pdf, meta, dns, the memory-* family, …) are first-class MCP tools; the long tail is reachable via search_tools + call_tool to keep your context window small.

Other env knobs: AGENT402_URL (target service), AGENT402_TOOLS (override the first-class tool list).

Choosing between them

	Hosted /mcp	npm agent402-mcp
Install	none	npx
Works in claude.ai	✅	❌ (stdio is Desktop/Code only)
Pure-CPU tools	free, rate-limited	free (PoW), unlimited
Search/browser/PDF/memory	❌ (refused with guidance)	✅ with a funded wallet
Identity	anonymous	your wallet = your identity (unlocks Memory and Coordination)

Troubleshooting

Symptom	Cause / fix
Connector won't connect in claude.ai/Claude Code	Confirm the URL is exactly https://agent402.tools/mcp (HTTPS, no trailing path). In Claude Code, claude mcp list should show agent402 ✓ Connected. If it's mid-deploy it can briefly drop — retry in ~60s.
"Error occurred during tool execution" (transient)	Usually a redeploy window on the host; the same call succeeds on retry. The endpoint is health-gated in CI on every deploy.
call_tool says a field is missing / "must be a number"	Pass params as a JSON object, e.g. {"slug":"unit-convert","params":{"value":42,"from":"kilometers","to":"miles"}}. A stringified object ("{\"value\":42}") is also accepted.
A tool returns "wallet required" / paid-path guidance	That tool (live search, browser render, screenshots, PDFs, durable memory) isn't in the hosted free tier. Run the npm server npx -y agent402-mcp with AGENT_KEY set to a funded Base wallet, or call it over HTTP with any x402 client.
"Free-tier rate limit reached"	The hosted connector is capped at 20 calls/min, 120/hour per client. Wait, or use the npm server with a wallet for unmetered access.
Finding the right tool	Call find_tool with a plain-language task — it returns the best match ready to call (slug + example + the exact call_tool invocation). search_tools is the broader, lower-level search.

More: Paying with x402 · Paying with Compute · Open an issue.