mcp-a2a-bridge

Un servidor MCP que permite a los agentes de codificación — GitHub Copilot CLI, Claude Code, Codex y Hermes — llamar a agentes A2A remotos. También incluye un panel de actividad de solo lectura opcional.

Repositorio: https://github.com/TonPC64/mcp-a2a-bridge

Licenciado bajo la Licencia MIT.

Para instrucciones de agentes de codificación, comienza con AGENTS.md y luego usa skills/setup/SKILL.md para la instalación o skills/contribute/SKILL.md para cambios y PRs.

Presentación de la interfaz del panel

El panel opcional usa una interfaz futurista Liquid Glass con tarjetas de agentes compactas, actividad de tareas en vivo, resúmenes de tareas a dos columnas, indicadores de estado y diseños responsivos. Esta captura de pantalla usa el modo de datos simulados del frontend, por lo que es seguro reproducirla sin conectarse a agentes reales ni exponer registros.

Para ejecutar la misma interfaz simulada localmente:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 127.0.0.1

El modo simulado es solo para desarrollo de UI y capturas de pantalla; las compilaciones normales usan la API en vivo del panel y SSE.

Related MCP server: agntcy-mcp-server

Primeros pasos

Elige tu configuración

Ambos perfiles necesitan Python 3.11 o posterior y uv. El frontend opcional del panel requiere Node.js 24.15 o posterior; CI usa la última versión de Node.js 24.

Solo MCP

Instala y ejecuta solo el puente MCP. Esto no requiere Node.js/npm ni una compilación del frontend del panel.

git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --locked

MCP + panel

Instala el runtime web opcional del panel y luego compila sus assets de frontend incluidos. Node.js y npm solo se necesitan para esta compilación (o para el desarrollo del frontend), no para ejecutar un panel ya compilado.

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

Para desarrollo y pruebas, usa uv sync --all-extras --locked; incluye los paquetes de Python necesarios para la suite de pruebas del panel. Los comandos siguientes usan /absolute/path/to/mcp-a2a-bridge. Reemplázalo con la ruta absoluta de tu clon; no copies la ruta de otro usuario.

Configura los agentes A2A

Crea .a2a-agents.json en la raíz del repositorio:

{
  "agents": {
    "example-agent": {
      "url": "https://agent.example.invalid",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}

Usa la URL base de un agente A2A; el puente solicita su /.well-known/agent-card.json automáticamente. Elimina Authorization (o usa un objeto headers vacío) cuando el agente no requiera autenticación. El registro puede contener secretos, así que no lo confirmes y restringe sus permisos de archivo cuando corresponda.

La ubicación del registro se resuelve en este orden:

1. A2A_BRIDGE_CONFIG

2. .a2a-agents.json en el directorio actual del proceso del puente

3. ~/.config/a2a-bridge/agents.json

Para un host que inicie el comando MCP fuera del repositorio, establece A2A_BRIDGE_CONFIG en una ruta absoluta dentro del entorno MCP de ese host. También puedes añadir un agente verificado en tiempo de ejecución con a2a_add_agent; por defecto escribe en el archivo de registro resuelto.

Registra el servidor MCP

Cada host debe iniciar el mismo comando de la copia local:

uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

Esto usa la instalación editable creada anteriormente. Configura el host con el siguiente marcador de posición de ruta portátil.

GitHub Copilot CLI — añade este servidor a ~/.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 — añade esto a ~/.codex/config.toml:

[mcp_servers.a2a]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/mcp-a2a-bridge", "mcp-a2a-bridge"]

Hermes: usa su UI o comando de registro de servidores MCP, elige un servidor stdio y proporciona el comando uv con estos argumentos:

run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

Reinicia el host después del registro y luego llama a a2a_list_agents para confirmar que el registro está disponible y que los agentes son accesibles.

Herramientas

a2a_send_message espera hasta timeout_s (60 segundos por defecto). Si una tarea sigue en ejecución, devuelve done: false con un task_id; consúltala con a2a_get_task. Si un agente devuelve state: "input_required", llama a a2a_send_message de nuevo con el mismo task_id.

Panel

El panel independiente opcional muestra los agentes configurados, su estado/habilidades y la actividad de tareas en vivo de los procesos del puente en la misma máquina. Es de solo lectura: nunca envía mensajes a los agentes.

Instala el perfil dashboard y compila los assets antes de iniciarlo:

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

Por defecto escucha solo en 127.0.0.1:9100. Abre http://127.0.0.1:9100 en la misma máquina.

Datos simulados del frontend

Para ejecutar la UI del panel sin el servicio Python ni SSE, usa el modo simulado opcional. Incluye agentes representativos y actividad de tareas para capturas de pantalla:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 0.0.0.0

Abre la URL de Vite en la misma red. VITE_USE_MOCK_DATA=true solo lo usa la compilación/servidor de desarrollo del frontend; npm run dev normal y las compilaciones de producción continúan usando la API en vivo del panel y SSE.

Habilita el reporte para cada proceso del puente cuya actividad deba aparecer en el panel. Añade esta variable de entorno a la configuración del servidor MCP (o al lanzarlo manualmente):

A2A_BRIDGE_DASHBOARD=1 uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

Los procesos del puente sin esa marca mantienen la actividad en memoria y no aparecen en el panel compartido. El panel puede iniciarse antes o después de ellos.

Despliegue en LAN

El panel puede exponerse deliberadamente en una LAN de confianza sin token estableciendo un enlace explícito que no sea de bucle local. Este modo no tiene autenticación, así que úsalo solo en una red privada y de confianza; nunca lo expongas a internet público.

Para acceso LAN protegido, establece un token fuerte y coloca el servicio detrás de un proxy inverso que termine TLS con sus propios controles de acceso a la red:

export A2A_BRIDGE_DASHBOARD_HOST=0.0.0.0
export A2A_BRIDGE_DASHBOARD_TOKEN="$(openssl rand -hex 32)"
uv run mcp-a2a-bridge-dashboard

Cuando se establece un token, el HTML del panel, los assets estáticos, las rutas de API y las rutas SSE lo requieren. Los usuarios de navegador lo introducen una vez en /login; la cookie de sesión HttpOnly y same-site resultante permite que EventSource se reconecte normalmente. Los clientes de API pueden enviar en su lugar Authorization: Bearer <token>. El servicio nunca registra el token. Un token autentica el acceso pero no cifra el tráfico, así que no uses el endpoint HTTP directo de LAN a través de redes no confiables; usa HTTPS en el proxy inverso.

Para macOS, la plantilla launchd/com.example.a2a-bridge-dashboard.plist puede ejecutar el panel al iniciar sesión. Reemplaza sus marcadores de posición __REPO__ y __HOME__ antes de instalarla como LaunchAgent.

Desarrollo del frontend del panel

Node.js 24.15+ y npm solo se requieren para trabajar en el frontend o recompilar sus assets incluidos:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev

Vite imprime la URL de desarrollo (normalmente http://localhost:5173). Compila los assets que consume el panel de Python con npm run build.

Servidor A2A de Copilot

El servidor incluido requiere una CLI copilot autenticada:

copilot-a2a-agent --port 9002 --cwd /path/to/default/repository

Se enlaza a 127.0.0.1 porque ejecuta Copilot con --allow-all-tools. Su actividad entrante puede usar el mismo almacén SQLite compartido opcional y se muestra con campos de origen y destino en el panel.

El panel también puede leer el archivo de auditoría nativo de Hermes sin modificar Hermes. Comprueba A2A_BRIDGE_HERMES_AUDIT, luego $HERMES_HOME/a2a_audit.jsonl y luego ~/.hermes/a2a_audit.jsonl.

Desarrollo y pruebas

Ejecuta la suite de pruebas de Python desde la raíz del repositorio:

uv sync --all-extras --locked
uv run pytest -v

Ejecuta las pruebas del panel o haz una compilación de producción del panel desde dashboard/:

npm test
npm run build

CI ejecuta la suite de Python en Python 3.11, valida uv.lock y ejecuta la instalación, las pruebas y la compilación de producción del panel en la última versión de Node.js 24.

tests/test_integration.py ejecuta un agente A2A en el mismo proceso y ejercita el puente de extremo a extremo.