Integrates with Google's Agent-to-Agent (A2A) protocol, allowing communication and interoperability between AI agents through a standardized JSON-RPC interface.
A2A MCP Server
A mcp 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.
Demo
1, Run The Currency Agent in A2A Sample
also support cloud deployed Agent
2, Use Claude to Register the Currency Agent
3, Use Claude to Send a task to the Currency Agent and get the result
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
Installing via Smithery
To install A2A Bridge Server for Claude Desktop automatically via Smithery:
Option 1: Install from PyPI
Option 2: Local Installation
Clone the repository:
git clone https://github.com/GongRzhe/A2A-MCP-Server.git cd A2A-MCP-ServerSet up a virtual environment:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activateInstall dependencies:
pip install -r requirements.txt
Configuration
Environment Variables
Configure how the MCP server runs using these environment variables:
Transport Types
The A2A MCP Server supports multiple transport types:
stdio (default): Uses standard input/output for communication
Ideal for command-line usage and testing
No HTTP server is started
Required for Claude Desktop
streamable-http (recommended for web clients): HTTP transport with streaming support
Recommended for production deployments
Starts an HTTP server to handle MCP requests
Enables streaming of large responses
sse: Server-Sent Events transport
Provides real-time event streaming
Useful for real-time updates
To specify the transport type:
Running the Server
From Command Line
Configuring in Claude Desktop
Claude Desktop allows you to configure MCP servers in the claude_desktop_config.json
file. This file is typically located at:
Windows:
%APPDATA%\Claude\claude_desktop_config.json
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
Method 1: PyPI Installation (Recommended)
Add the following to the mcpServers
section of your claude_desktop_config.json
:
Note that for Claude Desktop, you must use "MCP_TRANSPORT": "stdio"
since Claude requires stdio communication with MCP servers.
Method 2: Local Installation
If you've cloned the repository and want to run the server from your local installation:
Replace C:\\path\\to\\
with the actual paths on your system.
Using the Config Creator
This repository includes a config_creator.py
script to help you generate the configuration:
The script will:
Automatically detect Python, script, and repository paths when possible
Configure stdio transport which is required for Claude Desktop
Let you add any additional environment variables if needed
Create or update your Claude Desktop configuration file
Complete Example
Here's an example of a complete claude_desktop_config.json
file with the A2A-MCP-Server configured:
Using with MCP Clients
Claude
Claude can use A2A agents through the MCP tools provided by this server. Here's how to set it up:
For Claude Web: Start the MCP server with the streamable-http transport:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-serverFor Claude Web: In Claude web interface, enable the MCP URL connection in your Tools menu.
Use the URL:
http://127.0.0.1:8000/mcp
For Claude Desktop: Add the configuration to your
claude_desktop_config.json
file as described above. The easiest way is to use the providedconfig_creator.py
script which will automatically detect paths and create the proper configuration.In Claude, you can now use the following functions:
Register an A2A agent:
I need to register a new agent. Can you help me with that? (Agent URL: http://localhost:41242)Send message to an agent:
Ask the agent at http://localhost:41242 what it can do.Retrieve task results:
Can you get the results for task ID: 550e8400-e29b-41d4-a716-446655440000?
Cursor IDE
Cursor IDE can connect to MCP servers to add tools to its AI assistant:
Run your A2A MCP server with the streamable-http transport:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-serverIn Cursor IDE, go to Settings > AI > MCP Servers
Add a new MCP Server with URL:
http://127.0.0.1:8000/mcp
Enable the server
Now you can use the A2A tools from within Cursor's AI assistant.
Windsurf Browser
Windsurf is a browser with built-in MCP support:
Run your A2A MCP server with the streamable-http transport:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-serverIn Windsurf browser, go to Settings > MCP Connections
Add a new MCP connection with URL:
http://127.0.0.1:8000/mcp
Enable the connection
You can now use A2A tools from within Windsurf's AI assistant.
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
Example with Claude as the MCP Client
Architecture
The A2A MCP server consists of several key components:
FastMCP Server: Exposes tools to MCP clients
A2A Client: Communicates with registered A2A agents
Task Manager: Handles task forwarding and management
Agent Card Fetcher: Retrieves information about A2A agents
Communication Flow
Task ID Management
When sending a message to an A2A agent, the server:
Generates a unique
task_id
Maps this ID to the agent's URL in the
task_agent_mapping
dictionaryReturns the
task_id
to the MCP clientUses 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)
Transport Issues
If you have issues with a specific transport type:
stdio issues: Ensure input/output streams are not redirected or modified
streamable-http issues: Check if the port is available and not blocked by a firewall
sse issues: Verify the client supports Server-Sent Events
Claude Desktop Configuration Issues
If Claude Desktop isn't starting your A2A-MCP-Server:
Check that the paths in your
claude_desktop_config.json
are correctVerify that Python is in your PATH if using
"command": "python"
For local installation, ensure the PYTHONPATH is correct
Make sure
MCP_TRANSPORT
is set to"stdio"
in theenv
sectionTry running the command manually to see if it works outside of Claude
Use the
config_creator.py
script for automatic path detection and configuration
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
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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A bridge server that enables MCP-compatible AI assistants like Claude to seamlessly discover, communicate with, and manage A2A protocol agents.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that enables Claude to interact with Port.io's AI agent, allowing users to trigger the agent with prompts and receive structured responses including status, output, and action items.Last updated -13MIT License
- -securityAlicense-qualityA Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.Last updated -34The Unlicense
- AsecurityFlicenseAqualityAn MCP server that enables Claude Desktop to communicate with A2A protocol agents, allowing Claude to access extended capabilities through agent interactions.Last updated -320
- AsecurityAlicenseAqualityA bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.Last updated -1611MIT License