Integración de MCP de Hermes Agent
MCP (Model Context Protocol) es un protocolo abierto propuesto por Anthropic para estandarizar la interacción entre LLM y herramientas externas.
Hermes es compatible con MCP de forma nativa, lo que permite conectarse a GitHub, bases de datos, sistemas de archivos, pilas de navegador, API internas y cualquier otro servicio compatible con MCP sin necesidad de modificar el código central.
Este capítulo profundiza en los dos métodos de conexión de MCP, las estrategias de filtrado de herramientas, los mecanismos de aislamiento de seguridad y la solución de problemas comunes.
¿Qué es MCP?
MCP resuelve un problema real: cada vez que se integra un nuevo servicio, el método tradicional requiere escribir código de adaptación, definir esquemas de herramientas y gestionar la autenticación: cada servicio es un trabajo único.
MCP estandariza todo esto. Cualquier servicio que implemente el protocolo MCP puede ser integrado directamente por Hermes sin desarrollo adicional.
Los roles principales de MCP:
Hermes Agent(MCP 客户端)
│
├── stdio ──→ MCP 服务器 A(本地子进程)
│ └── 暴露工具:git_commit, git_push...
│
├── HTTP ───→ MCP 服务器 B(远程服务)
│ └── 暴露工具:list_issues, create_issue...
│
└── HTTP ───→ MCP 服务器 C(远程 OAuth)
└── 暴露工具:search_docs, create_page...
La instalación estándar ya incluye soporte para MCP, sin necesidad de pasos adicionales. Todos los servidores MCP se configuran en~/.hermes/config.yamlde manera unificada.
MCP no es un protocolo propietario de Hermes: es abierto. Los servidores escritos para otras herramientas compatibles con MCP (como los servidores MCP de Claude Code) pueden usarse directamente en Hermes, y viceversa.
Dos tipos de servidores MCP
Servidor stdio local
Se ejecuta localmente como subproceso y se comunica con Hermes mediante entrada/salida estándar (stdin/stdout).
La comunicación utiliza el protocolo JSON-RPC, con cada mensaje separado por un salto de línea.
Casos de uso: herramientas instaladas localmente que necesitan acceso de baja latencia a recursos locales (sistema de archivos, repositorios Git, bases de datos locales).
Ejemplo
# Configuración del servidor MCP stdio
mcp_servers:
# Servidor de GitHub: se inicia mediante npx
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
# Servidor de sistema de archivos: limita el ámbito de acceso del agente
filesystem:
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/home/user/projects" # Solo permite el acceso a este directorio
# Servidor Git: se inicia mediante uvx
git:
command: "uvx"
args:
- "mcp-server-git"
- "--repository"
- "/home/user/project"
El ciclo de vida del servidor stdio es gestionado por Hermes:
- Al iniciar la sesión o
/reload-mcpHermes inicia el subproceso. - Cuando finaliza la sesión o se deshabilita el servidor, Hermes termina el subproceso.
- Si el subproceso se bloquea, se reinicia automáticamente (con un máximo de 3 reintentos).
Servidor HTTP remoto
Se conecta directamente a un endpoint MCP remoto mediante solicitudes HTTP y admite múltiples métodos de autenticación.
Casos de uso: herramientas alojadas de forma remota, o cuando la organización ya dispone de una interfaz MCP.
Ejemplo
# Configuración del servidor MCP HTTP
mcp_servers:
# Opción 1: autenticación con token Bearer estático
internal_api:
url: "https://mcp.internal.example.com/mcp"
headers:
Authorization: "Bearer ${MY_TOKEN}" # Admite variables de entorno
# Opción 2: autenticación OAuth 2.1 (Linear, Sentry, Figma, Stripe, etc.)
linear:
url: "https://mcp.linear.app/mcp"
auth: oauth
# Opción 3: proveedores que requieren pre-registro de clientes OAuth
googledrive:
url: "https://drivemcp.googleapis.com/mcp/v1"
auth: oauth
oauth:
client_id: "<your-oauth-client-id>" # Obtener mediante pre-registro
client_secret: "<your-oauth-client-secret>"
Comparación de los dos tipos
| Dimensión | Servidor stdio | Servidor HTTP |
|---|---|---|
| Ubicación de ejecución | Local (subproceso) | Remoto (servicio independiente) |
| Método de comunicación | stdin/stdout + JSON-RPC | Solicitud HTTP |
| Ciclo de vida | Hermes gestiona el inicio y la detención | Independiente de Hermes |
| Latencia | Muy baja (comunicación dentro del proceso) | Depende de la latencia de la red |
| Autenticación | Transferencia de variables de entorno | Bearer Token / OAuth 2.1 |
| Casos de uso típicos | Git local, sistema de archivos, base de datos | GitHub API、Linear、Sentry |
| Complejidad de configuración | Baja (un comando en una línea) | Media (requiere configurar URL + autenticación) |
Directorio MCP seleccionado por Nous
Hermes incluye un directorio MCP revisado por Nous Research, que ofrece una experiencia de instalación con un solo clic.
Explorar e instalar
Abrir el selector interactivo (TUI) para explorar todas las entradas del directorio:
hermes mcp
Otros comandos:
# 纯文本列表(适合脚本化) hermes mcp catalog # 按名称一键安装 hermes mcp install n8n hermes mcp install github hermes mcp install linear
El selector interactivo muestra el estado actual de cada entrada:
n8n available 管理和检查 n8n 工作流 linear enabled Linear 问题/项目管理(远程 OAuth) github installed (disabled) GitHub 仓库 + PR 工具 filesystem installed (enabled) 安全的文件系统操作 postgres available PostgreSQL 数据库查询 slack available Slack 消息和频道管理
Descripción de estados:
| Estado | Significado |
|---|---|
| available | Instalable, aún no instalado |
| installed (enabled) | Instalado y habilitado, el agente puede usarlo |
| installed (disabled) | Instalado pero deshabilitado, el agente no puede usarlo |
| enabled | Servidor OAuth remoto, autorizado y habilitado |
En la versión de escritorio, ver la configuración en el menú de ajustes:

En el panel, ver la configuración en el menú MCP del lado izquierdo:

Qué ocurre durante el proceso de instalación
La instalación con un solo clic completa automáticamente tres pasos:
- Asistente de configuración: solicita introducir la clave API o guía el flujo de autorización OAuth en el navegador
- Detección de herramientas: se conecta al servidor y obtiene la lista completa de herramientas expuestas
- Selección de herramientas: muestra la lista de herramientas para que marques las que deseas habilitar (seleccionar todo por defecto)
El tercer paso (selección de herramientas) es un componente de seguridad importante: no necesitas todas las herramientas. Por ejemplo, si el servidor de GitHub expone delete_repo y no lo necesitas, puedes desmarcarlo.
Filtrado de herramientas: solo expone lo que necesitas
Cada servidor MCP admite un filtrado detallado de herramientas. Este es un mecanismo de seguridad clave para reducir la superficie de ataque del agente.
Modo include (lista blanca)
Solo registra las herramientas de la lista y excluye todas las demás:
Ejemplo
# Modo include (lista blanca): la opción más segura
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
tools:
include:
- list_issues
- create_issue
- update_issue
- search_code
# Ninguna otra herramienta fuera de estas 4 se registrará
Modo exclude (lista negra)
Excluye las herramientas de la lista y registra todas las demás:
Ejemplo
# Modo exclude (lista negra): excluye operaciones de alto riesgo
mcp_servers:
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ${STRIPE_KEY}"
tools:
exclude:
- delete_customer
- refund_payment
- create_live_key
# Cualquier herramienta fuera de estas 3 se registrará
Prioridad de las reglas de filtrado
| Configuración | Comportamiento | Casos de uso |
|---|---|---|
| Solo include | Solo registra las herramientas de la lista include | Prioridad a la seguridad, principio de mínimo privilegio |
| Solo exclude | Registra todas las herramientas, excluyendo las de la lista exclude | Prioridad a la conveniencia, excluye algunas operaciones de alto riesgo |
| Ambos configurados | include tiene prioridad, exclude se ignora | — |
| Ninguno configurado | Registra todas las herramientas expuestas por el servidor | Confianza total en ese servidor MCP |
Desactivar recursos y prompts
Además de herramientas, los servidores MCP también pueden exponer recursos y prompts. Si no los necesitas, puedes desactivarlos:
Ejemplo
# Hacer referencia al conjunto de herramientas MCP en la configuración de la plataforma
platform_toolsets:
cli:
- hermes-cli
- file
- terminal
- mcp-github # Herramienta MCP de GitHub
- mcp-linear # Herramienta MCP de Linear
telegram:
- hermes-gateway
- mcp-github # Habilitar también la herramienta GitHub en Telegram
discord:
- hermes-gateway
# No habilitar la herramienta GitHub en Discord (política de seguridad)
Aislamiento de variables de entorno de MCP
Este es el diseño más fácil de pasar por alto, pero el más importante, del mecanismo de seguridad MCP de Hermes.
El subproceso MCP stdio recibe unentorno filtrado, por defecto solo se pasan las siguientes variables:
PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR 以及所有 XDG_* 变量
Todas las demás variables de entorno (API Key, Token, contraseñas) están bloqueadas.
Solo las variables declaradas explícitamente en el bloqueenv:de configuración del servidor MCP se pasan al subproceso:
Ejemplo
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # Solo esta variable se pasa
# Aunque exportes GITHUB_TOKEN en el Shell,
# si no está declarado aquí, no se pasará al subproceso MCP
¿Por qué este diseño? Supón que tienes 10 API Keys almacenadas en .env (OpenAI, Anthropic, SerpAPI, Telegram Bot Token...). Si el servidor MCP pudiera leer todas las variables de entorno, una herramienta de servidor MCP maliciosa podría robar todas las credenciales. El aislamiento de variables de entorno garantiza que solo pueda ver la declarada explícitamente.
Redacción automática de información sensible en mensajes de error
Los mensajes de error de las herramientas MCP se desinfectan automáticamente antes de devolverse al LLM: la información sensible (API Key, Token, contraseñas) se reemplaza por[REDACTED]。
Esto evita que el Agente vea accidentalmente credenciales en texto plano al analizar errores.
Añadir manualmente un servidor MCP
Además de la instalación con un clic desde el catálogo de Nous, también puedes añadir manualmente cualquier servidor compatible con MCP.
Ejemplo
hermes mcp add my-git-server \
--command "uvx" \
--args "mcp-server-git,--repository,/home/user/project"
# Añadir servidor HTTP manualmente
hermes mcp add internal-db \
--url "https://mcp.internal.example.com/db" \
--header "Authorization: Bearer ${DB_TOKEN}"
# Probar si la conexión funciona correctamente
hermes mcp test my-git-server
# Configurar el filtrado de herramientas
hermes mcp configure my-git-server
hermes mcp configureSe abrirá una interfaz interactiva de selección de herramientas para que vuelvas a marcar las herramientas que deseas habilitar.
Recargar la configuración de MCP
Después de modificar la configuración de MCP en config.yaml, no es necesario reiniciar todo el Agente:
Ejemplo
hermes mcp # Selector de catálogo interactivo (TUI)
hermes mcp catalog # Lista de catálogo en texto plano
hermes mcp install <name> # Instalación con un clic desde el catálogo
# ─── Gestión manual ───────────────────────────────────────────────
hermes mcp add <name> --command <cmd> --args <...> # Añadir servidor stdio
hermes mcp add <name> --url <url> # Añadir servidor HTTP
hermes mcp remove <name> # Eliminar la configuración del servidor
hermes mcp list # Listar todos los servidores configurados
hermes mcp test <name> # Probar la conexión del servidor
hermes mcp configure <name> # Volver a seleccionar las herramientas habilitadas
# ─── Autenticación OAuth ─────────────────────────────────────────────
hermes mcp login <server> # Iniciar autorización OAuth (esperar máximo 5 minutos)
# ─── Operaciones en tiempo de ejecución ─────────────────────────────────────────────
/reload-mcp # Recargar la configuración de MCP dentro de la sesión
hermes mcp reload # Recargar desde la línea de comandos
Solución de problemas comunes
| Problema | Posible causa | Solución |
|---|---|---|
| Las herramientas MCP no aparecen | Servidor no habilitado o fallo de conexión | Ejecuta hermes mcp list para comprobar el estado, hermes mcp test para probar la conexión |
| El filtrado de herramientas no funciona | Se usó el nombre de herramienta registrado por Hermes | Usa el nombre original de la herramienta MCP (con guiones, como list-issues en lugar de list_issues) |
| El servidor stdio se bloquea con frecuencia | Faltan dependencias o permisos insuficientes | Comprueba si el comando está en el PATH y ejecuta la prueba manualmente |
| Tiempo de espera de autorización OAuth agotado | Los 30 segundos de /reload-mcp no son suficientes | Primero ejecuta hermes mcp login y, una vez completado, /reload-mcp |
| Las variables de entorno no funcionan | No se declararon explícitamente en el bloque env: | Declara en mcp_servers.<name>.env, no dependas de las variables de entorno del Shell |
| Conexión al servidor HTTP rechazada | URL inaccesible o fallo de autenticación | Comprueba la URL y el header Authorization, confirma la conectividad de red |