One-hop tool discovery for AI agents (and humans) using signed .well-known catalogs

Most people know MCP for connecting AI agents to third-party tools, but there's an elegant approach using signed .well-known catalogs that lets anyone - agents, developers, or automation scripts - discover your entire internal tool ecosystem in a single hop.

• AI Agents: Autonomous tool discovery and intelligent selection
• Developers: Quick discovery of internal APIs and services
• DevOps Teams: Simplified tool inventory and automation
• Organizations: Scalable tool ecosystems without complex registries

Organizations have hundreds of internal tools (APIs, MCP servers, services) but:

• AI agents can't find or use them effectively
• Developers waste time hunting for the right API
• Tool sprawl grows faster than documentation
• Complex registries become bottlenecks and single points of failure

Drop one signed file at /.well-known/api-catalog and everyone discovers your tools instantly:

• One HTTP GET replaces complex service discovery
• Complete usage context - auth, examples, error patterns
• Cryptographically signed for security and integrity
• Human + AI readable - same catalog, different interfaces

EAT and MCP are peer protocols, not hierarchical. This is a fundamental design principle that applies universally across all platforms:

graph TB
    subgraph "AI Application Layer"
        AGENT[AI Agent/Application]
    end
    
    subgraph "Protocol Layer (Parallel & Independent)"
        MCP[MCP Client]
        EAT[EAT Client]
    end
    
    subgraph "Tool Ecosystem"
        MCP_SERVERS[MCP Servers<br/>Context & AI-Native Tools]
        HTTP_APIS[HTTP/REST APIs<br/>Web Services]
        GRAPHQL[GraphQL APIs<br/>Data Services]
        EAT_CATALOGS[EAT Catalogs<br/>Tool Directories]
    end
    
    AGENT --> MCP
    AGENT --> EAT
    MCP --> MCP_SERVERS
    EAT --> HTTP_APIS
    EAT --> GRAPHQL
    EAT --> EAT_CATALOGS
    
    %% Optional Bridge (not dependency)
    EAT -.->|Optional Bridge| MCP_SERVERS

git clone https://github.com/foofork/eat.git
cd eat/demo && ./quickstart.sh
open http://localhost:8000  # Interactive catalog browser

import asyncio
from eat import Catalog

async def main():
    catalog = Catalog("http://localhost:8000/.well-known/api-catalog")
    await catalog.fetch()
    
    # Find and use a tool
    tool = catalog.find(capability="customer")[0]
    result = await tool.call(customer_id=12345)
    print(f"Customer: {result['name']}")

asyncio.run(main())

• 🔍 One-hop discovery - Find all tools from a single catalog URL
• 🔐 Cryptographically secure - JWS signatures with content verification
• 📋 Standards-based - Built on OpenAPI, RFC 8615, and MCP
• 🚀 Zero infrastructure - Just static files, no registries
• 🏗️ Complete demo - Working environment with 3 realistic MCP servers

• 3 MCP Servers: Customer management, Analytics, Notifications
• 13 Production Tools: Complete business workflow examples
• Interactive Browser: Visual catalog exploration at localhost:8000
• Example Agents: Simple and multi-tool workflow demos

• QUICKSTART.md - 10-minute implementation guide
• PROTOCOL.md - Complete protocol specification
• docs/ - Architecture, security, deployment guides

• Python client - Full implementation in 50 lines
• curl scripts - Pure HTTP examples
• OpenAPI specs - Real-world API definitions with x-mcp-tool

The included demo showcases realistic business tools:

from eat import Catalog

catalog = Catalog("http://localhost:8000/.well-known/api-catalog")
await catalog.fetch()
tools = catalog.find(capability="customer-management")
result = await tools[0].call(customer_id=1)

# Discover tools
curl http://localhost:8000/.well-known/api-catalog | jq '.tools[].name'

# Call a tool
curl -X POST http://localhost:3001 \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_customer","arguments":{"customer_id":1}}}'

pip install -r requirements-dev.txt
pytest tests/ -v

# Generate catalog from specs
python -m eat.cli.main generate specs/ --output catalog.json

# Serve locally
python -m eat.cli.main serve --port 8000

eat/
├── README.md                   # This file
├── QUICKSTART.md              # 10-minute tutorial
├── PROTOCOL.md                # Complete protocol spec
├── eat/                       # Python package
├── demo/                      # Working demo environment
├── examples/                  # Implementation examples
├── docs/                      # Complete documentation
└── tests/                     # Test suite

Contributions welcome! Areas for enhancement:

• Additional language implementations (Go, Rust, JavaScript)
• More MCP server examples
• Enhanced security features
• Performance optimizations

See docs/ for detailed guides.

MIT License - see LICENSE for details.

Ready to give your AI agents one-hop tool discovery? Start with the 10-minute tutorial!