sidebar_position: 4 title: "MCP (Model Context Protocol)" description: "Connect Hermes Agent to external tool servers via MCP — and control exactly which MCP tools Hermes loads" lang: ru

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

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

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

Что дает вам MCP

• Доступ к внешним экосистемам инструментов без предварительного написания собственного инструмента Hermes. — Локальные серверы stdio и удаленные серверы HTTP MCP в одной конфигурации.
• Автоматическое обнаружение и регистрация инструмента при запуске.
• Оболочки утилит для ресурсов MCP и подсказки, если они поддерживаются сервером.
• Фильтрация для каждого сервера, поэтому вы можете предоставлять только те инструменты MCP, которые действительно хотите, чтобы Hermes видел.

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

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 chat

1. Попросите Hermes использовать возможности, поддерживаемые MCP.

Например:

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

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

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

Стдио-серверы

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

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>

Примеры:

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

Утилиты 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

Если 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

Это означает: - 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

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

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.

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

Возможные причины: - сервер не смог подключиться - открытие не удалось - ваша конфигурация фильтра исключила инструменты - на этом сервере не существует возможности утилиты - сервер отключен с помощью 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            # Enable sampling (default: true)
      model: "openai/gpt-4o"  # Override model for sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens per sampling response (default: 4096)
      timeout: 30              # Timeout in seconds per request (default: 30)
      max_rpm: 10              # Rate limit: max requests per minute (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds in sampling loops (default: 5)
      allowed_models: []       # Allowlist of model names the server may request (empty = any)
      log_level: "info"        # Audit log level: debug, info, or warning (default: 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 — составлять список разговоров, читать историю сообщений и отправлять сообщения на все подключенные платформы.

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

• Вы хотите, чтобы Claude Code, Cursor или другой агент кодирования отправлял и читал сообщения 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 информацию о входящих разговорах практически в реальном времени:

# 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              # Normal mode
hermes mcp serve --verbose    # Debug logging on stderr

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

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

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

Текущие лимиты

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

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

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