Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gongrzhe--a2a-mcp-server/badge.svg)](/listings/gongrzhe--a2a-mcp-server)

HTML

<a href="/listings/gongrzhe--a2a-mcp-server"><img src="/api/listings/gongrzhe--a2a-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Smithery

To install A2A Bridge Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@GongRzhe/A2A-MCP-Server):

npx -y @smithery/cli install @GongRzhe/A2A-MCP-Server --client claude

Option 1: Install from PyPI

pip install a2a-mcp-server

Option 2: Local Installation

1. Clone the repository:

   git clone https://github.com/GongRzhe/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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 521 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # A2A MCP Server
  2. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. ![](https://badge.mcpx.dev?type=server 'MCP Server')
  4. [![smithery badge](https://smithery.ai/badge/@GongRzhe/A2A-MCP-Server)](https://smithery.ai/server/@GongRzhe/A2A-MCP-Server)
  5. 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.
  6. ## Overview
  7. This project serves as an integration layer between two cutting-edge AI agent protocols:
  8. - **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.
  9. - **Agent-to-Agent Protocol (A2A)**: Developed by Google, A2A enables communication and interoperability between different AI agents through a standardized JSON-RPC interface.
  10. 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.
  11. ### Demo
  12. #### 1, Run The Currency Agent in A2A Sample
  13. ![agent](public/agent.png)
  14. `also support cloud deployed Agent`
  15. ![cloudAgent](https://github.com/user-attachments/assets/481cbf01-95a0-4b0a-9ac5-898aef66a944)
  16. #### 2, Use Claude to Register the Currency Agent
  17. ![register](public/register.png)
  18. #### 3, Use Claude to Send a task to the Currency Agent and get the result
  19. ![task](public/task.png)
  20. ## Features
  21. - **Agent Management**
  22. - Register A2A agents with the bridge server
  23. - List all registered agents
  24. - Unregister agents when no longer needed
  25. - **Communication**
  26. - Send messages to A2A agents and receive responses
  27. - Stream responses from A2A agents in real-time
  28. - **Task Management**
  29. - Track which A2A agent handles which task
  30. - Retrieve task results using task IDs
  31. - Cancel running tasks
  32. - **Transport Support**
  33. - Multiple transport types: stdio, streamable-http, SSE
  34. - Configure transport type using MCP_TRANSPORT environment variable
  35. ## Installation
  36. ### Installing via Smithery
  37. To install A2A Bridge Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@GongRzhe/A2A-MCP-Server):
  38. ```bash
  39. npx -y @smithery/cli install @GongRzhe/A2A-MCP-Server --client claude
  40. ```
  41. ### Option 1: Install from PyPI
  42. ```bash
  43. pip install a2a-mcp-server
  44. ```
  45. ### Option 2: Local Installation
  46. 1. Clone the repository:
  47. ```bash
  48. git clone https://github.com/GongRzhe/A2A-MCP-Server.git
  49. cd A2A-MCP-Server
  50. ```
  51. 2. Set up a virtual environment:
  52. ```bash
  53. python -m venv .venv
  54. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  55. ```
  56. 3. Install dependencies:
  57. ```bash
  58. pip install -r requirements.txt
  59. ```
  60. ## Configuration
  61. ### Environment Variables
  62. Configure how the MCP server runs using these environment variables:
  63. ```bash
  64. # Transport type: stdio, streamable-http, or sse
  65. export MCP_TRANSPORT="streamable-http"
  66. # Host for the MCP server
  67. export MCP_HOST="0.0.0.0"
  68. # Port for the MCP server (when using HTTP transports)
  69. export MCP_PORT="8000"
  70. # Path for the MCP server endpoint (when using HTTP transports)
  71. export MCP_PATH="/mcp"
  72. # Path for SSE endpoint (when using SSE transport)
  73. export MCP_SSE_PATH="/sse"
  74. # Enable debug logging
  75. export MCP_DEBUG="true"
  76. ```
  77. ### Transport Types
  78. The A2A MCP Server supports multiple transport types:
  79. 1. **stdio** (default): Uses standard input/output for communication
  80. - Ideal for command-line usage and testing
  81. - No HTTP server is started
  82. - Required for Claude Desktop
  83. 2. **streamable-http** (recommended for web clients): HTTP transport with streaming support
  84. - Recommended for production deployments
  85. - Starts an HTTP server to handle MCP requests
  86. - Enables streaming of large responses
  87. 3. **sse**: Server-Sent Events transport
  88. - Provides real-time event streaming
  89. - Useful for real-time updates
  90. To specify the transport type:
  91. ```bash
  92. # Using environment variable
  93. export MCP_TRANSPORT="streamable-http"
  94. uvx a2a-mcp-server
  95. # Or directly in the command
  96. MCP_TRANSPORT=streamable-http uvx a2a-mcp-server
  97. ```
  98. ## Running the Server
  99. ### From Command Line
  100. ```bash
  101. # Using default settings (stdio transport)
  102. uvx a2a-mcp-server
  103. # Using HTTP transport on specific host and port
  104. MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8080 uvx a2a-mcp-server
  105. ```
  106. ## Configuring in Claude Desktop
  107. Claude Desktop allows you to configure MCP servers in the `claude_desktop_config.json` file. This file is typically located at:
  108. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  109. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  110. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  111. ### Method 1: PyPI Installation (Recommended)
  112. Add the following to the `mcpServers` section of your `claude_desktop_config.json`:
  113. ```json
  114. "a2a": {
  115. "command": "uvx",
  116. "args": [
  117. "a2a-mcp-server"
  118. ]
  119. }
  120. ```
  121. Note that for Claude Desktop, you must use `"MCP_TRANSPORT": "stdio"` since Claude requires stdio communication with MCP servers.
  122. ### Method 2: Local Installation
  123. If you've cloned the repository and want to run the server from your local installation:
  124. ```json
  125. "a2a": {
  126. "command": "C:\\path\\to\\python.exe",
  127. "args": [
  128. "C:\\path\\to\\A2A-MCP-Server\\a2a_mcp_server.py"
  129. ],
  130. "env": {
  131. "MCP_TRANSPORT": "stdio",
  132. "PYTHONPATH": "C:\\path\\to\\A2A-MCP-Server"
  133. }
  134. }
  135. ```
  136. Replace `C:\\path\\to\\` with the actual paths on your system.
  137. ### Using the Config Creator
  138. This repository includes a `config_creator.py` script to help you generate the configuration:
  139. ```bash
  140. # If using local installation
  141. python config_creator.py
  142. ```
  143. The script will:
  144. - Automatically detect Python, script, and repository paths when possible
  145. - Configure stdio transport which is required for Claude Desktop
  146. - Let you add any additional environment variables if needed
  147. - Create or update your Claude Desktop configuration file
  148. ### Complete Example
  149. Here's an example of a complete `claude_desktop_config.json` file with the A2A-MCP-Server configured:
  150. ```json
  151. {
  152. "mcpServers": {
  153. "a2a": {
  154. "command": "uvx",
  155. "args": [
  156. "a2a-mcp-server"
  157. ]
  158. }
  159. }
  160. }
  161. ```
  162. ## Using with MCP Clients
  163. ### Claude
  164. Claude can use A2A agents through the MCP tools provided by this server. Here's how to set it up:
  165. 1. For Claude Web: Start the MCP server with the streamable-http transport:
  166. ```bash
  167. MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server
  168. ```
  169. 2. For Claude Web: In Claude web interface, enable the MCP URL connection in your Tools menu.
  170. - Use the URL: `http://127.0.0.1:8000/mcp`
  171. 3. For Claude Desktop: Add the configuration to your `claude_desktop_config.json` file as described above. The easiest way is to use the provided `config_creator.py` script which will automatically detect paths and create the proper configuration.
  172. 4. In Claude, you can now use the following functions:
  173. **Register an A2A agent:**
  174. ```
  175. I need to register a new agent. Can you help me with that?
  176. (Agent URL: http://localhost:41242)
  177. ```
  178. **Send message to an agent:**
  179. ```
  180. Ask the agent at http://localhost:41242 what it can do.
  181. ```
  182. **Retrieve task results:**
  183. ```
  184. Can you get the results for task ID: 550e8400-e29b-41d4-a716-446655440000?
  185. ```
  186. ### Cursor IDE
  187. Cursor IDE can connect to MCP servers to add tools to its AI assistant:
  188. 1. Run your A2A MCP server with the streamable-http transport:
  189. ```bash
  190. MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server
  191. ```
  192. 2. In Cursor IDE, go to Settings > AI > MCP Servers
  193. - Add a new MCP Server with URL: `http://127.0.0.1:8000/mcp`
  194. - Enable the server
  195. 3. Now you can use the A2A tools from within Cursor's AI assistant.
  196. ### Windsurf Browser
  197. Windsurf is a browser with built-in MCP support:
  198. 1. Run your A2A MCP server with the streamable-http transport:
  199. ```bash
  200. MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server
  201. ```
  202. 2. In Windsurf browser, go to Settings > MCP Connections
  203. - Add a new MCP connection with URL: `http://127.0.0.1:8000/mcp`
  204. - Enable the connection
  205. 3. You can now use A2A tools from within Windsurf's AI assistant.
  206. ## Available MCP Tools
  207. The server exposes the following MCP tools for integration with LLMs like Claude:
  208. ### Agent Management
  209. - **register_agent**: Register an A2A agent with the bridge server
  210. ```json
  211. {
  212. "name": "register_agent",
  213. "arguments": {
  214. "url": "http://localhost:41242"
  215. }
  216. }
  217. ```
  218. - **list_agents**: Get a list of all registered agents
  219. ```json
  220. {
  221. "name": "list_agents",
  222. "arguments": {}
  223. }
  224. ```
  225. - **unregister_agent**: Remove an A2A agent from the bridge server
  226. ```json
  227. {
  228. "name": "unregister_agent",
  229. "arguments": {
  230. "url": "http://localhost:41242"
  231. }
  232. }
  233. ```
  234. ### Message Processing
  235. - **send_message**: Send a message to an agent and get a task_id for the response
  236. ```json
  237. {
  238. "name": "send_message",
  239. "arguments": {
  240. "agent_url": "http://localhost:41242",
  241. "message": "What's the exchange rate from USD to EUR?",
  242. "session_id": "optional-session-id"
  243. }
  244. }
  245. ```
  246. - **send_message_stream**: Send a message and stream the response
  247. ```json
  248. {
  249. "name": "send_message_stream",
  250. "arguments": {
  251. "agent_url": "http://localhost:41242",
  252. "message": "Tell me a story about AI agents.",
  253. "session_id": "optional-session-id"
  254. }
  255. }
  256. ```
  257. ### Task Management
  258. - **get_task_result**: Retrieve a task's result using its ID
  259. ```json
  260. {
  261. "name": "get_task_result",
  262. "arguments": {
  263. "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
  264. "history_length": null
  265. }
  266. }
  267. ```
  268. - **cancel_task**: Cancel a running task
  269. ```json
  270. {
  271. "name": "cancel_task",
  272. "arguments": {
  273. "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
  274. }
  275. }
  276. ```
  277. ## Usage Examples
  278. ### Basic Workflow
  279. ```
  280. 1. Client registers an A2A agent
  281. ↓
  282. 2. Client sends a message to the agent (gets task_id)
  283. ↓
  284. 3. Client retrieves the task result using task_id
  285. ```
  286. ### Example with Claude as the MCP Client
  287. ```
  288. User: Register an agent at http://localhost:41242
  289. Claude uses: register_agent(url="http://localhost:41242")
  290. Claude: Successfully registered agent: ReimbursementAgent
  291. User: Ask the agent what it can do
  292. Claude uses: send_message(agent_url="http://localhost:41242", message="What can you do?")
  293. Claude: I've sent your message. Here's the task_id: b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1
  294. User: Get the answer to my question
  295. Claude uses: get_task_result(task_id="b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1")
  296. 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."
  297. ```
  298. ## Architecture
  299. The A2A MCP server consists of several key components:
  300. 1. **FastMCP Server**: Exposes tools to MCP clients
  301. 2. **A2A Client**: Communicates with registered A2A agents
  302. 3. **Task Manager**: Handles task forwarding and management
  303. 4. **Agent Card Fetcher**: Retrieves information about A2A agents
  304. ### Communication Flow
  305. ```
  306. MCP Client → FastMCP Server → A2A Client → A2A Agent
  307. ↑ ↓
  308. └──── Response ──┘
  309. ```
  310. ## Task ID Management
  311. When sending a message to an A2A agent, the server:
  312. 1. Generates a unique `task_id`
  313. 2. Maps this ID to the agent's URL in the `task_agent_mapping` dictionary
  314. 3. Returns the `task_id` to the MCP client
  315. 4. Uses this mapping to route task retrieval and cancellation requests
  316. ## Error Handling
  317. The server provides detailed error messages for common issues:
  318. - Agent not registered
  319. - Task ID not found
  320. - Connection errors to agents
  321. - Parsing errors in responses
  322. ## Troubleshooting
  323. ### Agent Registration Issues
  324. If an agent can't be registered:
  325. - Verify the agent URL is correct and accessible
  326. - Check if the agent has a proper agent card at `/.well-known/agent.json`
  327. ### Message Delivery Problems
  328. If messages aren't being delivered:
  329. - Ensure the agent is registered (use `list_agents`)
  330. - Verify the agent is running and accessible
  331. ### Task Result Retrieval Issues
  332. If you can't retrieve a task result:
  333. - Make sure you're using the correct task_id
  334. - Check if too much time has passed (some agents might discard old tasks)
  335. ### Transport Issues
  336. If you have issues with a specific transport type:
  337. - **stdio issues**: Ensure input/output streams are not redirected or modified
  338. - **streamable-http issues**: Check if the port is available and not blocked by a firewall
  339. - **sse issues**: Verify the client supports Server-Sent Events
  340. ### Claude Desktop Configuration Issues
  341. If Claude Desktop isn't starting your A2A-MCP-Server:
  342. - Check that the paths in your `claude_desktop_config.json` are correct
  343. - Verify that Python is in your PATH if using `"command": "python"`
  344. - For local installation, ensure the PYTHONPATH is correct
  345. - Make sure `MCP_TRANSPORT` is set to `"stdio"` in the `env` section
  346. - Try running the command manually to see if it works outside of Claude
  347. - Use the `config_creator.py` script for automatic path detection and configuration
  348. ## Development
  349. ### Adding New Tool Methods
  350. To add new capabilities to the server, add methods decorated with `@mcp.tool()` in the `a2a_mcp_server.py` file.
  351. ### Custom Task Manager
  352. The server uses a custom `A2AServerTaskManager` class that extends `InMemoryTaskManager`. You can customize its behavior by modifying this class.
  353. ## Project Structure
  354. ```
  355. a2a-mcp-server/
  356. ├── a2a_mcp_server.py # Main server implementation
  357. ├── common/ # A2A protocol code (from google/A2A)
  358. │ ├── client/ # A2A client implementation
  359. │ ├── server/ # A2A server implementation
  360. │ ├── types.py # Common type definitions
  361. │ └── utils/ # Utility functions
  362. ├── config_creator.py # Script to help create Claude Desktop configuration
  363. ├── .gitignore # Git ignore file
  364. ├── pyproject.toml # Project metadata and dependencies
  365. ├── README.md # This file
  366. └── requirements.txt # Project dependencies
  367. ```
  368. ## License
  369. This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.
  370. The code in the `common/` directory is from the [Google A2A project](https://github.com/google/A2A) and is also licensed under the Apache License, Version 2.0.
  371. ## Acknowledgments
  372. - Anthropic for the [Model Context Protocol](https://modelcontextprotocol.io/)
  373. - Google for the [Agent-to-Agent Protocol](https://github.com/google/A2A)
  374. - Contributors to the FastMCP library

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.