Hermes Agent MCP: config, tool search y arreglos de producción

MCP (Model Context Protocol) es el estándar abierto con el que un agente descubre y llama herramientas externas, como Slack o GitHub, sin que cada integración se escriba a mano. Que un MCP server se conecte no es lo mismo que un agente usándolo. Aprendí eso de la forma cara: 157 herramientas conectadas, cero llamadas, y un modelo que juraba que las herramientas no existían. Las herramientas existían. La configuración estaba bien. Lo que faltaba era timing, y ningún quickstart te avisa de eso.

Esta es la configuración, la UI actual, y los arreglos de producción para correr MCP servers contra Hermes Agent, revisado contra v0.21.5, commit 9c6fe3aa.

Los MCP servers en Hermes Agent arrancan en un solo bloque

Cada MCP server con el que habla Hermes vive bajo mcp_servers en ~/.hermes/config.yaml, una entrada por server, y la forma de la entrada depende de si el server habla stdio o HTTP.

mcp_servers:
  project_fs:
    command: "npx"
    args:
      ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
    tools:
      include: [read_file, list_directory]

  github:
    url: "https://api.githubcopilot.com/mcp/"
    headers:
      Authorization: "Bearer ${env:GITHUB_TOKEN}"
    tools:
      exclude: [delete_repo]

Un server stdio recibe command, args y env. Un server HTTP recibe url y headers en su lugar, más las claves de TLS (ssl_verify, client_cert, client_key) cuando el endpoint necesita mTLS. Las dos formas comparten enabled, timeout, connect_timeout, trust y una política tools con globs de include/exclude más los toggles resources/prompts para los wrappers de utilidad que Hermes agrega encima. ${VAR} y el estilo Cursor ${env:VAR} resuelven los dos desde el .env del perfil activo, así que un snippet copiado de una config de Cursor o Claude Code funciona sin cambios.

Dos claves importan más de lo que el quickstart deja ver. lazy: true registra las herramientas de un server desde el caché de schema en disco al arrancar y solo lo levanta o conecta en la primera llamada real, que es el default correcto para un server que usas poco. idle_timeout_seconds y max_lifetime_seconds reciclan un server stdio cuando se queda idle o envejece, lo cual importa para cualquier server que pierde memoria de forma lenta.

No tienes que editar el YAML a mano para el caso común. hermes mcp add te escribe la entrada, y hermes mcp test <server> se conecta y lista lo que descubre:

Agregar y verificar un server

Server stdio local

$ hermes mcp add github --command npx --args -y @modelcontextprotocol/server-github

Verificar que se conecta
```
$ hermes mcp test github
```

Dentro de una sesión corriendo, /reload-mcp toma un cambio de config sin reiniciar. Ese slash command es el arreglo de un bug que me costó un reinicio en junio: un MCP server agregado después de que el gateway ya había arrancado se conectaba, pero su toolset nunca se registraba para activación hasta que el gateway se reiniciaba. /reload-mcp es el remedio documentado hoy. Si corres una versión de Hermes de antes de que existiera ese slash command, presupuesta un reinicio cada vez que tocas mcp_servers.

El centro de comando de MCP reemplazó la vieja pestaña de MCP

Hermes Desktop tenía antes una pestaña de MCP. Desde v0.21.5 tiene una página de Connectors en su lugar, y el cambio es más que cosmético. El release incorporó un catálogo de servers curados y aprobados por Nous, health checks por conexión, y prompts de “Connect now” que se disparan en el momento en que instalas un plugin que trae sus propios MCP servers, así que las herramientas y skills de un plugin recién instalado se activan en cada chat que ya tienes abierto, no solo en los nuevos. La misma ventana de release agregó mcp.discovery_concurrency para limitar cuántos servers prueba Hermes a la vez durante el discovery de arranque, el tipo de perilla que solo necesitas cuando ya tienes suficientes servers como para que el discovery mismo se vuelva un cuello de botella.

El tool search difiere cada herramienta de MCP, el presupuesto es la única variable

En el momento en que existe cualquier herramienta de MCP o de plugin en una sesión, Hermes la mueve detrás de una herramienta de búsqueda en vez de listarla en el system prompt. Esto no depende de cuántas herramientas tengas. tool_search.py se activa en cuanto existe cualquier herramienta diferible, punto. No hay ningún umbral en el código de “menos del 10 por ciento del contexto, lista todo”.

Lo que la config en verdad controla es el tamaño del listado compacto que Hermes sigue incrustando para las herramientas diferidas: threshold_pct, 5.0 por default, con un tope de listing_max_tokens, 4.000 tokens por default. El presupuesto es min(listing_max_tokens, threshold_pct% de la context window), y un largo de contexto desconocido cae en un piso fijo de 10.000 tokens, que es el 5 por ciento de una ventana típica de 200K. Sube threshold_pct y consigues un listado incrustado más rico a costa de espacio de prompt en cada turno. Bájalo y el modelo depende más de la herramienta de búsqueda misma.

Este es el mecanismo que hace que acotar a mano las herramientas de un agente sea una ganancia mucho más chica de lo que parece. Mi flota tenía 114 herramientas de MCP detrás de la búsqueda en junio. El costo en tokens de “demasiadas herramientas” ya estaba mitigado por el diferimiento; lo único que compraba el hard-scope era riesgo. Más sobre eso abajo.

hermes mcp serve: Hermes como fuente para otros agentes

La config de arriba es Hermes como cliente de MCP, trayendo herramientas hacia adentro. Hermes también puede correr como server. hermes mcp serve levanta un MCP server de stdio que expone tus conversaciones de mensajería como herramientas: listar conversaciones, leer historial, enviar mensajes, sondear eventos en vivo, manejar aprobaciones. Apunta Claude Code, Cursor o Codex hacia él:

{
  "mcpServers": {
    "hermes": { "command": "hermes", "args": ["mcp", "serve"] }
  }
}

El docstring del módulo mismo dice que empareja la superficie del channel bridge de 9 herramientas de OpenClaw, lo cual te dice de dónde vino la presión de diseño: en cuanto un runtime self-hosted expone sus canales a un coding agent por MCP, el otro tiene que hacerlo también.

Hermes Agent MCP en producción: los arreglos que importan

Todo lo de arriba es la documentación. Todo lo de abajo es lo que la documentación no te avisa, aprendido corriendo una flota de agentes de Paperclip sobre Hermes desde junio.

Lo que MCP en producción en verdad me enseñó

Junio157 herramientas, cero llamadas
Cada agente tenía todo su toolset conectado a través de un gateway agregador delante de 7 MCP servers de backend. No llamaron a ninguna y reportaron que las herramientas no existían. La causa real vivía en agent.log: el gateway arrancaba en frío sus 7 backends por sesión, de 4,5 a 27 segundos, más allá de la ventana de discovery de menos de un segundo de Hermes. Un backend caliente responde tools/list en unos 10 milisegundos. Los agentes nunca esperaron tanto.
JunioPlano de control y plano de datos son trabajos distintos
El arreglo no fue abandonar el gateway agregador, se gana el puesto como catálogo administrativo. El arreglo fue dejar de rutear el tráfico en caliente a través de él. mcp-pooler mantiene una sola sesión caliente y persistente hacia el gateway, cachea tools/list, y hace proxy de tools/call, así que cada sesión de agente de vida corta ve el discovery en unos 50 milisegundos en vez de decenas de segundos. En config.yaml eso significa una sola entrada HTTP apuntando al pooler, no una entrada por backend.
Juniohermes mcp test prueba menos de lo que parece
El comando se conecta y lista herramientas, lo cual es un chequeo estático: prueba spawn más tools/list, nada sobre auth o alcanzabilidad bajo carga. La prueba real necesitó un tools/call más un sondeo directo de la API. La documentación de hoy describe los mismos tres exit codes, 0 conectado, 1 falló, 3 sin configurar, que siguen significando lo mismo, limitado.
JunioEl flag de hard-scope reemplaza, no acota
Acotar un agente con el flag de toolset de Hermes reemplazaba todo el toolset base en vez de agregarle, lo cual le sacaba la terminal y los skills al agente y lo dejaba zombi, sin manos. Combinado con que el tool search ya pagaba el costo en tokens de un toolset grande, el hard-scope dejó de valer el riesgo. Me pasé a soft scope: doctrina en un TOOLS.md más una cerca de proyecto, y aguantó. Un agente con el pool completo simplemente nunca tocaba el namespace del que le dijeron que se mantuviera lejos.
JunioValida al consumidor antes de construir la fuente
Me pasé una tarde construyendo cuatro namespaces de MCP con hard-scope antes de chequear cómo el flag de toolset en verdad los consumía. Todo el trabajo de la tarde se borró una hora después de pasar sus propios tests, porque había probado lo equivocado, correctamente.
En cursoEl agente es un narrador poco confiable
Cada falla de MCP que depuré creyéndole al relato del agente me costó tiempo. agent.log tuvo razón todas las veces que la historia del agente estaba mal. Cuando una llamada a herramienta falla, lee el log antes de leer el transcript del chat.

Las lecciones de junio son anteriores a v0.21. Léelas como historia, no como la lista de bugs de hoy.

La carrera de cold-spawn y el error de scoping están escritos en detalle en el Lab: 157 herramientas y cero llamadas y valida el consumo antes de construir la fuente. Los MCP de datos detrás de esa flota eran Ubersuggest, GA4 y Search Console, catalogados en el gateway agregador y alcanzados a través del pooler. Nada de eso era exótico. Cada falla se rastreó hasta una carrera, la semántica real de un flag, o un error de secuencia, nunca hasta el modelo.

Palabras que te consiguen prueba, no una narración

01
Haz que el agente llame a la herramienta, no solo que la nombre.
El tool search y hermes mcp test se quedan los dos en el listado. Una herramienta que aparece en un resultado de búsqueda no está probada para devolver nada.
Escribe esto
```
Llama a esa herramienta una vez con un argumento real ahora mismo y pega el resultado crudo. No me digas que está disponible, muéstrame que devuelve datos.
```
02
Cuando diga que una herramienta no existe, pide la línea del log, no la excusa.
El agente narra una falla. agent.log la registra. Los dos están en desacuerdo más seguido de lo que pensarías.
En lugar de
¿Por qué no funcionó esa herramienta?
Escribe esto
```
Abre agent.log y cita la línea exacta de la última llamada de MCP que falló. No la resumas, cítala.
```
03
Antes de confiar en un hard scope, pregunta qué sacó en realidad.
El flag de toolset de Hermes reemplaza el toolset base en vez de acotarlo. Un agente que perdió su terminal muchas veces no te lo va a contar solo.
Escribe esto
```
Lista cada herramienta a la que tienes acceso ahora mismo, y dime qué tenías antes de que yo agregara el flag -t.
```

Tres frases que convierten un reporte confiado del agente en algo que en verdad puedes chequear.

Antes de conectar un nuevo MCP server a Hermes

Obligatorio:
Decide stdio o HTTP primero, las claves no se mezclan.command/args/env para un proceso local, url/headers para un endpoint remoto. Una forma por server.
Obligatorio:
Usa tools.include antes de usar un flag de scoping.El tool search ya paga la mayor parte del costo en tokens de un toolset grande. Un agente amplio cercado por doctrina es más seguro que uno con hard-scope que perdió su propia terminal.
Obligatorio:
Trata hermes mcp test como una smoke test, no un health check.Prueba que el server arranca y lista herramientas. Prueba un tools/call real por separado antes de confiar en la conexión.
Obligatorio:
Si un server está detrás de un gateway agregador, pon un pooler caliente delante.Las sesiones de agente efímeras no sobreviven un cold spawn de 4 a 27 segundos. Un tools/list cacheado y una sola sesión caliente upstream sí.
Obligatorio:
Cuando un agente diga que una herramienta no existe, abre agent.log antes de creerle.El agente narra. El log es la verdad del terreno.

Todo esto vino de una flota de producción, no de una demo.

Hermes Agent MCP, respuestas rápidas

¿Cómo agrego un MCP server a Hermes Agent?

Agrega una entrada bajo mcp_servers en ~/.hermes/config.yaml, o corre hermes mcp add <name> --command ... --args ... para un server stdio (usa --url para HTTP en vez de un command). Verifica con hermes mcp test <name>, y recarga una sesión corriendo con /reload-mcp en vez de reiniciar.

¿Qué es el centro de comando de MCP en Hermes Agent?

Desde v0.21.5, la vieja pestaña de MCP de Hermes Desktop es la página Connectors: un catálogo de servers curados, health checks por conexión, y un flujo de 'Connect now' que activa las herramientas de MCP de un plugin recién instalado en cada chat que ya tienes abierto.

¿El tool search de Hermes Agent solo se activa sobre un umbral de tokens?

No. El tool search se activa en el momento en que existe cualquier herramienta de MCP o de plugin en la sesión, sin importar cuántas sean. Lo único configurable es el tamaño del listado incrustado para las herramientas diferidas, 5 por ciento de la context window por default, con un tope de 4.000 tokens.

¿Claude Code puede usar Hermes Agent como MCP server?

Sí. hermes mcp serve expone tus conversaciones de mensajería, listar, leer historial, enviar, sondear eventos, manejar aprobaciones, como herramientas de MCP que cualquier cliente puede llamar, Claude Code, Cursor o Codex incluidos.

¿Por qué mi agente de Hermes dice que sus herramientas de MCP no existen?

Usualmente es una carrera de discovery, no una herramienta faltante. Si el server está detrás de un gateway agregador que arranca en frío sus backends por sesión, el discovery puede tardar segundos mientras la ventana propia de Hermes es de menos de un segundo. Lee agent.log antes de confiar en la explicación del agente, y pon un pooler caliente delante del gateway si los arranques en frío son la causa.

La newsletter

Don’t Code, Specify. Cada semana, agentes de IA en producción de verdad. Sin hype: lo que funcionó y lo que se rompió.

Suscríbete en Substack