Saltar al contenido principal

MCPs y HINs

Esta guía te ayudará a entender los conceptos de MCPs y HINs, y como se integran en la plataforma Hubeet.

¿Qué son los MCPs?​

Los MCP Servers (Model Context Protocol) son módulos especializados que proveen herramientas de IA para los Copilotos de Hubeet. Estos servidores permiten que el copiloto interactúe con fuentes de datos y APIs reales, como bases de datos (MySQL, Postgres), servicios web, y sistemas empresariales.

Hubeet desarrolla los MCPs para su propio uso, pero pueden ser desarrollados por cualquiera, ya que son completamente personalizables y extensibles. Son los que proveen las herramientas para el Copiloto de IA.

¿Qué es un HIN?​

Un Hubeet Integration Node (HIN) es un cliente de integración remota que permite conectar servidores MCP con la plataforma Hubeet. Es el componente que hace posible que las herramientas (servidores MCP) se comuniquen con cualquier Copiloto de Hubeet en entornos que no son publicos y muchas veces no son accesibles desde internet, de manera privada y segura.

Esto permite que cualquier componente ya existente en tu empresa se pueda conectar a Hubeet y que el Copiloto de IA pueda interactuar con él de manera privada y segura, sin importar su tecnología o sistema operativo.

Este es un componente clave para la seguridad y privacidad, ya que permite que las herramientas se comuniquen Hubeet sin exponer ningun dato sensible a internet a la vez que te permite potenciar con inteligencia artificial cualquier componente ya existente en tu empresa.

Advertencia

Las herramientas detrás de un HIN (como los MCP Servers) no estarán disponibles para los Agentes o Copilotos a menos que dichos servidores MCP estén efectivamente en ejecución. Asegúrate de que los servidores estén activos para garantizar el acceso y funcionamiento correcto desde Hubeet.

Hubeet brinda notificaciones de alerta cuando los servidores MCP no están en ejecución. Ver FAQ para más información.

Arquitectura clásica propuesta por Hubeet para la integración de MCPs en entornos privados​

Componentes de la Arquitectura​

  • Hubeet Platform: Plataforma en la nube que gestiona los Copilotos y coordina las solicitudes
  • HIN (Host): Nodo de integración que corre directamente en el Host, actuando como puente seguro entre Hubeet y los MCPs
  • Docker Container: Contenedor que agrupa los servidores MCP en un entorno aislado
  • MCP Servers: Servidores individuales que proveen herramientas específicas (bases de datos, APIs, sistemas internos)

Flujo de Comunicación​

  1. El Copiloto en Hubeet envía una solicitud que requiere herramientas MCP
  2. Hubeet reenvía la solicitud al HIN a través de una conexión segura
  3. El HIN (corriendo en el Host) actúa como canal y comunica con los MCP Servers dentro del Docker Container
  4. Los MCP Servers ejecutan la acción solicitada (consultas a BD, llamadas a APIs, etc.)
  5. La respuesta viaja de vuelta por el mismo canal: MCP Servers → HIN → Hubeet → Copiloto

Ventajas de esta Arquitectura​

  • Seguridad: Los datos sensibles nunca salen del entorno privado
  • Aislamiento: Los MCPs corren en contenedores Docker, aislados del sistema host
  • Escalabilidad: Fácil agregar o remover MCP Servers sin afectar el HIN
  • Privacidad: El HIN maneja toda la comunicación, manteniendo los sistemas internos privados

Requerimientos del HIN​

El HIN es un binario que se ejecuta en el host y se encarga de la comunicación entre Hubeet y los servidores MCP Dockerizados. A continuación se detallan los requerimientos del HIN:

  • Sistema Operativo: Linux recomendado, Windows y macOS soportados
  • RAM: 1GB o superior
  • Disco: 1GB o superior
  • CPU: 1 core o superior
  • Conexión a internet: Requerida para la descarga de actualizaciones y descarga de imágenes de los servidores MCP

Requerimientos de los Servidores MCP Dockerizados​

Los servidores MCP desarrollados por Hubeet serán Dockerizados, y los mismos requieren tener una versión de Docker Engine instalada en el host que va a ejecutar el contenedor. A continuación se detallan los requerimientos de la versión de Docker Engine:

  • Versión: 20.10.0 o superior
  • Sistema Operativo: Linux recomendado, Windows y macOS soportados
  • RAM: 8GB o superior
  • Disco: 20GB o superior
  • CPU: 2 core o superior
  • Conexión a internet: Requerida para la descarga de actualizaciones y descarga de imágenes de los servidores MCP

Instalación del HIN​

Descargar el binario​

Los binarios están disponibles en el CDN de Hubeet. Descarga la versión correspondiente a tu sistema operativo desde:

https://cdn.hubeet.com/hin/builds/

Las versiones disponibles se organizan por carpetas (por ejemplo: v1.0.24/). Dentro de cada versión encontrarás:

  • macOS: hubeet-integration-node-macos.bin
  • Linux: hubeet-integration-node-linux.bin
  • Windows: hubeet-integration-node-win.exe

Permisos de ejecución (macOS/Linux)​

Después de descargar el binario, otorga permisos de ejecución:

chmod +x hubeet-integration-node-macos.bin
# o
chmod +x hubeet-integration-node-linux.bin

Uso Básico​

Iniciar el nodo​

Ejecuta el binario correspondiente a tu sistema:

# macOS/Linux
./hubeet-integration-node-macos.bin
./hubeet-integration-node-linux.bin

# Windows
hubeet-integration-node-win.exe

En el primer inicio, se ejecutará un asistente interactivo para configurar:

  • Token de Hubeet: Tu token de autenticación para conectar con la plataforma
  • Nombre del nodo: Un identificador único para tu nodo de integración

Detener el nodo​

Para detener el nodo desde otra terminal:

./hubeet-integration-node-macos.bin stop

Ejecutar en segundo plano​

Mientras el nodo está ejecutándose:

  1. Presiona d (y Enter si es necesario)
  2. Escribe bg y presiona Enter para continuar en segundo plano

Alternativa (macOS/Linux): Usa kill -SIGUSR1 <PID> para enviar al background.

Ver el nodo en ejecución desde Hubeet​

Para ver el nodo en ejecución desde Hubeet, puedes visitar el siguiente link: https://support.hubeet.com/admin/settings/abilities/integrationNode/nodes

Advertencia

Debés estar logueado en la plataforma y tener permisos de administrador para ver el nodo en ejecución.

Comandos Disponibles​

Ver configuración​

./hubeet-integration-node-macos.bin config --show

Reiniciar configuración​

./hubeet-integration-node-macos.bin config --reset

Esto eliminará la configuración actual y ejecutará nuevamente el asistente de configuración.

Usar configuración personalizada​

./hubeet-integration-node-macos.bin config=/ruta/a/config

Archivos y Directorios​

El HIN almacena sus archivos en el directorio ~/.hubeet-integration-node/:

  • Configuración: ~/.hubeet-integration-node/config.json
  • MCPs: ~/.hubeet-integration-node/mcps.json - Configuración de los servidores MCP
  • Logs: ~/.hubeet-integration-node/logs/hubeet-integration-node.log
  • PID: ~/.hubeet-integration-node/hubeet-integration-node.pid - ID del proceso en ejecución

Actualizaciones​

El nodo verifica automáticamente si hay nuevas versiones disponibles al iniciar. Si hay una actualización disponible, se mostrará la URL de descarga con la versión más reciente.

Puedes verificar las versiones disponibles visitando: https://cdn.hubeet.com/hin/builds/

Solución de Problemas​

El nodo ya está ejecutándose​

Si ves el error "already running", detén la instancia anterior:

./hubeet-integration-node-macos.bin stop

Ver logs​

Los logs se guardan automáticamente en:

~/.hubeet-integration-node/logs/hubeet-integration-node.log

Puedes ver los logs en tiempo real con:

tail -f ~/.hubeet-integration-node/logs/hubeet-integration-node.log

Problemas de conexión​

Si el nodo no se conecta a la plataforma Hubeet:

  1. Verifica que tu token sea válido usando config --show
  2. Revisa los logs para ver mensajes de error específicos
  3. Asegúrate de tener conexión a internet
  4. Verifica que no haya un firewall bloqueando la conexión

Notas Importantes​

  • Una instancia por configuración: Solo puede ejecutarse una instancia por directorio de configuración
  • Reconexión automática: El nodo se reconecta automáticamente si se pierde la conexión con la plataforma
  • Detención segura: Presiona Ctrl+C para detener el nodo de forma segura
  • MCPs personalizados: Puedes configurar múltiples servidores MCP en el archivo mcps.json

Configuración de MCPs​

Para agregar servidores MCP a tu nodo, edita el archivo ~/.hubeet-integration-node/mcps.json. Cada servidor MCP debe tener una configuración que incluya:

  • Nombre del servidor
  • Tipo de servidor
  • Parámetros de conexión
  • Herramientas disponibles

Consulta la documentación específica de cada servidor MCP para conocer los parámetros requeridos.

Próximos Pasos​