A2A MCP Server

The server supports three communication protocols:

1. stdio (default): Uses standard input/output. Required for Claude Desktop. No HTTP server is started.
2. streamable-http: HTTP transport with streaming support. Recommended for web clients (Claude Web, Cursor, Windsurf) and production deployments. It starts an HTTP server to handle requests and enables streaming of large responses.
3. sse: Server-Sent Events transport. Provides real-time event streaming, useful for real-time updates.

You can install the A2A MCP Server using several methods depending on your environment:

Via Smithery (Recommended for Claude Desktop)

Automatically install for Claude Desktop:

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

Via PyPI

pip install a2a-mcp-server

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

To extend the server's capabilities with new tools, add new methods to the a2a_mcp_server.py file. Each new method must be decorated with @mcp.tool() to be exposed via the Model Context Protocol.

@mcp.tool()
def my_new_tool(param: str) -> str:
    """Description of the tool"""
    return f"Result for {param}"

Claude Desktop requires stdio transport. You can configure it in your claude_desktop_config.json file.

Method 1: PyPI Installation

Add this to the mcpServers section:

"a2a": {
  "command": "uvx",
  "args": [
    "a2a-mcp-server"
  ]
}

Method 2: Local Installation

If running from a cloned repository, specify the absolute paths:

"a2a": {
  "command": "C:\\path\\to\\python.exe",
  "args": [
    "C:\\path\\to\\A2A-MCP-Server\\a2a_mcp_server.py"
  ],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "PYTHONPATH": "C:\\path\\to\\A2A-MCP-Server"
  }
}

Using the Config Creator

You can use the included script to automate this process:

python config_creator.py

For web-based or IDE-based clients (Cursor, Windsurf, Claude Web), you must run the server using the streamable-http transport.

1. Start the server:

   MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

2. Connect the client:

   • Claude Web: In the Tools menu, enable the MCP URL connection using http://127.0.0.1:8000/mcp.
   • Cursor IDE: Go to Settings > AI > MCP Servers, add a new server with URL http://127.0.0.1:8000/mcp, and enable it.
   • Windsurf Browser: Go to Settings > MCP Connections, add a new connection with URL http://127.0.0.1:8000/mcp, and enable it.

The server handles errors and returns specific JSON-RPC error types based on the failure mode:

• JSONParseError: Returned when the request body is not valid JSON (json.decoder.JSONDecodeError).
• InvalidRequestError: Returned when the request body fails Pydantic validation (ValidationError). The error includes the validation data.
• InternalError: Returned for any other unhandled exceptions.

All error responses are wrapped in a JSONRPCResponse and returned with a 400 status code. Successful responses are either returned as JSONResponse (for standard requests) or EventSourceResponse (for streaming requests that return an AsyncIterable).

The A2A MCP Bridge uses JSON files to persist registered agents and task-to-agent mappings across restarts.

By default, these files are stored in the directory specified by A2A_MCP_DATA_DIR (defaults to the current directory):

• registered_agents.json: Stores information about registered agents.
• task_agent_mapping.json: Maps task_ids to their corresponding agent_url to allow result retrieval.

Data is saved automatically on exit and periodically every 5 minutes.

The server's behavior can be customized using the following environment variables:

When using A2AClient, you should handle the following custom exceptions:

• A2AClientHTTPError: Raised when the server returns an error status code (e.g., 4xx or 5xx). It includes the status code and error message.
• A2AClientJSONError: Raised when the server response cannot be parsed as valid JSON.

The A2AServer automatically sets up two routes:

1. POST {endpoint}: The main entrypoint for processing A2ARequest objects. It routes various request types (like SendTaskRequest, CancelTaskRequest, etc.) to the provided TaskManager.
2. GET /.well-known/agent.json: Returns the agent's identity information as a JSON response using the provided agent_card.