Content
# agent-discovery-mcp
[](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
