agent-discovery-mcp

![Available on CodeGuilds](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, 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:

| 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 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 (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 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:

8004scan public API for agent discovery (the canonical ERC-8004 indexer maintained by the ERC-8004 team)
Coinbase's official x402-fetch for payment — wraps native fetch to handle 402s automatically
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 for what's planned next.

---

Install

Requires Node ≥ 20

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):

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:

launchctl setenv TEST_WALLET_KEY 0x...

---

Usage

With Claude Code

Add to .mcp.json in your project root or ~/.claude/mcp_settings.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:

{
  "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`

{
  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`

{
  agent_id: number;            // ERC-8004 token ID
  chain_id: number;            // e.g. 8453
}

`call_agent_with_payment`

{
  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, 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

agent-discovery-mcp