A2A MCP Server

Un servidor puente que conecta el Protocolo de Contexto de Modelo (MCP) con el protocolo Agente a Agente (A2A).

GitHub
148
Prueba este MCPPatrocinado

Documentación

Servidor MCP A2A

License smithery badge

Un servidor MCP que conecta el Protocolo de Contexto de Modelos (MCP) con el protocolo Agente-a-Agente (A2A), permitiendo que asistentes de IA compatibles con MCP (como Claude) interactúen sin problemas con agentes A2A.

Descripción General

Este proyecto actúa como una capa de integración entre dos protocolos de agentes de IA de vanguardia:

  • Protocolo de Contexto de Modelos (MCP): Desarrollado por Anthropic, MCP permite a los asistentes de IA conectarse a herramientas y fuentes de datos externas. Estandariza cómo las aplicaciones de IA y los modelos de lenguaje grandes se conectan a recursos externos de manera segura y componible.

  • Protocolo Agente-a-Agente (A2A): Desarrollado por Google, A2A permite la comunicación e interoperabilidad entre diferentes agentes de IA a través de una interfaz JSON-RPC estandarizada.

Al conectar estos protocolos, este servidor permite que los clientes MCP (como Claude) descubran, registren, se comuniquen y gestionen tareas en agentes A2A a través de una interfaz unificada.

Demostración

1, Ejecutar el Agente de Moneda en el Ejemplo A2A

agent

also support cloud deployed Agent

cloudAgent

2, Usar Claude para Registrar el Agente de Moneda

register

3, Usar Claude para Enviar una tarea al Agente de Moneda y obtener el resultado

task

Características

  • Gestión de Agentes

    • Registrar agentes A2A con el servidor puente
    • Listar todos los agentes registrados
    • Anular el registro de agentes cuando ya no sean necesarios

  • Comunicación

    • Enviar mensajes a agentes A2A y recibir respuestas
    • Transmitir respuestas de agentes A2A en tiempo real

  • Gestión de Tareas

    • Rastrear qué agente A2A maneja cada tarea
    • Recuperar resultados de tareas usando IDs de tarea
    • Cancelar tareas en ejecución

  • Soporte de Transporte

    • Múltiples tipos de transporte: stdio, streamable-http, SSE
    • Configurar el tipo de transporte usando la variable de entorno MCP_TRANSPORT

Instalación

Instalación vía Smithery

Para instalar A2A Bridge Server para Claude Desktop automáticamente vía Smithery:

npx -y @smithery/cli install @GongRzhe/A2A-MCP-Server --client claude

Opción 1: Instalar desde PyPI

pip install a2a-mcp-server

Opción 2: Instalación Local

  1. Clonar el repositorio:

    git clone https://github.com/GongRzhe/A2A-MCP-Server.git
cd A2A-MCP-Server

  2. Configurar un entorno virtual:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instalar las dependencias:

    pip install -r requirements.txt

Configuración

Variables de Entorno

Configure cómo se ejecuta el servidor MCP usando estas variables de entorno:

# Transport type: stdio, streamable-http, or sse
export MCP_TRANSPORT="streamable-http"

# Host for the MCP server
export MCP_HOST="0.0.0.0"

# Port for the MCP server (when using HTTP transports)
export MCP_PORT="8000"

# Path for the MCP server endpoint (when using HTTP transports)
export MCP_PATH="/mcp"

# Path for SSE endpoint (when using SSE transport)
export MCP_SSE_PATH="/sse"

# Enable debug logging
export MCP_DEBUG="true"

Tipos de Transporte

El Servidor MCP A2A soporta múltiples tipos de transporte:

  1. stdio (predeterminado): Usa entrada/salida estándar para la comunicación

    • Ideal para uso desde línea de comandos y pruebas
    • No se inicia ningún servidor HTTP
    • Requerido para Claude Desktop

  2. streamable-http (recomendado para clientes web): Transporte HTTP con soporte de transmisión

    • Recomendado para implementaciones de producción
    • Inicia un servidor HTTP para manejar solicitudes MCP
    • Permite la transmisión de respuestas grandes

  3. sse: Transporte de Eventos Enviados por el Servidor

    • Proporciona transmisión de eventos en tiempo real
    • Útil para actualizaciones en tiempo real

Para especificar el tipo de transporte:

# Using environment variable
export MCP_TRANSPORT="streamable-http"
uvx a2a-mcp-server

# Or directly in the command
MCP_TRANSPORT=streamable-http uvx a2a-mcp-server

Ejecutar el Servidor

Desde la Línea de Comandos

# Using default settings (stdio transport)
uvx a2a-mcp-server

# Using HTTP transport on specific host and port
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8080 uvx a2a-mcp-server

Configuración en Claude Desktop

Claude Desktop le permite configurar servidores MCP en el archivo claude_desktop_config.json. Este archivo normalmente se encuentra en:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Método 1: Instalación desde PyPI (Recomendado)

Agregue lo siguiente a la sección mcpServers de su claude_desktop_config.json:

"a2a": {
  "command": "uvx",
  "args": [
    "a2a-mcp-server"
  ]
}

Tenga en cuenta que para Claude Desktop, debe usar "MCP_TRANSPORT": "stdio" ya que Claude requiere comunicación stdio con los servidores MCP.

Método 2: Instalación Local

Si ha clonado el repositorio y desea ejecutar el servidor desde su instalación local:

"a2a": {
  "command": "C:\\path\\to\\python.exe",
  "args": [
    "C:\\path\\to\\A2A-MCP-Server\\a2a_mcp_server.py"
  ],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "PYTHONPATH": "C:\\path\\to\\A2A-MCP-Server"
  }
}

Reemplace C:\\path\\to\\ con las rutas reales en su sistema.

Usando el Creador de Configuración

Este repositorio incluye un script config_creator.py para ayudarle a generar la configuración:

# If using local installation
python config_creator.py

El script:

  • Detectará automáticamente las rutas de Python, script y repositorio cuando sea posible
  • Configurará el transporte stdio que es requerido para Claude Desktop
  • Le permitirá agregar variables de entorno adicionales si es necesario
  • Creará o actualizará su archivo de configuración de Claude Desktop

Ejemplo Completo

Aquí hay un ejemplo de un archivo claude_desktop_config.json completo con el A2A-MCP-Server configurado:

{
  "mcpServers": {
    "a2a": {
      "command": "uvx",
      "args": [
        "a2a-mcp-server"
      ]
    }
  }
}

Uso con Clientes MCP

Claude

Claude puede usar agentes A2A a través de las herramientas MCP proporcionadas por este servidor. Aquí se explica cómo configurarlo:

  1. Para Claude Web: Inicie el servidor MCP con el transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. Para Claude Web: En la interfaz web de Claude, habilite la conexión URL MCP en su menú de Herramientas.

    • Use la URL: http://127.0.0.1:8000/mcp

  3. Para Claude Desktop: Agregue la configuración a su archivo claude_desktop_config.json como se describió anteriormente. La forma más fácil es usar el script config_creator.py proporcionado, que detectará automáticamente las rutas y creará la configuración adecuada.

  4. En Claude, ahora puede usar las siguientes funciones:

    Registrar un agente A2A:

    I need to register a new agent. Can you help me with that?
(Agent URL: http://localhost:41242)

    Enviar mensaje a un agente:

    Ask the agent at http://localhost:41242 what it can do.

    Recuperar resultados de tareas:

    Can you get the results for task ID: 550e8400-e29b-41d4-a716-446655440000?

IDE Cursor

Cursor IDE puede conectarse a servidores MCP para agregar herramientas a su asistente de IA:

  1. Ejecute su servidor MCP A2A con el transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. En Cursor IDE, vaya a Configuración > IA > Servidores MCP

    • Agregue un nuevo Servidor MCP con URL: http://127.0.0.1:8000/mcp
    • Habilite el servidor

  3. Ahora puede usar las herramientas A2A desde el asistente de IA de Cursor.

Navegador Windsurf

Windsurf es un navegador con soporte MCP integrado:

  1. Ejecute su servidor MCP A2A con el transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. En el navegador Windsurf, vaya a Configuración > Conexiones MCP

    • Agregue una nueva conexión MCP con URL: http://127.0.0.1:8000/mcp
    • Habilite la conexión

  3. Ahora puede usar las herramientas A2A desde el asistente de IA de Windsurf.

Herramientas MCP Disponibles

El servidor expone las siguientes herramientas MCP para integración con LLMs como Claude:

Gestión de Agentes

  • register_agent: Registrar un agente A2A con el servidor puente

    {
  "name": "register_agent",
  "arguments": {
    "url": "http://localhost:41242"
  }
}

  • list_agents: Obtener una lista de todos los agentes registrados

    {
  "name": "list_agents",
  "arguments": {}
}

  • unregister_agent: Eliminar un agente A2A del servidor puente

    {
  "name": "unregister_agent",
  "arguments": {
    "url": "http://localhost:41242"
  }
}

Procesamiento de Mensajes

  • send_message: Enviar un mensaje a un agente y obtener un task_id para la respuesta

    {
  "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: Enviar un mensaje y transmitir la respuesta

    {
  "name": "send_message_stream",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "Tell me a story about AI agents.",
    "session_id": "optional-session-id"
  }
}

Gestión de Tareas

  • get_task_result: Recuperar el resultado de una tarea usando su ID

    {
  "name": "get_task_result",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
    "history_length": null
  }
}

  • cancel_task: Cancelar una tarea en ejecución

    {
  "name": "cancel_task",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
  }
}

Ejemplos de Uso

Flujo de Trabajo Básico

1. Client registers an A2A agent
   ↓
2. Client sends a message to the agent (gets task_id)
   ↓
3. Client retrieves the task result using task_id

Ejemplo con Claude como Cliente MCP

User: Register an agent at http://localhost:41242

Claude uses: register_agent(url="http://localhost:41242")
Claude: Successfully registered agent: ReimbursementAgent

User: Ask the agent what it can do

Claude uses: send_message(agent_url="http://localhost:41242", message="What can you do?")
Claude: I've sent your message. Here's the task_id: b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1

User: Get the answer to my question

Claude uses: get_task_result(task_id="b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1")
Claude: The agent replied: "I can help you process reimbursement requests. Just tell me what you need to be reimbursed for, including the date, amount, and purpose."

Arquitectura

El servidor MCP A2A consta de varios componentes clave:

  1. Servidor FastMCP: Expone herramientas a los clientes MCP
  2. Cliente A2A: Se comunica con los agentes A2A registrados
  3. Gestor de Tareas: Maneja el reenvío y la gestión de tareas
  4. Obtenedor de Tarjetas de Agente: Recupera información sobre los agentes A2A

Flujo de Comunicación

MCP Client → FastMCP Server → A2A Client → A2A Agent
                   ↑                ↓
                   └──── Response ──┘

Gestión de IDs de Tarea

Al enviar un mensaje a un agente A2A, el servidor:

  1. Genera un task_id único
  2. Mapea este ID a la URL del agente en el diccionario task_agent_mapping
  3. Devuelve el task_id al cliente MCP
  4. Usa este mapeo para enrutar las solicitudes de recuperación y cancelación de tareas

Manejo de Errores

El servidor proporciona mensajes de error detallados para problemas comunes:

  • Agente no registrado
  • ID de tarea no encontrado
  • Errores de conexión con los agentes
  • Errores de análisis en las respuestas

Solución de Problemas

Problemas de Registro de Agentes

Si un agente no puede registrarse:

  • Verifique que la URL del agente sea correcta y accesible
  • Compruebe si el agente tiene una tarjeta de agente adecuada en /.well-known/agent.json

Problemas de Entrega de Mensajes

Si los mensajes no se están entregando:

  • Asegúrese de que el agente esté registrado (use list_agents)
  • Verifique que el agente esté ejecutándose y sea accesible

Problemas de Recuperación de Resultados de Tareas

Si no puede recuperar un resultado de tarea:

  • Asegúrese de estar usando el task_id correcto
  • Compruebe si ha pasado demasiado tiempo (algunos agentes podrían descartar tareas antiguas)

Problemas de Transporte

Si tiene problemas con un tipo de transporte específico:

  • Problemas de stdio: Asegúrese de que los flujos de entrada/salida no estén redirigidos o modificados
  • Problemas de streamable-http: Compruebe si el puerto está disponible y no está bloqueado por un firewall
  • Problemas de sse: Verifique que el cliente soporte Eventos Enviados por el Servidor

Problemas de Configuración de Claude Desktop

Si Claude Desktop no está iniciando su A2A-MCP-Server:

  • Compruebe que las rutas en su claude_desktop_config.json sean correctas
  • Verifique que Python esté en su PATH si usa "command": "python"
  • Para instalación local, asegúrese de que PYTHONPATH sea correcto
  • Asegúrese de que MCP_TRANSPORT esté configurado en "stdio" en la sección env
  • Intente ejecutar el comando manualmente para ver si funciona fuera de Claude
  • Use el script config_creator.py para la detección automática de rutas y configuración

Desarrollo

Agregar Nuevos Métodos de Herramientas

Para agregar nuevas capacidades al servidor, agregue métodos decorados con @mcp.tool() en el archivo a2a_mcp_server.py.

Gestor de Tareas Personalizado

El servidor usa una clase A2AServerTaskManager personalizada que extiende InMemoryTaskManager. Puede personalizar su comportamiento modificando esta clase.

Estructura del Proyecto

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

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0 - consulte el archivo LICENSE para más detalles.

El código en el directorio common/ proviene del proyecto Google A2A y también está licenciado bajo la Licencia Apache, Versión 2.0.

Agradecimientos