# 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