a2a-mcp-server 0.1.0

A bridge server that connects Model Context Protocol (MCP) with Agent-to-Agent (A2A) protocol

A2A MCP Server

A middleware server that bridges the Model Context Protocol (MCP) with the Agent-to-Agent (A2A) protocol, enabling MCP-compatible AI assistants (like Claude) to seamlessly interact with A2A agents.

Overview

This project serves as an integration layer between two cutting-edge AI agent protocols:

• Model Context Protocol (MCP): Developed by Anthropic, MCP allows AI assistants to connect to external tools and data sources. It standardizes how AI applications and large language models connect to external resources in a secure, composable way.

• Agent-to-Agent Protocol (A2A): Developed by Google, A2A enables communication and interoperability between different AI agents through a standardized JSON-RPC interface.

By bridging these protocols, this server allows MCP clients (like Claude) to discover, register, communicate with, and manage tasks on A2A agents through a unified interface.

Features

• Agent Management

  • Register A2A agents with the bridge server
  • List all registered agents
  • Unregister agents when no longer needed

• Communication

  • Send messages to A2A agents and receive responses
  • Stream responses from A2A agents in real-time

• Task Management

  • Track which A2A agent handles which task
  • Retrieve task results using task IDs
  • Cancel running tasks

• Transport Support

  • Multiple transport types: stdio, streamable-http, SSE
  • Configure transport type using MCP_TRANSPORT environment variable

Installation

Prerequisites

• Python 3.11+
• FastMCP library (2.3.4+)
• A2A client library

Setup

1. Clone the repository:

   git clone https://github.com/yourusername/a2a-mcp-server.git
   cd a2a-mcp-server
   

2. Set up a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment variables (optional):

   export MCP_HOST="0.0.0.0"  # Host for the MCP server
   export MCP_PORT="8000"     # Port for the MCP server
   export MCP_TRANSPORT="streamable-http"  # Transport type: stdio, streamable-http, or sse
   

5. Run the server:

   python a2a_mcp_server.py
   

Available MCP Tools

The server exposes the following MCP tools for integration with LLMs like Claude:

Agent Management

• register_agent: Register an A2A agent with the bridge server

  {
    "name": "register_agent",
    "arguments": {
      "url": "http://localhost:41242"
    }
  }
  

• list_agents: Get a list of all registered agents

  {
    "name": "list_agents",
    "arguments": {}
  }
  

• unregister_agent: Remove an A2A agent from the bridge server

  {
    "name": "unregister_agent",
    "arguments": {
      "url": "http://localhost:41242"
    }
  }
  

Message Processing

• send_message: Send a message to an agent and get a task_id for the response

  {
    "name": "send_message",
    "arguments": {
      "agent_url": "http://localhost:41242",
      "message": "What's the exchange rate from USD to EUR?",
      "session_id": "optional-session-id"
    }
  }
  

• send_message_stream: Send a message and stream the response

  {
    "name": "send_message_stream",
    "arguments": {
      "agent_url": "http://localhost:41242",
      "message": "Tell me a story about AI agents.",
      "session_id": "optional-session-id"
    }
  }
  

Task Management

• get_task_result: Retrieve a task's result using its ID

  {
    "name": "get_task_result",
    "arguments": {
      "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
      "history_length": null
    }
  }
  

• cancel_task: Cancel a running task

  {
    "name": "cancel_task",
    "arguments": {
      "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
    }
  }
  

Usage Examples

Basic Workflow

1. Client registers an A2A agent
   ↓
2. Client sends a message to the agent (gets task_id)
   ↓
3. Client retrieves the task result using task_id

Example with Claude as the MCP Client

User: Register an agent at http://localhost:41242

Claude uses: register_agent(url="http://localhost:41242")
Claude: Successfully registered agent: ReimbursementAgent

User: Ask the agent what it can do

Claude uses: send_message(agent_url="http://localhost:41242", message="What can you do?")
Claude: I've sent your message. Here's the task_id: b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1

User: Get the answer to my question

Claude uses: get_task_result(task_id="b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1")
Claude: The agent replied: "I can help you process reimbursement requests. Just tell me what you need to be reimbursed for, including the date, amount, and purpose."

Architecture

The A2A MCP server consists of several key components:

1. FastMCP Server: Exposes tools to MCP clients
2. A2A Client: Communicates with registered A2A agents
3. Task Manager: Handles task forwarding and management
4. Agent Card Fetcher: Retrieves information about A2A agents

Communication Flow

MCP Client → FastMCP Server → A2A Client → A2A Agent
                   ↑                ↓
                   └──── Response ──┘

Task ID Management

When sending a message to an A2A agent, the server:

1. Generates a unique task_id
2. Maps this ID to the agent's URL in the task_agent_mapping dictionary
3. Returns the task_id to the MCP client
4. Uses this mapping to route task retrieval and cancellation requests

Error Handling

The server provides detailed error messages for common issues:

• Agent not registered
• Task ID not found
• Connection errors to agents
• Parsing errors in responses

Troubleshooting

Agent Registration Issues

If an agent can't be registered:

• Verify the agent URL is correct and accessible
• Check if the agent has a proper agent card at /.well-known/agent.json

Message Delivery Problems

If messages aren't being delivered:

• Ensure the agent is registered (use list_agents)
• Verify the agent is running and accessible

Task Result Retrieval Issues

If you can't retrieve a task result:

• Make sure you're using the correct task_id
• Check if too much time has passed (some agents might discard old tasks)

Development

Adding New Tool Methods

To add new capabilities to the server, add methods decorated with @mcp.tool() in the a2a_mcp_server.py file.

Custom Task Manager

The server uses a custom A2AServerTaskManager class that extends InMemoryTaskManager. You can customize its behavior by modifying this class.

Project Structure

a2a-mcp-server/
├── a2a_mcp_server.py      # Main server implementation
├── common/                # A2A protocol code (from google/A2A)
│   ├── client/            # A2A client implementation
│   ├── server/            # A2A server implementation
│   ├── types.py           # Common type definitions
│   └── utils/             # Utility functions
├── .gitignore             # Git ignore file
├── pyproject.toml         # Project metadata and dependencies
├── README.md              # This file
└── requirements.txt       # Project dependencies

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

The code in the common/ directory is from the Google A2A project and is also licensed under the Apache License, Version 2.0.

Acknowledgments

• Anthropic for the Model Context Protocol
• Google for the Agent-to-Agent Protocol
• Contributors to the FastMCP library