Интеграция 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, локальные базы данных).
Пример
# Конфигурация сервера 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-интерфейсы.
Пример
# Конфигурация 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-RPC | HTTP-запрос |
| Жизненный цикл | 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 в левой части панели управления:

Что происходит во время установки
Установка в один клик автоматически выполняет три шага:
- Руководство по настройке: предлагает ввести ключ API или проводит через процесс авторизации OAuth в браузере.
- Обнаружение инструментов: подключается к серверу и получает полный список предоставляемых им инструментов.
- Выбор инструментов: отображает список инструментов, чтобы вы отметили инструменты, которые хотите включить (по умолчанию выбраны все).
Третий шаг (выбор инструментов) — важная проверка безопасности: вам не нужны все инструменты. Например, если сервер GitHub предоставляет delete_repo, а он вам не нужен, вы можете снять с него отметку.
Фильтрация инструментов: предоставляйте только то, что вам нужно
Каждый сервер MCP поддерживает тонкую фильтрацию инструментов. Это ключевой механизм безопасности для уменьшения поверхности атаки Агента.
режим include (белый список)
Регистрировать только инструменты из списка; исключить все остальные:
Пример
# режим 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, не будут зарегистрированы
режим исключения (чёрный список)
Исключить инструменты из списка; зарегистрировать все остальные:
Пример
# Режим исключения по чёрному списку — исключить высокорисковые операции
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-серверы также могут предоставлять ресурсы и промпты. Если они вам не нужны, их можно отключить:
Пример
# Ссылка на набор инструментов 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:В дочерний процесс передаются только переменные, явно объявленные в блоке:
Пример
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-совместимый сервер.
Пример
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, запустите тест вручную |
| Тайм-аут авторизации OAuth | 30 секунд для /reload-mcp недостаточно | Сначала hermes mcp login, затем /reload-mcp после завершения |
| Переменные среды не применяются | Не объявлено явно в блоке env: | Объявите в mcp_servers.<name>.env, не полагайтесь на переменные среды Shell |
| Соединение с HTTP-сервером отклонено | URL недоступен или аутентификация не удалась | Проверьте URL и заголовок Authorization, чтобы подтвердить сетевое подключение. |