Интеграция Hermes Agent с MCP

MCP (Model Context Protocol) — открытый протокол, предложенный Anthropic для стандартизации взаимодействия между LLM и внешними инструментами.

Hermes нативно поддерживает MCP, что позволяет интегрироваться с любым MCP-совместимым сервисом, таким как GitHub, базы данных, файловые системы, браузерные стеки и внутренние API, без изменения основного кода.

В этой главе мы подробно рассмотрим два метода интеграции MCP, стратегии фильтрации инструментов, механизмы изоляции безопасности и типичные способы устранения неполадок.


Что такое MCP

MCP решает практическую проблему: при каждой новой интеграции сервиса традиционный подход требует написания кода адаптера, определения схем инструментов и обработки аутентификации — каждый сервис требует отдельной работы.

MCP стандартизирует всё это. Hermes может напрямую интегрироваться с любым сервисом, реализующим протокол MCP, без дополнительной разработки.

Ключевая роль 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...

Стандартная установка включает поддержку MCP, дополнительные шаги не требуются. Все MCP-серверы в~/.hermes/config.yamlцентрализованной конфигурации в.

MCP — это не проприетарный протокол Hermes, он открытый. Серверы, написанные для других инструментов с поддержкой MCP (например, MCP-серверы Claude Code), можно напрямую использовать в Hermes, и наоборот.


Два типа MCP-серверов

Локальный stdio-сервер

Запускается локально как подпроцесс и взаимодействует с Hermes через стандартный ввод/вывод (stdin/stdout).

Для связи используется протокол JSON-RPC, каждое сообщение отделяется символом новой строки.

Применимые сценарии: инструменты установлены локально, требуется доступ к локальным ресурсам с низкой задержкой (файловые системы, репозитории Git, локальные базы данных).

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Конфигурация сервера MCP stdio
mcp_servers
:
 # Сервер GitHub: запуск через npx
  github
:
    command
: "npx"
    args
: ["-y", "@modelcontextprotocol/server-github"]
    env
:
      GITHUB_PERSONAL_ACCESS_TOKEN
: "ghp_..."

  # Сервер файловой системы: ограничить область доступа агента
  filesystem
:
    command
: "npx"
    args
:
     - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/projects"     # Разрешить доступ только к этому каталогу

  # Сервер Git: запуск через uvx
  git
:
    command
: "uvx"
    args
:
     - "mcp-server-git"
      - "--repository"
      - "/home/user/project"

Жизненным циклом серверов stdio управляет Hermes:

  • Запуск сессии или/reload-mcpКогда Hermes запускает дочерний процесс
  • Когда сессия завершается или сервер отключается, Hermes завершает дочерний процесс.
  • Аварийно завершившийся дочерний процесс автоматически перезапускается (до 3 повторных попыток).

Удалённый HTTP-сервер

Напрямую подключается к удалённым конечным точкам MCP через HTTP-запросы, поддерживая несколько методов аутентификации.

Применимые сценарии: инструменты размещены удалённо или в вашей организации уже есть MCP-интерфейсы.

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Конфигурация MCP HTTP-сервера
mcp_servers
:
 # Способ 1: аутентификация со статическим Bearer Token
  internal_api
:
    url
: "https://mcp.internal.example.com/mcp"
    headers
:
      Authorization
: "Bearer ${MY_TOKEN}"    # Поддержка переменных окружения

  # Метод 2: аутентификация OAuth 2.1(Linear、Sentry、Figma、Stripe и т. д.)
  linear
:
    url
: "https://mcp.linear.app/mcp"
    auth
: oauth

  # Метод 3: Провайдеры, требующие предварительно зарегистрированных клиентов OAuth
  googledrive
:
    url
: "https://drivemcp.googleapis.com/mcp/v1"
    auth
: oauth
    oauth
:
      client_id
: "<your-oauth-client-id>"       # Получение предварительной регистрации
      client_secret
: "<your-oauth-client-secret>"

Сравнение двух типов

Измерениеstdio-серверHTTP-сервер
Место запускаЛокально (дочерний процесс)Удалённо (автономная служба)
Способ коммуникацииstdin/stdout + JSON-RPCHTTP-запрос
Жизненный циклHermes управляет запуском/остановкойНе зависит от Hermes
ЗадержкаЧрезвычайно низкая (внутрипроцессное взаимодействие)Зависит от сетевой задержки
аутентификацияПередача переменных окруженияBearer Token / OAuth 2.1
Типичные сценарииЛокальный Git, файловые системы, базы данныхGitHub API, Linear, Sentry
Сложность конфигурацииНизкая (однострочная команда)Средняя (требуется URL + настройка аутентификации)

Каталог MCP, курируемый Nous

Hermes поставляется с проверенным Nous Research каталогом MCP, обеспечивая установку в один клик.

Просмотреть и установить

Откройте интерактивный селектор (TUI), чтобы просмотреть все записи каталога:

hermes mcp

Другие команды:

# 纯文本列表(适合脚本化)
hermes mcp catalog

# 按名称一键安装
hermes mcp install n8n
hermes mcp install github
hermes mcp install linear

Интерактивный селектор показывает текущий статус каждой записи:

n8n          available              管理和检查 n8n 工作流
linear       enabled                Linear 问题/项目管理(远程 OAuth)
github       installed (disabled)   GitHub 仓库 + PR 工具
filesystem   installed (enabled)    安全的文件系统操作
postgres     available               PostgreSQL 数据库查询
slack        available               Slack 消息和频道管理

Описание статуса:

StateЗначение
доступноМожно установить, ещё не установлено
установлено (включено)Установлено и включено, доступно для использования Агентом.
установлено (отключено)Установлено, но отключено, недоступно для Агента.
включеноУдалённый сервер OAuth, авторизован и включён.

Десктопная версия: просмотрите конфигурацию в меню настроек:

Просмотрите конфигурацию в меню MCP в левой части панели управления:

Что происходит во время установки

Установка в один клик автоматически выполняет три шага:

  1. Руководство по настройке: предлагает ввести ключ API или проводит через процесс авторизации OAuth в браузере.
  2. Обнаружение инструментов: подключается к серверу и получает полный список предоставляемых им инструментов.
  3. Выбор инструментов: отображает список инструментов, чтобы вы отметили инструменты, которые хотите включить (по умолчанию выбраны все).

Третий шаг (выбор инструментов) — важная проверка безопасности: вам не нужны все инструменты. Например, если сервер GitHub предоставляет delete_repo, а он вам не нужен, вы можете снять с него отметку.


Фильтрация инструментов: предоставляйте только то, что вам нужно

Каждый сервер MCP поддерживает тонкую фильтрацию инструментов. Это ключевой механизм безопасности для уменьшения поверхности атаки Агента.

режим include (белый список)

Регистрировать только инструменты из списка; исключить все остальные:

Пример

# Путь к файлу: ~/.hermes/config.yaml
# режим include с белым списком — самый безопасный выбор.
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
      # Любые инструменты, кроме этих 4, не будут зарегистрированы

режим исключения (чёрный список)

Исключить инструменты из списка; зарегистрировать все остальные:

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Режим исключения по чёрному списку — исключить высокорисковые операции
mcp_servers
:
  stripe
:
    url
: "https://mcp.stripe.com"
    headers
:
      Authorization
: "Bearer ${STRIPE_KEY}"
    tools
:
      exclude
:
       - delete_customer
        - refund_payment
        - create_live_key
      # Любой инструмент, кроме этих 3, будет зарегистрирован

Приоритет правил фильтрации

КонфигурацияПоведениеПрименимые сценарии
Только includeРегистрировать только инструменты из списка includeБезопасность прежде всего, принцип наименьших привилегий
Только excludeРегистрировать все инструменты, исключая список excludeУдобство прежде всего, исключить несколько операций повышенного риска
Заданы обаinclude имеет приоритет, exclude игнорируется—
Ни один не заданРегистрировать все инструменты, предоставляемые серверомПолностью доверять этому MCP-серверу

Отключить ресурсы и промпты

Помимо инструментов, MCP-серверы также могут предоставлять ресурсы и промпты. Если они вам не нужны, их можно отключить:

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Ссылка на набор инструментов MCP в конфигурации платформы
platform_toolsets:
  cli:
    - hermes-cli
    - file
    - terminal
- mcp-github # инструмент GitHub MCP
mcp-linear # инструмент Linear MCP

  telegram:
    - hermes-gateway
- mcp-github # Также включить инструменты GitHub в Telegram

  discord:
    - hermes-gateway
# Инструменты GitHub не включены в Discord (политика безопасности)

Изоляция переменных окружения MCP

Это наиболее легко упускаемый из виду, но при этом наиболее важный элемент дизайна в механизмах безопасности MCP Hermes.

Дочерний процесс MCP stdio получаетотфильтрованное окружение. По умолчанию передаются только следующие переменные:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
以及所有 XDG_* 变量

Все остальные переменные окружения (API-ключ, токен, пароль) блокируются.

Только переменные окружения, явно объявленные в конфигурации MCP-сервераenv:В дочерний процесс передаются только переменные, явно объявленные в блоке:

Пример

    env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # Только эта переменная передаётся
# Даже если вы экспортировали GITHUB_TOKEN в оболочке,
# Если он не объявлен здесь, он не будет передан подпроцессу MCP

Почему это сделано именно так? Предположим, у вас есть 10 API-ключей, хранящихся в .env (OpenAI, Anthropic, SerpAPI, Telegram Bot Token...). Если бы MCP-сервер мог читать все переменные окружения, вредоносный инструмент MCP-сервера мог бы украсть все учетные данные. Изоляция переменных окружения гарантирует, что он увидит только явно объявленную переменную.

Сообщения об ошибках автоматически маскируются

Сообщения об ошибках инструмента MCP автоматически санитизируются перед возвратом LLM — конфиденциальная информация (API-ключ, токен, пароль) заменяется на[REDACTED]。

Это не позволяет Агенту случайно увидеть учетные данные в открытом виде при анализе ошибок.


Добавление MCP-сервера вручную

Помимо установки в один клик из каталога Nous, вы также можете вручную добавить любой MCP-совместимый сервер.

Пример

# Добавить stdio-сервер вручную
hermes mcp add my-git-server \
  --command "uvx" \
  --args "mcp-server-git,--repository,/home/user/project"

# Добавить HTTP-сервер вручную
hermes mcp add internal-db \
  --url "https://mcp.internal.example.com/db" \
  --header "Authorization: Bearer ${DB_TOKEN}"

# Проверить, нормально ли соединение
hermes mcp test my-git-server

# Настроить фильтрацию инструментов
hermes mcp configure my-git-server

hermes mcp configureОткрывается интерактивный интерфейс выбора инструментов, позволяющий заново отметить инструменты для включения.


Перезагрузить конфигурацию MCP

После изменения конфигурации MCP в config.yaml нет необходимости перезапускать всего агента:

Пример

# ─── Просмотр и установка ─────────────────────────────────────────────
hermes mcp # интерактивный formulaDirectorySelectors(TUI)
hermes mcp catalog # список каталога в виде простого текста
hermes mcp install <name> # установка в один клик из каталога

# ─── ручное управление ───────────────────────────────────────────────
hermes mcp add <name> --command <cmd> --args <...> # добавить stdio-сервер
hermes mcp add <name> --url <url> # добавить HTTP-сервер
hermes mcp remove <name> # удалить конфигурацию сервера
hermes mcp list # список всех настроенных серверов
hermes mcp test <name> # проверить подключение к серверу
hermes mcp configure <name> # заново выбрать включённые инструменты

# ─── аутентификация OAuth ─────────────────────────────────────────────
hermes mcp login <server> # запустить авторизацию OAuth(максимальное ожидание 5 минут)

# ─── Операции во время выполнения ─────────────────────────────────────────────
/reload-mcp # SessioninsideAgainaddload Конфигурация MCP
hermes mcp reload # Перезагрузить из командной строки

Распространённые проблемы

ПроблемаВозможные причиныРешение
Инструменты MCP не отображаютсяСервер не включён или подключение не удалосьЗапустите hermes mcp list для проверки статуса, hermes mcp test для проверки подключения
Фильтрация инструментов не применяетсяИспользовано имя инструмента, зарегистрированное в HermesИспользуйте исходное имя инструмента MCP (с дефисами, например, list-issues вместо list_issues)
Сервер stdio часто падаетОтсутствуют зависимости или недостаточно правПроверьте, находится ли команда в PATH, запустите тест вручную
Тайм-аут авторизации OAuth30 секунд для /reload-mcp недостаточноСначала hermes mcp login, затем /reload-mcp после завершения
Переменные среды не применяютсяНе объявлено явно в блоке env:Объявите в mcp_servers.<name>.env, не полагайтесь на переменные среды Shell
Соединение с HTTP-сервером отклоненоURL недоступен или аутентификация не удаласьПроверьте URL и заголовок Authorization, чтобы подтвердить сетевое подключение.
Другие расширения