# agent-discovery-mcp [![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/agent-discovery-mcp) > An MCP server that lets your AI coding agent (Claude Code, OpenClaw, Codex, Cursor, etc.) **discover and call on-chain agents** — and pay them automatically using Coinbase's x402 protocol. Agents register themselves on [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004), Ethereum's agent identity standard. This server bridges that registry with x402 payment so your existing tool runtime can find and pay arbitrary on-chain agents in a single tool call — no smart account, no bundler, no relay. Just your EOA, an HTTPS request, and an automatic 402 → sign → retry flow. **Who this is for:** developers building or using AI coding agents who want to reach into the on-chain agent ecosystem without wiring up a custom discovery or payment stack. --- ## What it does Three tools, exposed via [Model Context Protocol](https://modelcontextprotocol.io/): | Tool | What it does | Source of truth | |---|---|---| | `find_agents_by_skill` | Search the ERC-8004 registry for agents matching a skill keyword. Returns id, chain, name, description, endpoint, and x402-support flag. | [8004scan.io](https://8004scan.io/) public API + semantic search | | `get_agent_card` | Fetch one agent's full ERC-8004 registration card (name, services, x402 support, trust models, owner address). | 8004scan, falls back to direct RPC | | `call_agent_with_payment` | HTTP call an agent endpoint. If the agent returns `HTTP 402`, sign an x402 payment using your EOA and retry — automatically. | [`x402-fetch`](https://www.npmjs.com/package/x402-fetch) (Coinbase official) | The whole server is ~250 lines of TypeScript. No smart contract account, no bundler, no third-party relay — payment is direct EOA signing per the x402 spec. --- ## Why this exists The pieces of an agent-to-agent economy are now real: - **x402** (Coinbase's HTTP 402-based payment protocol) processes 165M+ transactions and ~$50M in volume as of April 2026. - **ERC-8004** (Ethereum's agent identity standard) was deployed to mainnet on January 29, 2026 and now has tens of thousands of registered agents. - **MCP** (Anthropic's tool-call protocol) is the de-facto standard for connecting AI coding agents to external capability. But there was no clean "glue" that lets a Claude Code / OpenClaw / Cursor user *just discover and pay* an arbitrary on-chain agent from inside their existing tool. Existing options like [`@azeth/mcp-server`](https://www.npmjs.com/package/@azeth/mcp-server) bundle ERC-4337 smart accounts and a custom trust layer on top — which forces a bundler/relay dependency that can fail in practice on testnets. This server skips all of that. It uses: 1. **8004scan public API** for agent discovery (the canonical ERC-8004 indexer maintained by the ERC-8004 team) 2. **Coinbase's official `x402-fetch`** for payment — wraps native `fetch` to handle 402s automatically 3. **viem** for EOA signing — no contract account deployment, no bundler The result: install, set one env var, and your agent runtime can call any x402 agent in the ERC-8004 registry. --- ## Current status This is a working v0.1.0 with real infrastructure underneath it, but the ecosystem is still early. - **Discovery works.** The 8004scan API returns real agents from the ERC-8004 registry (~70k+ registered across chains as of mid-2026). - **Payment works.** The x402 payment flow is end-to-end using Coinbase's official `x402-fetch` library and EOA signing. - **Ecosystem caveat.** Many agents set `x402Support: true` in their metadata but don't enforce a paywall on their endpoint — they accept calls for free or return 404. The flag is self-declared; nobody verifies it yet. Most production x402 traffic today flows through managed platforms (Coinbase Agent.market, AWS Bedrock AgentCore, etc.). The permissionless registry flow is real but early. See [Roadmap](#roadmap) for what's planned next. --- ## Install **Requires Node ≥ 20** ```bash git clone https://github.com/claynsn/agent-discovery-mcp cd agent-discovery-mcp npm install npm run build ``` Set your wallet's private key (this is the EOA that will sign x402 payments): ```bash export TEST_WALLET_KEY=0x...your-64-hex-private-key ``` > `TEST_WALLET_KEY` is only required for `call_agent_with_payment`. The discovery tools (`find_agents_by_skill`, `get_agent_card`) work without it. **macOS LaunchAgent users** (e.g. OpenClaw): use `launchctl setenv` instead, since LaunchAgent processes don't inherit your shell env: ```bash launchctl setenv TEST_WALLET_KEY 0x... ``` --- ## Usage ### With Claude Code Add to `.mcp.json` in your project root or `~/.claude/mcp_settings.json`: ```json { "mcpServers": { "agent-discovery": { "command": "node", "args": ["/absolute/path/to/agent-discovery-mcp/dist/index.js"], "env": { "TEST_WALLET_KEY": "${TEST_WALLET_KEY}" } } } } ``` ### With OpenClaw Add to `~/.openclaw/openclaw.json` under `mcp.servers`: ```json { "mcp": { "servers": { "agent-discovery": { "command": "node", "args": ["/absolute/path/to/agent-discovery-mcp/dist/index.js"], "env": { "TEST_WALLET_KEY": "${TEST_WALLET_KEY}" } } } } } ``` Then `openclaw gateway restart`. ### With Cursor / Cline / any MCP-compatible client Standard MCP stdio server. Point your client at `node /path/to/dist/index.js`. --- ## Example workflow In your AI coding agent, just ask: > Find me 5 agents on Base mainnet that can do text summarization, only ones supporting x402. The agent calls `find_agents_by_skill({ skill_keyword: "summarization", chain_id: 8453, x402_only: true, limit: 5 })` and returns real on-chain agents. Then: > Call agent #25886 at its primary endpoint with the text "...long article...", pay max $0.05 USDC. The agent calls `call_agent_with_payment({ endpoint: "...", payload: { text: "..." }, max_pay_usdc: 0.05, chain_id: 8453 })`. If the server responds 402, the EOA signs an EIP-3009 USDC authorization, retries, and returns the result. --- ## Tools reference ### `find_agents_by_skill` ```typescript { skill_keyword: string; // e.g. "summarization", "code review", "price feed" limit?: number; // 1-50, default 10 chain_id?: number; // e.g. 8453 (Base), 1 (Ethereum), 56 (BSC) x402_only?: boolean; // filter to agents advertising x402 support } ``` ### `get_agent_card` ```typescript { agent_id: number; // ERC-8004 token ID chain_id: number; // e.g. 8453 } ``` ### `call_agent_with_payment` ```typescript { endpoint: string; // full HTTPS URL payload?: unknown; // JSON body (omit for GET) max_pay_usdc: number; // max USDC willing to pay, e.g. 0.10 chain_id?: number; // settlement chain, default 8453 } ``` --- ## Supported chains | Chain ID | Network | x402 settlement | Discovery | |---|---|---|---| | 1 | Ethereum Mainnet | ✅ | ✅ | | 8453 | Base Mainnet | ✅ | ✅ | | 56 | BSC | — | ✅ | | 84532 | Base Sepolia | ✅ | ✅ | | 11155111 | Ethereum Sepolia | ✅ | ✅ | --- ## Architecture ``` ┌───────────────────────┐ ┌──────────────────────┐ │ Claude Code / │ MCP │ agent-discovery-mcp │ │ OpenClaw / Cursor │ ──────▶ │ (this server) │ └───────────────────────┘ stdio └──────────┬───────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌─────────────┐ │ 8004scan │ │ Base RPC │ │ x402-fetch │ │ public API │ │ (fallback) │ │ (Coinbase) │ │ discovery │ │ tokenURI │ │ EOA signs │ └────────────┘ └────────────┘ │ EIP-3009 │ └─────────────┘ ``` No smart-contract account. No bundler. No relay. Your EOA signs, x402-fetch retries, agent's facilitator settles. --- ## CodeGuilds This package is listed on [CodeGuilds](https://codeguilds.dev/packages/agent-discovery-mcp), a directory of MCP servers and AI agent tools. --- ## Roadmap - [ ] Endpoint health check before returning agent in `find_agents_by_skill` (filter out 404 demo deployments) - [ ] Verify on-chain `x402Support` claim by probing endpoint for 402 response - [ ] Multi-chain payment in one call (auto-select cheapest chain for USDC) - [ ] Optional integration with Coinbase Facilitator for settlement metadata - [ ] Spending-limit policy (server-side cap independent of `max_pay_usdc` parameter) - [ ] Receipt logging to disk for tax/audit --- ## License MIT