A2A Registry

A Model Context Protocol (MCP) server providing a unified registry for agents implementing the A2A (Agent-to-Agent) protocol. The registry exposes both a REST API and MCP tools for registering, querying, and managing agent metadata.

Features

• Dual API Access: REST API and MCP server running on a single HTTP server

• Intelligent Agent Registration: Automatically fetches AgentCards from URLs using smart routing

• Multiple Storage Backends: JSON file or SQLite database

• Concurrent Access: SSE-based MCP transport allows multiple clients simultaneously

• Full CRUD Operations: Create, read, update, and delete agents

• A2A Protocol Compliant: Uses standard AgentCard model from @a2a-js/sdk

Installation

Usage

Basic Usage

Configuration Options

CLI Options

Using PM2

API Endpoints

REST API

All REST endpoints are under /agents:

List All Agents

Get Agent by Name

Register New Agent

The registry will automatically:

1. Determine the AgentCard URL using intelligent routing

2. Fetch the AgentCard from the URL

3. Validate the AgentCard structure

4. Store it using the agent's name as the primary key

URL Routing Examples:

• https://example.com → Fetches from https://example.com/.well-known/agent-card.json

• https://example.com/my-agent → Fetches from https://example.com/my-agent/.well-known/agent-card.json

• https://cdn.example.com/agent.json → Fetches directly (URL ends with .json)

Update Agent

Delete Agent

MCP Server

The MCP server is available at /mcp using SSE (Server-Sent Events) transport.

Config example

Available MCP Tools

1. a2a_register_agent

   • Register a new agent by URL

   • Parameters: { url: string }

2. a2a_list_agents

   • List all registered agents

   • Parameters: none

3. a2a_get_agent

   • Get agent details by name

   • Parameters: { name: string }

4. a2a_update_agent

   • Update agent by re-fetching AgentCard

   • Parameters: { name: string, url?: string }

5. a2a_delete_agent

   • Delete agent from registry

   • Parameters: { name: string }

Architecture

Key Design Principles

• Service Layer Pattern: AgentService encapsulates all business logic

• No Code Duplication: REST and MCP APIs are thin adapters calling AgentService

• Intelligent Registration: Automatic AgentCard discovery and fetching

• Pluggable Storage: Easy to add new storage backends

• Concurrent Access: Stateless SSE transport for MCP

AgentCard Structure

The registry uses the standard AgentCard model from the A2A protocol. Required fields include:

• name: Agent name (used as primary key)

• description: Agent purpose and capabilities

• url: Primary A2A endpoint URL

• version: Agent version

• capabilities: Supported A2A protocol features

• defaultInputModes: Supported input MIME types

• defaultOutputModes: Supported output MIME types

• skills: Agent's distinct capabilities

See the A2A Protocol Specification for complete details.

Development

Project Structure

Build

Development Mode (with auto-reload)

Clean Build

Error Handling

The registry provides clear, actionable error messages:

• 404: Agent not found

• 409: Agent already exists (use update instead)

• 400: Invalid URL, fetch failure, or validation error

• 500: Internal server error

All errors include helpful messages to guide next steps.

License

MIT

Contributing

Contributions are welcome! Please ensure:

1. Code follows the existing architecture patterns

2. All business logic is in AgentService

3. APIs are thin adapters

4. Tests pass and build succeeds

Support

For issues or questions, please open an issue on GitHub.