ERC-8004 MCP Server

An MCP (Model Context Protocol) server for querying ERC-8004 AI agent identities. It queries The Graph subgraph for on-chain data and fetches IPFS metadata for full off-chain details.

Features

• Search agents by name with optional protocol filtering (MCP/A2A)
• List agents with pagination, sorting, and protocol filtering
• Get full agent details including contract state, services, identity, and statistics
• Get feedback/reviews with scores, tags, review text, and MCP/A2A context
• Get engagement stats with tag analysis and score distribution
• Get full metadata including off-chain IPFS attributes (certifications, model info, social links, pricing, etc.)

Tools

Tool	Description
search_agents	Search agents by name with optional protocol filter
list_agents	Browse agents with pagination and sorting
get_agent	Get full details for an agent by ID
get_agent_feedback	Get all feedback/reviews for an agent
get_agent_stats	Get engagement metrics and score breakdown
get_agent_metadata	Get full on-chain + off-chain metadata (IPFS)

Setup

yarn install

Usage

stdio mode (Claude Desktop, Cursor, etc.)

yarn dev

HTTP mode (Streamable HTTP)

yarn dev:http

The server starts on http://localhost:3100/mcp by default. Set the PORT environment variable to change it.

Production

yarn build
yarn start          # stdio
yarn start:http     # HTTP

Configuration with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "npx",
      "args": ["tsx", "/path/to/erc-8004-mcp-server/src/index.ts"]
    }
  }
}

Or with the compiled version:

{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "node",
      "args": ["/path/to/erc-8004-mcp-server/dist/index.js"]
    }
  }
}

Configuration with Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "npx",
      "args": ["tsx", "/path/to/erc-8004-mcp-server/src/index.ts"]
    }
  }
}

Or for the HTTP transport:

{
  "mcpServers": {
    "erc-8004-agents": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

Example queries

Once connected, you can ask your AI assistant:

• "Search for fitness agents on ERC-8004"
• "List the most recently created agents with MCP support"
• "Get details for agent 11155111:1213"
• "Show me all the feedback for Larry the Lobster"
• "What are the full metadata attributes for agent 11155111:1213?"
• "Show me the stats and score breakdown for this agent"

Data Sources

• On-chain data: ERC-8004 Subgraph on Sepolia testnet
• Off-chain metadata: IPFS via public gateways (ipfs.io, cloudflare-ipfs.com, dweb.link)