mcp-a2a-bridge
This server lets coding agents call remote A2A agents over MCP, with optional task tracking and an optional read-only dashboard.
List configured A2A agents with their skills and reachability (
a2a_list_agents)Send messages to A2A agents, optionally continuing a task or selecting a provider (
a2a_send_message)Poll the status and output of previously started tasks (
a2a_get_task)Cancel running tasks (
a2a_cancel_task)Register new A2A agents by URL, optionally persisting them to the registry (
a2a_add_agent)Run as an MCP stdio server for GitHub Copilot CLI, Claude Code, Codex, and Hermes
Optionally run a local dashboard showing agents, status, skills, and live task activity
Reads Hermes' native audit file (a2a_audit.jsonl) so the dashboard can display activity from Hermes without modifying Hermes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-a2a-bridge List the available A2A agents and their capabilities."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-a2a-bridge
An MCP server that lets coding agents — GitHub Copilot CLI, Claude Code, Codex, and Hermes — call remote A2A agents. It also includes an optional read-only activity dashboard.
Repository: https://github.com/TonPC64/mcp-a2a-bridge
Licensed under the MIT License.
For coding-agent instructions, start with AGENTS.md, then
use skills/setup/SKILL.md for installation or
skills/contribute/SKILL.md for changes and PRs.
Dashboard UI showcase
The optional dashboard uses a futuristic Liquid Glass interface with compact agent cards, live task activity, two-column task summaries, status indicators, and responsive layouts. This screenshot uses the opt-in frontend mock data mode so it is safe to reproduce without connecting to real agents or exposing logs.

To run the same mock UI locally:
cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 127.0.0.1The mock mode is for UI development and screenshots only; normal builds use the live dashboard API and SSE.
Related MCP server: agentkit-mesh
Getting started
Choose your setup
Both profiles need Python 3.11 or later and uv.
The optional dashboard frontend requires Node.js 24.15 or later; CI uses the
latest Node.js 24 release.
MCP only
Install and run the MCP bridge only. This does not require Node.js/npm or a dashboard frontend build.
git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --lockedMCP + dashboard
Install the optional dashboard web runtime, then build its bundled frontend assets. Node.js and npm are needed only for this build (or frontend development), not to run an already-built dashboard.
git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run buildFor development and tests, use uv sync --all-extras --locked; it includes
the Python packages needed by the dashboard test suite. The commands below use
/absolute/path/to/mcp-a2a-bridge. Replace it with the absolute path to your
clone; do not copy another user's path.
Configure A2A agents
Create .a2a-agents.json in the repository root:
{
"agents": {
"example-agent": {
"url": "https://agent.example.invalid",
"headers": {
"Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN"
}
}
}
}Use the base URL of an A2A agent; the bridge requests its
/.well-known/agent-card.json automatically. Remove Authorization (or use
an empty headers object) when the agent does not require authentication.
The registry can contain secrets, so do not commit it and restrict its file
permissions where appropriate.
The registry location is resolved in this order:
A2A_BRIDGE_CONFIG.a2a-agents.jsonin the bridge process's current directory~/.config/a2a-bridge/agents.json
For a host that starts the MCP command outside the repository, set
A2A_BRIDGE_CONFIG to an absolute path in that host's MCP environment. You
can also add a verified agent at runtime with a2a_add_agent; by default it
writes to the resolved registry file.
Register the MCP server
Each host should start the same local checkout command:
uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridgeThis uses the editable installation created above. Configure the host with the following portable path placeholder.
GitHub Copilot CLI — add this server to ~/.copilot/mcp-config.json:
{
"mcpServers": {
"a2a": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/mcp-a2a-bridge",
"mcp-a2a-bridge"
]
}
}
}Claude Code:
claude mcp add a2a -- uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridgeCodex — add this to ~/.codex/config.toml:
[mcp_servers.a2a]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/mcp-a2a-bridge", "mcp-a2a-bridge"]Hermes: use its MCP server registration UI or command, choose a stdio
server, and supply the command uv with these arguments:
run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridgeRestart the host after registration, then call a2a_list_agents to confirm
that the registry is available and the agents are reachable.
Expose the interactive Codex CLI as A2A (opt-in)
With Codex CLI 0.150.1 installed, run this separate adapter in another terminal:
uv run python examples/run_codex_interactive_a2a.pyIt binds only to 127.0.0.1:9013, publishes
/.well-known/agent-card.json, and registers a temporary unique entry in the
resolved registry. The exact entry is removed on graceful shutdown. It starts
codex app-server --stdio directly; it does not use codex exec or attach to
an existing terminal TUI. Each adapter process starts one new ephemeral
app-server thread. --thread-id ID may resume a known persisted thread only
when app-server reports canAcceptDirectInput: true.
Use --port for another loopback port and --codex-bin when codex is not on
the launcher PATH. The adapter has no public bind, token, or credential-file
configuration.
Tools
Tool | Purpose |
| List agents with skills and reachability |
| Send a message; continue a task with |
| Poll a task started earlier |
| Cancel a running task |
| Register an agent by URL |
a2a_send_message waits up to timeout_s (60 seconds by default). If a task
is still running, it returns done: false with a task_id; poll it with
a2a_get_task. If an agent returns state: "input_required", call
a2a_send_message again with the same task_id.
Dashboard
The optional standalone dashboard shows configured agents, their status/skills, and live task activity from bridge processes on the same machine. It is read-only: it never sends messages to agents.
Install the dashboard profile and build the assets before starting it:
cd /absolute/path/to/mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run build
uv run mcp-a2a-bridge-dashboardIt listens only on 127.0.0.1:9100 by default. Open
http://127.0.0.1:9100 on the same machine.
Frontend mock data
To run the dashboard UI without the Python service or SSE, use the opt-in mock mode. It includes representative agents and task activity for screenshots:
cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 0.0.0.0Open the Vite URL on the same network. VITE_USE_MOCK_DATA=true is only used
by the frontend build/dev server; normal npm run dev and production builds
continue to use the live dashboard API and SSE.
Enable reporting for every bridge process whose activity should appear in the dashboard. Add this environment variable to the MCP server configuration (or when launching it manually):
A2A_BRIDGE_DASHBOARD=1 uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridgeBridge processes without that flag keep activity in memory and do not appear in the shared dashboard. The dashboard can start before or after them.
Environment variable | Default | Purpose |
| — | Absolute path to the agents JSON registry |
| unset (off) | Set to |
|
| Shared SQLite activity database |
|
| Source label for activity written by compatible processes |
|
| Dashboard bind address |
|
| Dashboard port |
| unset (off) | Optional bearer token that protects the dashboard and API |
| unset | Read-only override for Hermes' |
| unset | Used to find |
LAN deployment
The dashboard can be exposed deliberately on a trusted LAN without a token by setting an explicit non-loopback bind. This mode has no authentication, so use it only on a private, trusted network; never expose it to the public internet.
For protected LAN access, set a strong token and put the service behind a TLS-terminating reverse proxy with its own network access controls:
export A2A_BRIDGE_DASHBOARD_HOST=0.0.0.0
export A2A_BRIDGE_DASHBOARD_TOKEN="$(openssl rand -hex 32)"
uv run mcp-a2a-bridge-dashboardWhen a token is set, dashboard HTML, static assets, API routes, and SSE routes
all require it. Browser users enter it once at /login; the resulting
HttpOnly, same-site session cookie lets EventSource reconnect normally. API clients
can instead send Authorization: Bearer <token>. The service never
logs the token. A token authenticates access but does not encrypt traffic, so
do not use the direct HTTP LAN endpoint across untrusted networks; use HTTPS
at the reverse proxy.
For macOS, the launchd/com.example.a2a-bridge-dashboard.plist template can
run the dashboard at login. Replace its __REPO__ and __HOME__ placeholders
before installing it as a LaunchAgent.
Dashboard frontend development
Node.js 24.15+ and npm are only required to work on the frontend or rebuild its bundled assets:
cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run devVite prints the development URL (normally http://localhost:5173). Build the
assets consumed by the Python dashboard with npm run build.
Copilot A2A server
The optional Copilot example requires an authenticated copilot CLI:
PYTHONPATH=examples:src python examples/run_copilot_main_dev.py 9010 --cwd /path/to/default/repositoryIt binds to 127.0.0.1 because it runs Copilot with --allow-all-tools.
Its incoming activity can use the same opt-in shared SQLite store and is
shown with source and destination fields in the dashboard.
The dashboard can also read Hermes' native audit file without modifying
Hermes. It checks A2A_BRIDGE_HERMES_AUDIT, then
$HERMES_HOME/a2a_audit.jsonl, then ~/.hermes/a2a_audit.jsonl.
Development and tests
Run the Python test suite from the repository root:
uv sync --all-extras --locked
uv run pytest -vRun dashboard tests or make a production dashboard build from dashboard/:
npm test
npm run buildCI runs the Python suite on Python 3.11, validates uv.lock, and
runs the dashboard install, tests, and production build on the latest Node.js
24 release.
tests/test_integration.py runs an A2A agent in-process and exercises the
bridge end to end.
Available Tools
5 toolsa2a_add_agentA
Register a new A2A agent by its base URL.
The agent card is fetched first, so an unreachable URL is rejected instead of being saved. With persist=true the agent is written to the shared registry file and stays available in future sessions.
Inputs: url (required), name (required), headers, persist.
a2a_cancel_taskB
Cancel a running A2A task and return its final state.
Inputs: agent (required), task_id (required).
a2a_get_taskA
Get the current state and output of a previously started A2A task.
Inputs: agent (required), task_id (required).
a2a_list_agentsA
List configured A2A agents with their skills and reachability.
Set refresh=true to re-fetch agent cards that were previously cached.
Inputs: refresh.
a2a_send_messageA
Send a message to an A2A agent and return its reply.
Set provider to "litellm-auto" or "github" when the target agent supports provider selection. The selected provider is carried in the message for the local Copilot A2A agent; other agents may ignore it. Pass task_id to continue an existing task, for example to answer an agent that returned state="input_required". If the agent is still working when timeout_s elapses, this returns done=false with a task_id to poll rather than blocking.
Inputs: agent (required), message (required), task_id, provider, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: listing agents, sending messages, getting task state, cancelling tasks, and adding agents. No overlap or ambiguity between them.
All tools follow a consistent 'a2a_' prefix followed by a verb_noun pattern (list_agents, send_message, get_task, cancel_task, add_agent). Naming is predictable and uniform.
Five tools is well-scoped for an A2A bridge: listing, messaging, task management, and agent registration cover the core functionality without being excessive or sparse.
The tool surface covers the essential operations for an A2A bridge. A remove_agent or update_agent tool is missing, but it's not critical; the set supports the primary workflows adequately.
Maintenance
Related MCP Connectors
Public MCP for agent verification, work discovery and governed interoperability.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that gives AI agents the ability to discover, match with, and build relationships with other autonomous agents. Supports agent registration, matchmaking, messaging, shared goals, relationship lifecycle management, and real-time event subscriptions.45 npmMIT

agentkit-meshofficial
AlicenseAqualityFmaintenanceEnables agent-to-agent discovery and delegation via MCP, with tools for registering agents, discovering them by keyword matching, and delegating tasks over HTTP.47 npm1MIT- FlicenseNot gradedqualityBmaintenanceEnables AI agents to discover other agents, publish and match tasks, exchange messages and artifacts, and build transaction-backed reputation over MCP and A2A.-
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to interact with A2A agents through four ordinary tools, translating agent discovery, messaging, task reading, and cancellation between the A2A and MCP protocols, with support for the tasks extension.41 npm2Apache 2.0