web3-agents-mcp

Discover, inspect, and verify on-chain AI agents — from any MCP client.

English | 日本語 | 中文 | 한국어

An MCP (Model Context Protocol) server that bridges ERC-8004 agent identity, reputation, and validation registries into tool calls any AI agent can make. One server, every supported chain — each tool takes a chain argument.

📋 Table of contents

• Why

• Quickstart

• Example prompts

• Tools

• Design principles

• Supported chains

• Configuration

• Verification semantics

• Feedback honesty

• Development

• Roadmap

• License

Related MCP server: AgentStamp

🤔 Why

AI agents are starting to hire, pay, and delegate to other agents. ERC-8004 ("Trustless Agents") gives them an on-chain trust layer — identity, reputation, and validation registries on 20+ EVM chains — but until now an LLM agent had no way to read it from inside its tool loop.

web3-agents-mcp closes that gap. Before your agent trusts a counterparty, it can ask: Who owns this agent? Is its registration file authentic? What feedback has it received — and from whom? Has anyone independently validated its work?

🚀 Quickstart

npx web3-agents-mcp

Pre-publish: run from a checkout instead — pnpm install && pnpm build && node dist/server/index.js

Claude Code:

claude mcp add web3-agents -- npx web3-agents-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "web3-agents": {
      "command": "npx",
      "args": ["web3-agents-mcp"]
    }
  }
}

Any other MCP client: spawn npx web3-agents-mcp as a child process and speak MCP over stdio. The server never opens a network port.

💬 Example prompts

Once connected, just ask your agent naturally:

"Which chains does the web3-agents server support?"

"Look up ERC-8004 agent #1 on Base — who owns it and what does it do?"

"Is agent #42's registration file cryptographically verified?"

"Show me the raw feedback entries for agent #1 on Base, including who submitted them."

"Should I trust agent #0 on Polygon for a code-review task? Pull the on-chain facts."

🧰 Tools

Full input/output schemas, defaults, and error codes are generated from source into docs/tools.md (pnpm docs:gen). A real captured transcript is in docs/demo.md.

🛡️ Design principles

🔒 Read-only by design

No private keys, no signing, no write operations — every tool reads public state. An MCP tool surface reachable by an LLM must never have an injection path into on-chain actions (spending funds, changing registrations, submitting feedback). If a task needs a write, it needs a different, explicitly authorized tool — not this one.

⚖️ No scoring by design

There is no numeric score, confidence level, or star rating anywhere in this server's output. It hands back verified on-chain facts plus mandatory honesty caveats; weighing them into a trust decision is the consuming agent's job. A server that quietly compresses "57 feedback entries, all from one address, no independent validation" into a single number is making a judgment call it has no business making on the consumer's behalf.

⛓️ Supported chains

Registry addresses are identical on every chain (CREATE2). Adding a chain is one entry in src/chains/config.ts; agents discover the live list via the list_chains tool, and the chain enum in every tool's schema updates automatically.

⚙️ Configuration

All configuration is via environment variables; every tool call still takes an explicit chain argument, so these are defaults, not global switches.

🔍 Verification semantics

A registration file's verified field means different things depending on how the agent's tokenUri points at it (per the v1 ERC-8004 contracts this server targets):

🧂 Feedback honesty

get_reputation and assess_trust always attach caveats to feedback-derived data, because on-chain feedback has real, structural weaknesses that no aggregation can paper over:

• There is no canonical score scale enforced by the registry; averages are clamped to 0-100 and may overstate quality relative to whatever scale a given client actually used.

• Feedback is submitted by arbitrary addresses and is Sybil-able — nothing stops one party from submitting many entries under different addresses.

These caveats are deterministic and unremovable: they are always present in the output, not an opt-in flag.

🛠️ Development

pnpm install
pnpm dev        # build then run the stdio server
pnpm build      # compile TypeScript to dist/
pnpm test       # run the vitest suite (excludes live-chain fork tests)
pnpm test:fork  # run the live-chain fork tests against public RPCs
pnpm lint       # eslint + prettier --check
pnpm typecheck  # tsc --noEmit
pnpm docs:gen   # regenerate docs/tools.md from the tool schemas

Project layout:

• src/chains — per-chain static config (registry addresses, deployment blocks, RPC URLs).

• src/registry — typed reads against the identity/reputation/validation ERC-8004 contracts.

• src/fetcher — registration-file retrieval, hashing/CID verification, and the sqlite cache.

• src/trust — assess_trust's orchestration, deterministic caveats, and summary text.

• src/indexer — search_agents backend contract and the MVP NullBackend stub.

• src/tools — one module per MCP tool: input/output zod schemas plus the tool function.

• src/server — MCP server wiring, tool registration, and the stdio entry point.

• src/shared — the Result/BridgeError types and the stderr logger used everywhere.

Contributor/agent guidelines live in AGENTS.md.

🗺️ Roadmap

• Local search indexer — real search_agents backend (SQLite log backfill, resumable)

• Endpoint liveness checks — flag agents whose advertised endpoints are dead

• Streamable HTTP transport — hosted/shared deployments

• npm release — npx web3-agents-mcp without a checkout

• More chains (one config entry each)

📄 License

MIT — see LICENSE.