Hermes agent

MCP в Hermes

Этот гайд о том, как реально использовать MCP в Hermes Agent в повседневной работе.

Если справочная страница объясняет, что такое MCP, то здесь — как получить от него пользу быстро и безопасно.

Когда стоит использовать MCP?

Используйте MCP, когда:

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

Не используйте MCP, когда:

  • встроенный инструмент Hermes уже хорошо решает задачу
  • сервер открывает огромную опасную поверхность инструментов, а вы не готовы её фильтровать
  • нужна только одна узкая интеграция, и нативный инструмент был бы проще и безопаснее

Ментальная модель

Представьте MCP как адаптерный слой:

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

Последнее важно. Правильное использование MCP — это не «подключи всё подряд», а «подключи нужное с минимально необходимой поверхностью».

Шаг 1: установите поддержку MCP

Если вы установили Hermes через стандартный установочный скрипт, поддержка MCP уже включена (установщик запускает uv pip install -e ".[all]").

Если устанавливали без расширений и нужно добавить MCP отдельно:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

Для серверов на базе npm убедитесь, что Node.js и npx доступны.

Для многих Python MCP-серверов удобно использовать uvx.

Шаг 2: начните с одного сервера

Начните с одного безопасного сервера.

Пример: доступ к файловой системе только одного проектного каталога.

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

Запустите Hermes:

hermes chat

Спросите что-нибудь конкретное:

Inspect this project and summarize the repo layout.

Шаг 3: убедитесь, что MCP загрузился

Проверить загрузку MCP можно несколькими способами:

  • в баннере/статусе Hermes при настроенном MCP будет соответствующая отметка
  • спросите Hermes, какие инструменты у него есть
  • после изменений конфига используйте /reload-mcp
  • проверьте логи, если сервер не подключился

Практичный тестовый промпт:

Tell me which MCP-backed tools are available right now.

Шаг 4: сразу начните фильтровать

Не откладывайте фильтрацию, если сервер открывает много инструментов.

Пример: белый список только нужного

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

Обычно это лучший вариант по умолчанию для чувствительных систем.

WSL2: мост из Hermes в WSL к Chrome на Windows

Этот вариант актуален, когда:

  • Hermes работает внутри WSL2
  • браузер, которым вы хотите управлять, — это ваш обычный Chrome с сессиями на Windows
  • /browser connect из WSL работает ненадёжно или не работает совсем

В этой схеме Hermes не подключается к Chrome напрямую. Вместо этого:

  • Hermes работает в WSL
  • Hermes запускает локальный MCP-сервер через stdio
  • этот MCP-сервер запускается через Windows interop (cmd.exe или powershell.exe)
  • MCP-сервер подключается к вашей живой сессии Chrome на Windows

Ментальная модель:

Hermes (WSL) -> MCP stdio bridge -> Windows Chrome

Почему этот режим полезен

  • вы сохраняете настоящий профиль браузера Windows, куки и авторизации
  • Hermes остаётся в поддерживаемой Unix-среде (WSL2)
  • управление браузером открывается как MCP-инструменты, а не через транспорт браузера в ядре Hermes

Рекомендуемый сервер

Используйте chrome-devtools-mcp.

Если Chrome на Windows уже запущен с удалённой отладкой через chrome://inspect/#remote-debugging, добавьте его так из WSL:

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

После сохранения сервера:

hermes mcp test chrome-devtools-win

Затем начните новую сессию Hermes или выполните:

/reload-mcp

Типичный промпт

После загрузки Hermes может напрямую использовать MCP-инструменты для браузера. Например:

调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。

Когда /browser connect — не тот инструмент

Если Hermes работает в WSL, а Chrome — на Windows, /browser connect может не работать, даже если Chrome открыт и доступен для отладки.

Типичные причины:

  • WSL не может достучаться до того же host-local эндпоинта, который Chrome открывает для Windows-инструментов
  • новые режимы живой отладки Chrome отличаются от классической схемы ws://localhost:9222
  • к браузеру проще подключиться с Windows-стороны через chrome-devtools-mcp

В таких случаях оставьте /browser connect для сценариев в одной среде, а для мостов WSL→Windows используйте MCP.

Известные подводные камни

  • Запускайте Hermes из пути на Windows-разделе, например /mnt/c/Users/<you> или /mnt/c/workspace/..., при использовании Windows stdio-исполняемых файлов через MCP.
  • Если запустить Hermes из /root или /home/..., Windows может выдать предупреждение о UNC текущем каталоге перед стартом MCP-сервера.
  • Если chrome-devtools-mcp --autoConnect зависает при перечислении страниц — уменьшите количество фоновых/замороженных вкладок в Chrome и попробуйте снова.

Пример: чёрный список опасных действий

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Пример: отключение вспомогательных обёрток

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

На что реально влияет фильтрация?

В Hermes есть две категории MCP-функциональности:

  1. Нативные MCP-инструменты сервера
  • фильтруются через:
    • tools.include
    • tools.exclude
  1. Вспомогательные обёртки, добавляемые Hermes
  • фильтруются через:
    • tools.resources
    • tools.prompts

Вспомогательные обёртки, которые вы можете встретить

Ресурсы:

  • list_resources
  • read_resource

Промпты:

  • list_prompts
  • get_prompt

Эти обёртки появляются только если:

  • ваш конфиг их разрешает, и
  • MCP-сессия сервера действительно поддерживает эти возможности

Hermes не будет притворяться, что у сервера есть ресурсы/промпты, если их нет.

Типовые паттерны

Паттерн 1: локальный ассистент для проекта

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

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

Хорошие промпты:

Review the project structure and identify where configuration lives.
Check the local git state and summarize what changed recently.

Паттерн 2: ассистент для триажа GitHub

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

Хорошие промпты:

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

Паттерн 3: ассистент для внутреннего API

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

Хорошие промпты:

Look up customer ACME Corp and summarize recent invoice activity.

Именно здесь строгий белый список работает значительно лучше, чем список исключений.

Паттерн 4: документация / серверы знаний

Некоторые MCP-серверы открывают промпты или ресурсы, которые больше похожи на общие активы знаний, чем на прямые действия.

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

Хорошие промпты:

List available MCP resources from the docs server, then read the onboarding guide and summarize it.
List prompts exposed by the docs server and tell me which ones would help with incident response.

Туториал: настройка с фильтрацией от начала до конца

Вот практичная последовательность шагов.

Фаза 1: добавьте GitHub MCP с жёстким белым списком

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

Запустите Hermes и спросите:

Search the codebase for references to MCP and summarize the main integration points.

Фаза 2: расширяйте только по необходимости

Если позже понадобится обновление задач:

tools:
  include: [list_issues, create_issue, update_issue, search_code]

Затем перезагрузите:

/reload-mcp

Фаза 3: добавьте второй сервер с другой политикой

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

Теперь Hermes может комбинировать их:

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

Вот где MCP становится по-настоящему ценным: мультисистемные рабочие процессы без изменений в ядре Hermes.

Рекомендации по безопасному использованию

Предпочитайте белые списки для опасных систем

Для финансовых, клиентских или деструктивных систем:

  • используйте tools.include
  • начинайте с минимально возможного набора

Отключайте неиспользуемые утилиты

Если не хотите, чтобы модель просматривала ресурсы/промпты, предоставляемые сервером, отключите их:

tools:
  resources: false
  prompts: false

Держите серверы в узких рамках

Примеры:

  • файловый сервер, привязанный к одному каталогу проекта, а не ко всему домашнему каталогу
  • git-сервер, указывающий на один репозиторий
  • сервер внутреннего API с преимущественно read-only инструментами по умолчанию

Перезагружайте после изменений конфига

/reload-mcp

Делайте это после изменения:

  • списков include/exclude
  • флагов enabled
  • переключателей resources/prompts
  • заголовков авторизации / переменных окружения

Диагностика по симптомам

«Сервер подключился, но ожидаемые инструменты отсутствуют»

Возможные причины:

  • отфильтрованы через tools.include
  • исключены через tools.exclude
  • вспомогательные обёртки отключены через resources: false или prompts: false
  • сервер на самом деле не поддерживает ресурсы/промпты

«Сервер настроен, но ничего не загружается»

Проверьте:

  • в конфиге не осталось enabled: false
  • команда/рантайм существует (npx, uvx и т.д.)
  • HTTP-эндпоинт доступен
  • переменные окружения или заголовки авторизации корректны

«Почему вижу меньше инструментов, чем анонсирует MCP-сервер?»

Потому что Hermes соблюдает вашу политику на уровне сервера и регистрирует инструменты с учётом их возможностей. Это ожидаемо и обычно желательно.

«Как убрать MCP-сервер, не удаляя конфиг?»

Используйте:

enabled: false

Конфиг останется, но подключение и регистрация будут заблокированы.

Рекомендуемые первые MCP-серверы

Хорошие первые серверы для большинства:

  • filesystem
  • git
  • GitHub
  • fetch / документационные MCP-серверы
  • один узкий внутренний API

Не очень подходят для начала:

  • огромные бизнес-системы с множеством деструктивных действий без фильтрации
  • всё, в чём вы недостаточно разбираетесь, чтобы ограничить

Связанная документация

⌕ ESC