🏠 Главная › Документация › Интеграции

MCP (Model Context Protocol)

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

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

Что даёт MCP

Быстрый старт

  1. Установите поддержку MCP (уже включена, если вы использовали стандартный скрипт установки):
cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
  1. Добавьте MCP-сервер в ~/.hermes/config.yaml:
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
  1. Запустите Hermes:
hermes chat
  1. Попросите Hermes использовать функциональность, предоставляемую MCP.

Например:

List the files in /home/user/projects and summarize the repo structure.

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

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

Stdio-серверы

Stdio-серверы запускаются как локальные подпроцессы и общаются через stdin/stdout.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

Используйте stdio-серверы, когда:

HTTP-серверы

HTTP MCP-серверы — это удалённые конечные точки, к которым Hermes подключается напрямую.

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

Используйте HTTP-серверы, когда:

Справочник базовой конфигурации

Hermes читает конфигурацию MCP из ~/.hermes/config.yaml в разделе mcp_servers.

Общие ключи

Ключ Тип Значение
command string Исполняемый файл для stdio MCP-сервера
args list Аргументы для stdio-сервера
env mapping Переменные окружения, передаваемые stdio-серверу
url string HTTP MCP-эндпоинт
headers mapping HTTP-заголовки для удалённых серверов
timeout number Таймаут вызова инструмента
connect_timeout number Таймаут первоначального подключения
enabled bool Если false, Hermes полностью пропускает этот сервер
tools mapping Фильтрация инструментов и политика утилит для конкретного сервера

Минимальный пример stdio

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Минимальный пример HTTP

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Как Hermes регистрирует MCP-инструменты

Hermes добавляет префикс к MCP-инструментам, чтобы они не конфликтовали со встроенными именами:

mcp_<server_name>_<tool_name>

Примеры:

Сервер MCP-инструмент Зарегистрированное имя
filesystem read_file mcp_filesystem_read_file
github create-issue mcp_github_create_issue
my-api query.data mcp_my_api_query_data

На практике вам обычно не нужно вызывать имя с префиксом вручную — Hermes видит инструмент и выбирает его во время обычного процесса рассуждения.

Утилиты MCP

Если поддерживается, Hermes также регистрирует утилиты для работы с ресурсами и промптами MCP:

Они регистрируются для каждого сервера с тем же шаблоном префикса, например:

Важно

Теперь эти утилиты учитывают возможности:

Таким образом, сервер, предоставляющий вызываемые инструменты, но без ресурсов/промптов, не получит этих дополнительных обёрток.

Фильтрация по серверам

Вы можете управлять тем, какие инструменты каждый MCP-сервер предоставляет Hermes, что позволяет точно настраивать пространство имён инструментов.

Полное отключение сервера

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Если enabled: false, Hermes полностью пропускает сервер и даже не пытается установить соединение.

Белый список инструментов сервера

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

Регистрируются только указанные MCP-инструменты сервера.

Чёрный список инструментов сервера

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

Регистрируются все инструменты сервера, кроме исключённых.

Правило приоритета

Если указаны оба:

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include имеет приоритет.

Фильтрация утилит

Вы также можете отдельно отключать обёртки утилит, добавленные Hermes:

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

Это означает:

Полный пример

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

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Что если всё отфильтровано?

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

Это сохраняет список инструментов чистым.

Поведение во время выполнения

Время обнаружения

Hermes обнаруживает MCP-серверы при запуске и регистрирует их инструменты в стандартном реестре инструментов.

Динамическое обнаружение инструментов

MCP-серверы могут уведомлять Hermes об изменении доступных инструментов во время выполнения, отправляя уведомление notifications/tools/list_changed. Когда Hermes получает такое уведомление, он автоматически повторно запрашивает список инструментов сервера и обновляет реестр — без необходимости вручную выполнять /reload-mcp.

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

Обновление защищено блокировкой, поэтому быстрые уведомления от одного и того же сервера не вызывают перекрывающихся обновлений. Уведомления об изменении промптов и ресурсов (prompts/list_changed, resources/list_changed) принимаются, но пока не обрабатываются.

Перезагрузка

Если вы изменили конфигурацию MCP, используйте:

/reload-mcp

Это перезагружает MCP-серверы из конфигурации и обновляет доступный список инструментов. Об изменениях инструментов во время выполнения, отправляемых самим сервером, см. раздел Динамическое обнаружение инструментов выше.

Наборы инструментов

Каждый настроенный MCP-сервер также создаёт набор инструментов во время выполнения, если он предоставляет хотя бы один зарегистрированный инструмент:

mcp-<server>

Это упрощает работу с MCP-серверами на уровне наборов инструментов.

Модель безопасности

Фильтрация окружения Stdio

Для stdio-серверов Hermes не передаёт вслепую всё ваше shell-окружение.

Передаются только явно настроенные env плюс безопасный базовый набор. Это снижает риск случайной утечки секретов.

Контроль доступности на уровне конфигурации

Новая поддержка фильтрации также является средством контроля безопасности:

Примеры использования

GitHub-сервер с минимальным управлением задачами

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

Пример использования:

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

Stripe-сервер без опасных действий

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

Пример использования:

Look up the last 10 failed payments and summarize common failure reasons.

Файловый сервер для корня проекта

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

Пример использования:

Inspect the project root and explain the directory layout.

Устранение неполадок

MCP-сервер не подключается

Проверьте:

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

Затем проверьте конфигурацию и перезапустите Hermes.

Инструменты не отображаются

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

Если вы намеренно фильтруете, это ожидаемое поведение.

Почему не появились утилиты ресурсов или промптов?

Потому что теперь Hermes регистрирует эти обёртки только при выполнении обоих условий:

  1. ваша конфигурация разрешает их

  2. серверная сессия действительно поддерживает эту возможность

Это сделано намеренно и сохраняет список инструментов честным.

Поддержка семплирования MCP

MCP-серверы могут запрашивать LLM-инференс у Hermes через протокол sampling/createMessage. Это позволяет MCP-серверу попросить Hermes сгенерировать текст от его имени — полезно для серверов, которым нужны возможности LLM, но у которых нет собственного доступа к модели.

Семплирование включено по умолчанию для всех MCP-серверов (если MCP SDK поддерживает это). Настраивается для каждого сервера в разделе sampling:

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Включить семплирование (по умолчанию: true)
      model: "openai/gpt-4o"  # Переопределить модель для запросов семплирования (опционально)
      max_tokens_cap: 4096     # Максимум токенов на один ответ семплирования (по умолчанию: 4096)
      timeout: 30              # Таймаут в секундах на запрос (по умолчанию: 30)
      max_rpm: 10              # Лимит запросов в минуту (по умолчанию: 10)
      max_tool_rounds: 5       # Максимум раундов использования инструментов в циклах семплирования (по умолчанию: 5)
      allowed_models: []       # Белый список имён моделей, которые сервер может запрашивать (пусто = любые)
      log_level: "info"        # Уровень аудита: debug, info или warning (по умолчанию: info)

Обработчик семплирования включает скользящий ограничитель скорости, таймауты для каждого запроса и лимиты глубины циклов инструментов для предотвращения неконтролируемого использования. Метрики (количество запросов, ошибки, использованные токены) отслеживаются для каждого экземпляра сервера.

Чтобы отключить семплирование для конкретного сервера:

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

Запуск Hermes в роли MCP-сервера

Помимо подключения к MCP-серверам, Hermes также может быть MCP-сервером. Это позволяет другим MCP-совместимым агентам (Claude Code, Cursor, Codex или любому MCP-клиенту) использовать возможности обмена сообщениями Hermes — просматривать беседы, читать историю сообщений и отправлять сообщения на все ваши подключённые платформы.

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

Быстрый старт

hermes mcp serve

Это запускает stdio MCP-сервер. MCP-клиент (не вы) управляет жизненным циклом процесса.

Конфигурация MCP-клиента

Добавьте Hermes в конфигурацию вашего MCP-клиента. Например, в ~/.claude/claude_desktop_config.json от Claude Code:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Или если вы установили Hermes в определённое место:

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Доступные инструменты

MCP-сервер предоставляет 10 инструментов, соответствующих поверхности канального моста OpenClaw плюс обозреватель каналов, специфичный для Hermes:

Инструмент Описание
conversations_list Список активных бесед. Фильтрация по платформе или поиск по имени.
conversation_get Получение подробной информации об одной беседе по ключу сессии.
messages_read Чтение последней истории сообщений для беседы.
attachments_fetch Извлечение нетекстовых вложений (изображения, медиа) из конкретного сообщения.
events_poll Опрос новых событий беседы с указанной позиции курсора.
events_wait Долгий опрос / ожидание следующего события (почти в реальном времени).
messages_send Отправка сообщения через платформу (например, telegram:123456, discord:#general).
channels_list Список доступных целей для отправки сообщений на всех платформах.
permissions_list_open Список ожидающих запросов на одобрение, замеченных во время сессии моста.
permissions_respond Разрешить или отклонить ожидающий запрос на одобрение.

Система событий

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

# Poll for new events (non-blocking)
events_poll(after_cursor=0)

# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)

Типы событий: message, approval_requested, approval_resolved

Очередь событий находится в памяти и запускается при подключении моста. Более старые сообщения доступны через messages_read.

Опции

hermes mcp serve              # Обычный режим
hermes mcp serve --verbose    # Отладочное логирование в stderr

Как это работает

MCP-сервер читает данные бесед напрямую из хранилища сессий Hermes (~/.hermes/sessions/sessions.json и базы данных SQLite). Фоновый поток опрашивает базу данных на предмет новых сообщений и поддерживает очередь событий в памяти. Для отправки сообщений используется та же инфраструктура send_message, что и у самого агента Hermes.

Шлюзу НЕ требуется быть запущенным для операций чтения (список бесед, чтение истории, опрос событий). Он ДОЛЖЕН быть запущен для операций отправки, поскольку адаптерам платформ требуются активные подключения.

Текущие ограничения