home / mcp / mcp-a2a-gateway mcp server

MCP-A2A-Gateway MCP Server

Bridges MCP with the A2A protocol to enable MCP clients to discover, register, and manage A2A agents and tasks.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "yw0nam-mcp_a2a_gateway": {
      "command": "uvx",
      "args": [
        "mcp-a2a-gateway"
      ],
      "env": {
        "MCP_HOST": "0.0.0.0",
        "MCP_PATH": "/mcp",
        "MCP_PORT": "10000",
        "MCP_DATA_DIR": "/Users/your-username/Desktop/data/Copilot/a2a_gateway/",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

You can bridge MCP compatible AI assistants with A2A agents using the MCP-A2A-Gateway. This gateway lets you discover, register, communicate with, and manage tasks across MCP clients and A2A agents through a single, unified interface, enabling powerful cross-protocol workflows without changing your client code.

How to use

You start by running the gateway in stdio mode or via a transport that suits your workflow. Then you register A2A agents you want to connect to, send messages to those agents, and track the resulting tasks. You can fetch task results, list all tasks, and cancel ongoing tasks if needed. In practice, you typically: - Run the gateway with your preferred transport. - Register one or more A2A agents you want to interact with. - Send a message to an agent and receive a task identifier. - Poll or stream the task result as the agent processes the request.

How to install

# Prerequisites
- Python 3.11+
- uvx (for running the gateway)

# Quick start (no installation required):
uvx mcp-a2a-gateway

# With HTTP transport for web clients:
MCP_TRANSPORT=streamable-http MCP_PORT=10000 uvx mcp-a2a-gateway

# With a custom data directory:
MCP_DATA_DIR="/Users/your-username/Desktop/a2a_data" uvx mcp-a2a-gateway

# Run a specific version if needed:
uvx mcp-a2a-gateway==0.1.6

# Multiple env vars:
MCP_TRANSPORT=stdio MCP_DATA_DIR="/custom/path" LOG_LEVEL=DEBUG uvx mcp-a2a-gateway
```
"} ,{

Configuration and notes

The gateway supports multiple transport types and environment variables to customize how it runs. Typical variables you may set include the transport type, host, port, data directory, and log level. The following are commonly used: MCP_TRANSPORT, MCP_HOST, MCP_PORT, MCP_PATH, MCP_DATA_DIR, MCP_REQUEST_TIMEOUT, MCP_REQUEST_IMMEDIATE_TIMEOUT, and LOG_LEVEL. These let you tune how the gateway accepts MCP requests, stores data, and reports status.

Service-to-service interactions are performed through MCP tools exposed by the gateway, including registering A2A agents, sending messages, and retrieving task results or lists. When you configure your MCP client, point it to the gateway via its MCP URL or local transport channel, and start issuing commands to manage agents and tasks.

Connecting Claude Desktop or Copilot to the gateway

You can connect client IDEs or assistants by configuring their MCP server settings to talk to the gateway. Use the provided configurations to register the gateway as an MCP server and point your client to the gateway’s transport channel. For example, configure the client to communicate over stdio or HTTP transport as described in the setup examples. Then your client can register A2A agents, send messages, and fetch task results through the gateway.

Examples and workflows

- Register an A2A agent with the bridge server to enable communication through the gateway. - Send a message to the registered agent and obtain a task_id for the response. - Retrieve the task result using the task_id, or list all tasks to monitor progress. - Cancel a running task if needed.

Security and best practices

Validate agent URLs when registering new A2A agents and restrict access to trusted clients. Use TLS/HTTPS transports where possible and keep your data directory secure. Monitor logs and enable DEBUG only during troubleshooting to avoid verbose output in production.

Troubleshooting

If the gateway does not start, verify your Python version, ensure uvx is installed, and confirm that the environment variables are set correctly for your chosen transport. Check for common issues like incorrect MCP_PORT or missing data directory. If a task fails, inspect the task_id’s status and ensure the target A2A agent URL is reachable.

Notes

Multiple transport modes are supported to fit different deployment scenarios. Use stdio for local development and testing with Claude Desktop or Copilot-style clients. Use streamable-http for web clients that require streaming responses. Server-Sent Events (SSE) is also available for real-time updates.

Available tools

register_agent

list_agents

List all A2A agents currently registered with the gateway.

unregister_agent

Remove a previously registered A2A agent from the gateway by URL.

send_message

Send a message to a registered A2A agent and obtain a task_id for the response.

get_task_result

Retrieve the result of a previously started task using its task_id.

get_task_list

Retrieve a list of all tasks and their statuses.