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

The mock mode is for UI development and screenshots only; normal builds use the live dashboard API and SSE.

Related MCP server: agntcy-mcp-server

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 --locked

MCP + 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 build

For 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:

1. A2A_BRIDGE_CONFIG

2. .a2a-agents.json in the bridge process's current directory

3. ~/.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-bridge

This 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-bridge

Codex — 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-bridge

Restart the host after registration, then call a2a_list_agents to confirm that the registry is available and the agents are reachable.

Tools

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-dashboard

It 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.0

Open 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-bridge

Bridge processes without that flag keep activity in memory and do not appear in the shared dashboard. The dashboard can start before or after them.

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-dashboard

When 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 dev

Vite 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/repository

It 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 -v

Run dashboard tests or make a production dashboard build from dashboard/:

npm test
npm run build

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