MCP (Протокол контекста модели)

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

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

Что даёт MCP

• Доступ к внешним экосистемным инструментам без необходимости сначала писать нативный инструмент Hermes.
• Локальные stdio-серверы и удаленные HTTP MCP-серверы в одной конфигурации.
• Автоматическое обнаружение и инструменты регистрации при запуске.
• Утилитарные обёртки для ресурсов и приглашений MCP, когда они обращаются на сервер.
• Фильтрация для каждого сервера, чтобы вы могли показать Hermes только те 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.

Например:

Перечисли файлы в /home/user/projects и обобщи структуру репозитория.

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

Два вида MCP-серверов

Stdio-серверы

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

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

Используйте stdio-серверы, когда: - установлен локально сервер - Вам нужна поддержка доступа к локальным ресурсам - вы следуете документацию MCP-сервера, где показаны command, args и env

HTTP-серверы

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

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

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

Справочник по формулировке

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

Общие ключи

Минимальный пример 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>

Примеры:

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

Утилитарные инструменты MCP

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

• list_resources
• read_resource
• list_prompts
• get_prompt

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

• mcp_github_list_resources
• mcp_github_get_prompt

Важно

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

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

Фильтрация для каждого сервера

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

Полностью отключенный сервер

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

Если включено: 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

Это означает: - tools.resources: false отключает list_resources и read_resource - tools.prompts: false отключает list_prompts и get_prompt

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

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 не передаёт слепо всё ваше окружение.

Передаются только явно настроенные 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

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

Покажи открытые issues с меткой bug, затем создай новый issue для нестабильного поведения MCP-переподключения.

Stripe-сервер с удаленными опасными действиями

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

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

Найди последние 10 неудачных платежей и обобщи распространённые причины сбоев.

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

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

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

Проверь корень проекта и объясни структуру каталогов.

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

MCP-сервер не хранится

проверить:

# Убедитесь, что зависимости MCP установлены (уже включены в стандартную установку)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

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

Инструменты не строительные

Возможные причины: - сервер не смог подключиться - Обнаружение не удалось - ваши настройки фильтра отдельных инструментов - альтернативная возможность не существует в этом регионе - сервер отключен с помощью enabled: false

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

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

Потому что 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 — просматривать разговоры, читать историю сообщений и отправлять сообщения на все ваши подключенные платформы.

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

• Вы хотите, чтобы Клод Код, Курсор или другой кодирующий агент отправлял и читал сообщения Telegram/Discord/Slack через Hermes.
• Вам нужен один MCP-сервер, который одновременно подключается со всеми подключенными платформами обмена сообщениями Hermes.
• У вас уже есть работающий шлюз Hermes с подключенными платформами

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

hermes mcp serve

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

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

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

{
  "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:

События системы

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

# Опрос новых событий (неблокирующий)
events_poll(after_cursor=0)

# Ожидание следующего события (блокируется до таймаута)
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.

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

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

• Только stdio-транспорт (пока нет HTTP MCP-транспорта)
• Опрос событий с интервалом ~200 мс через последовательный опрос mtime БД (пропускает работу, когда файлы не сохраняются)
• Пока нет протокола push-уведомлений claude/channel
• Только текстовая отправка (нет отправки медиа/вложений через messages_send)

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

• Использование MCP с Hermes
• Команды CLI
• Слэш-команды
• Часто задаваемые вопросы