Hermes Agent no carga sus herramientas MCP: cómo arreglarlo

Añadiste un servidor MCP a ~/.hermes/config.yaml, reiniciaste el gateway y le pediste a Hermes que listara sus herramientas. No hay nada nuevo. Ni un error, ni un aviso, y gateway.log está en silencio. Este post es el camino más corto desde ese silencio hasta ver un mcp_<servidor>_<herramienta> funcionando en tu sesión.

Cinco modos de fallo explican casi todos los casos reportados, y cada uno se esconde en un sitio distinto. La buena noticia: hermes mcp list, hermes mcp test y una sola bandera de log te dirán en menos de dos minutos cuál de los cinco te ha tocado.

Por qué los fallos silenciosos existen

La configuración de MCP es la superficie con menos logging útil de todo Hermes. Cuando el loader no puede arrancar un servidor, no puede importar el extra Python de mcp o no puede parsear el bloque mcp_servers, el fallo se registra a nivel DEBUG y nunca llega a gateway.log en una instalación por defecto. Desde tu lado parece que la config se aceptó y que las herramientas simplemente no existen.

La solución es subir la visibilidad antes de tocar nada más. Reinicia Hermes con logging verboso para que el loader te diga por qué se rindió:

hermes serve --verbose
# o, si arrancas por docker compose:
HERMES_LOG_LEVEL=DEBUG docker compose up

Ahora vuelve a ejecutar hermes mcp list. Si tu servidor aparece en la lista pero sin herramientas colgando, la conexión funcionó pero falló el discovery. Si el servidor no aparece, el loader no llegó a registrarlo. Esa bifurcación te dice cuál de los arreglos de abajo te toca.

Causa 1: falta el extra Python mcp

Si compilaste Hermes desde el fuente o fijaste una tag concreta, el paquete mcp es un extra opcional y no se instala con el install por defecto. Sin él, cada entrada dentro de mcp_servers se ignora en silencio. Es la causa número uno en instalaciones a medida.

Reinstala con el extra activado:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
hermes serve --verbose

Si tu gateway arranca ahora e intenta contactar al servidor, te faltaba el SDK. Si el log sigue diciendo mcp module not available, el extra no llegó al intérprete que realmente ejecuta Hermes: revisa hermes --version para saber la ruta del venv y vuelve a lanzar el install dentro.

Causa 2: tu indentación YAML se ha desviado un espacio

YAML descarta en silencio cualquier bloque cuya indentación no cuadra con su padre. Un tab suelto, un - a la profundidad equivocada o dos puntos sin comillas dentro de una cadena de comando hacen desaparecer todo el mapa mcp_servers sin una línea de aviso.

La forma segura es indentación de dos espacios, comillas alrededor de cualquier cosa con dos puntos y listas con -:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
  stripe:
    url: "https://mcp.stripe.com/v1/sse"
    enabled: true

Dos comprobaciones rápidas: lanza python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" para confirmar que el fichero parsea, y después hermes mcp list para confirmar que los nombres aparecen. Si parsea pero el bloque está vacío desde el punto de vista de Hermes, la indentación es incorrecta aunque el YAML sea legal.

Causa 3: falta node o npx en el host

La mayoría de servidores MCP de la comunidad se distribuyen como paquetes npm y se lanzan con npx -y @modelcontextprotocol/server-<name>. Si el host no tiene Node.js en PATH, el subproceso muere antes de imprimir nada y Hermes lo apunta solo a nivel DEBUG. Es la causa más frecuente dentro de contenedores Docker minimalistas.

Prueba el lanzamiento fuera de Hermes primero:

node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp

Si alguna de las tres falla, instala Node.js en el mismo entorno donde corre Hermes. En Docker eso significa añadir nodejs y npm a tu imagen o partir de una base que ya los traiga. No hay forma de que Hermes lance un binario Node que no existe.

Causa 4: el servidor conecta pero sus herramientas no salen a la sesión

Ves el servidor en hermes mcp list, hermes mcp test <servidor> descubre sus herramientas y aun así no hay nada nuevo callable dentro de la sesión. Es el fallo documentado en el issue #51587 y el issue #71736: el discovery funcionó, pero las herramientas nunca se inyectaron al toolset de la sesión.

Los workarounds fiables son:

• Ejecuta /reload-mcp dentro de tu sesión de Hermes, o reinicia el gateway entero. Algunas builds pueblan el toolset una única vez al arranque y se saltan los servidores que suben tarde.
• Revisa el campo enabled_toolsets de la sesión. Si está muy limitado (por ejemplo la sesión ACP hardcodea ["hermes-acp"]), las herramientas MCP se excluyen por diseño y hay que abrir el toolset.
• Confirma que tu provider soporta uso de herramientas de verdad. Los modelos Ollama tienen que arrancar con una plantilla compatible con Hermes, y los modelos locales viejos reportan las herramientas descubiertas pero nunca las invocan.

Causa 5: tu provider descarta las tool calls en silencio

Incluso con el servidor arriba y las herramientas registradas, algunos providers eliminan el payload de tool antes de que llegue al modelo. El síntoma es el mismo que un MCP roto: la herramienta existe pero no pasa nada cuando la pides.

Comprobación de dos minutos: cambia la sesión a un provider con tool calling probado (cualquier modelo reciente de Anthropic, OpenAI o Groq) y haz la misma pregunta. Si ahí sí dispara, el problema es tu provider o tu elección de modelo, no MCP. Si sigue sin disparar, vuelve a la Causa 4.

El camino de diagnóstico, en orden

Ejecuta esto en este orden y para cuando algo cambie lo que ves:

1. hermes serve --verbose - ahora los fallos salen por stdout.
2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - confirma que el fichero al menos parsea.
3. hermes mcp list - muestra lo que el loader aceptó.
4. hermes mcp test <servidor> - muestra si conexión y discovery funcionan.
5. hermes mcp health - un snapshot de estado por servidor cuando toca pasarle algo a otra persona.
6. /reload-mcp dentro de tu sesión, o un reinicio completo del gateway.
7. Cambia de provider dos minutos para hacer un A/B.

Para un recorrido completo por la superficie de diagnóstico, la guía de debugging y observabilidad de Hermes cubre gateway.log, el tracing por herramienta y cómo hacerle tail a todo sin morir. Si aún estás montando tu primer servidor MCP, la guía de setup de MCP recorre la forma del fichero de config antes de que ninguno de los fallos de arriba llegue a existir.

Sáltate la superficie de golpe

Cada fallo de este post viene de un desajuste entre Hermes y su host: un extra Python que no está, un binario Node que no está, un permiso mal puesto sobre el fichero de config, un bug de orden de arranque de la sesión. Hermify ejecuta toda esa superficie por ti.

Empieza con Hermify para correr un Hermes Agent gestionado en Telegram con MCP ya cableado, el extra mcp instalado, npx disponible en el host y el reload al cambiar la config funcionando de fábrica. Mantienes tu config de MCP, mantienes tu memoria y dejas de diagnosticar indentación de YAML un martes por la noche.

Fuentes

• La mala configuración MCP es invisible - issue #31246
• Las herramientas MCP conectan pero no aparecen en la sesión - issue #51587
• Disponibilidad inconsistente de herramientas MCP con Ollama - issue #71736
• Documentación MCP de Hermes Agent
• Guía de debugging del Model Context Protocol