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

# Ruta del archivo: ~/.hermes/config.yaml
# 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

# Ruta del archivo: ~/.hermes/config.yaml
# 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ónServidor stdioServidor HTTP
Ubicación de ejecuciónLocal (subproceso)Remoto (servicio independiente)
Método de comunicaciónstdin/stdout + JSON-RPCSolicitud HTTP
Ciclo de vidaHermes gestiona el inicio y la detenciónIndependiente de Hermes
LatenciaMuy baja (comunicación dentro del proceso)Depende de la latencia de la red
AutenticaciónTransferencia de variables de entornoBearer Token / OAuth 2.1
Casos de uso típicosGit local, sistema de archivos, base de datosGitHub API、Linear、Sentry
Complejidad de configuraciónBaja (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:

EstadoSignificado
availableInstalable, aún no instalado
installed (enabled)Instalado y habilitado, el agente puede usarlo
installed (disabled)Instalado pero deshabilitado, el agente no puede usarlo
enabledServidor 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:

  1. Asistente de configuración: solicita introducir la clave API o guía el flujo de autorización OAuth en el navegador
  2. Detección de herramientas: se conecta al servidor y obtiene la lista completa de herramientas expuestas
  3. 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

# Ruta del archivo: ~/.hermes/config.yaml
# 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

# Ruta del archivo: ~/.hermes/config.yaml
# 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ónComportamientoCasos de uso
Solo includeSolo registra las herramientas de la lista includePrioridad a la seguridad, principio de mínimo privilegio
Solo excludeRegistra todas las herramientas, excluyendo las de la lista excludePrioridad a la conveniencia, excluye algunas operaciones de alto riesgo
Ambos configuradosinclude tiene prioridad, exclude se ignora—
Ninguno configuradoRegistra todas las herramientas expuestas por el servidorConfianza 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

# Ruta del archivo: ~/.hermes/config.yaml
# 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

    env:
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

# Añadir servidor stdio manualmente
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

# ─── Explorar e instalar ─────────────────────────────────────────────
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

ProblemaPosible causaSolución
Las herramientas MCP no aparecenServidor no habilitado o fallo de conexiónEjecuta hermes mcp list para comprobar el estado, hermes mcp test para probar la conexión
El filtrado de herramientas no funcionaSe usó el nombre de herramienta registrado por HermesUsa el nombre original de la herramienta MCP (con guiones, como list-issues en lugar de list_issues)
El servidor stdio se bloquea con frecuenciaFaltan dependencias o permisos insuficientesComprueba si el comando está en el PATH y ejecuta la prueba manualmente
Tiempo de espera de autorización OAuth agotadoLos 30 segundos de /reload-mcp no son suficientesPrimero ejecuta hermes mcp login y, una vez completado, /reload-mcp
Las variables de entorno no funcionanNo 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 rechazadaURL inaccesible o fallo de autenticaciónComprueba la URL y el header Authorization, confirma la conectividad de red
Otras extensiones