Labsco
GongRzhe logo

A2A MCP Server

★ 147

from GongRzhe

A bridge server connecting Model Context Protocol (MCP) with Agent-to-Agent (A2A) protocol.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#devops#git

A2A MCP Server

License smithery badge

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

agent

also support cloud deployed Agent

cloudAgent

2, Use Claude to Register the Currency Agent

register

3, Use Claude to Send a task to the Currency Agent and get the result

task

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

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:

  1. For Claude Web: Start the MCP server with the streamable-http transport:

    Copy & paste — that's it
    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. For 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

  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.

  4. In Claude, you can now use the following functions:

    Register an A2A agent:

    Copy & paste — that's it
    I need to register a new agent. Can you help me with that?
(Agent URL: http://localhost:41242)

    Send message to an agent:

    Copy & paste — that's it
    Ask the agent at http://localhost:41242 what it can do.

    Retrieve task results:

    Copy & paste — that's it
    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:

  1. Run your A2A MCP server with the streamable-http transport:

    Copy & paste — that's it
    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. In 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

  3. Now you can use the A2A tools from within Cursor's AI assistant.

Windsurf Browser

Windsurf is a browser with built-in MCP support:

  1. Run your A2A MCP server with the streamable-http transport:

    Copy & paste — that's it
    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. In Windsurf browser, go to Settings > MCP Connections

    • Add a new MCP connection with URL: http://127.0.0.1:8000/mcp
    • Enable the connection

  3. 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

    Copy & paste — that's it
    {
  "name": "register_agent",
  "arguments": {
    "url": "http://localhost:41242"
  }
}

  • list_agents: Get a list of all registered agents

    Copy & paste — that's it
    {
  "name": "list_agents",
  "arguments": {}
}

  • unregister_agent: Remove an A2A agent from the bridge server

    Copy & paste — that's it
    {
  "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

    Copy & paste — that's it
    {
  "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

    Copy & paste — that's it
    {
  "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

    Copy & paste — that's it
    {
  "name": "get_task_result",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
    "history_length": null
  }
}

  • cancel_task: Cancel a running task

    Copy & paste — that's it
    {
  "name": "cancel_task",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
  }
}

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

Copy & paste — that's it
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

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

Copy & paste — that's it
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
├── config_creator.py      # Script to help create Claude Desktop configuration
├── .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