MCP конфигурация

11.05.2026 · 6 мин чтения · admin

Обзор

Hermes Agent имеет встроенный MCP-клиент (Model Context Protocol), который подключается к внешним MCP-серверам при запуске, обнаруживает их инструменты и регистрирует как инструменты первого класса наряду с встроенными (terminal, read_file и т.д.). Все настройки находятся в секции mcp_servers конфигурационного файла профиля (config.yaml).

Подробное руководство: MCP Feature Guide.

Предварительные требования

mcp (Python-пакет) — опциональная зависимость; если не установлен, поддержка MCP тихо отключается. Установка: pip install mcp
Node.js — нужен для npx-серверов (большинство community-серверов)
uv — нужен для uvx-серверов (Python-серверы)

Корневая структура конфигурации

Конфигурация задаётся в config.yaml:

mcp_servers:
  <server_name>:
    command: "..."      # stdio-транспорт
    args: [...]
    url: "..."          # HTTP-транспорт
    ...

Каждый сервер описывается именем-ключом. Конфигурация должна содержать либо command (stdio), либо url (HTTP), но не оба.

Полная таблица параметров

Параметр	Тип	По умолчанию	Описание
`command`	string	—	Исполняемая команда для запуска локального MCP-сервера (stdio, обязательный)
`args`	list	`[]`	Аргументы команды
`env`	dict	`{}`	Переменные окружения, передаваемые процессу
`url`	string	—	URL удалённого MCP-сервера (HTTP/StreamableHTTP, обязательный)
`headers`	dict	`{}`	HTTP-заголовки (например, `Authorization`)
`timeout`	int	`120`	Таймаут одного вызова инструмента (секунды)
`connect_timeout`	int	`60`	Таймаут начального подключения и обнаружения (секунды)
`enabled`	bool	`true`	Если `false`, сервер полностью отключён
`tools`	object	—	Политика управления инструментами (include/exclude/resources/prompts)
`auth`	string	—	Тип аутентификации. `oauth` включает OAuth 2.1 PKCE flow
`sampling`	object	—	Настройки sampling-потенциала (см. раздел Sampling)

CLI-команды для управления MCP

hermes mcp serve            # Запустить Hermes как MCP-сервер
hermes mcp add NAME         # Добавить MCP-сервер (--url или --command)
hermes mcp remove NAME      # Удалить MCP-сервер
hermes mcp list             # Показать настроенные серверы
hermes mcp test NAME        # Проверить подключение
hermes mcp configure NAME   # Настроить выбор инструментов

Slash-команды

/reload-mcp — перезагрузить MCP-серверы без перезапуска агента. Используйте после изменения конфигурации.

Политика инструментов (`tools`)

Секция tools внутри сервера управляет тем, какие инструменты регистрируются в агенте.

Ключи `tools`

include — белый список. Если указан, регистрируются только перечисленные инструменты.
exclude — чёрный список. Перечисленные инструменты исключаются.
resources — true/false, включает/отключает утилиты ресурсов.
prompts — true/false, включает/отключает утилиты промптов.

Фильтрация

Белый список (include):

tools:
  include: [list_issues, create_issue, search_code]

Чёрный список (exclude):

tools:
  exclude: [delete_customer, refund_payment]

Приоритет: если указаны оба списка, include имеет приоритет над exclude. Например, инструмент create_issue в include и exclude одновременно — будет доступен.

Utility-tool policy

Hermes может регистрировать служебные инструменты-обёртки для каждого MCP-сервера:

Ресурсы: list_resources, read_resource
Промпты: list_prompts, get_prompt

Даже при resources: true или prompts: true утилиты регистрируются только если сервер действительно поддерживает соответствующую возможность.

Именование инструментов

Инструменты именуются по шаблону mcp_<server>_<tool>. Дефисы и точки заменяются на подчёркивания для совместимости с LLM API. В фильтрах include/exclude используйте оригинальное имя MCP-инструмента.

Примеры:

Сервер filesystem, инструмент read_file → mcp_filesystem_read_file
Сервер github, инструмент list-issues → mcp_github_list_issues
Сервер my-api, инструмент fetch.data → mcp_my_api_fetch_data

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

Stdio (command + args)

Hermes запускает MCP-сервер как подпроцесс и общается через stdin/stdout.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 30

HTTP / StreamableHTTP (url)

Для удалённых или общих MCP-серверов. Требует пакет mcp с поддержкой HTTP-клиента.

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."
    timeout: 180
    connect_timeout: 30

Примеры конфигураций

Сервер времени (uvx)

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Регистрирует инструменты типа mcp_time_get_current_time.

Файловая система (npx)

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

Регистрирует mcp_filesystem_read_file, mcp_filesystem_write_file, mcp_filesystem_list_directory.

GitHub с аутентификацией

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

Регистрирует mcp_github_list_issues, mcp_github_create_pull_request и др.

Удалённый HTTP-сервер

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

Несколько серверов одновременно

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

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

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

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

Все инструменты от всех серверов регистрируются и доступны одновременно. Каждый сервер именуется с префиксом для предотвращения коллизий.

Безопасность

Фильтрация переменных окружения

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

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
Любые переменные XDG_*

Все остальные переменные (API-ключи, токены, секреты) исключаются, если вы явно не добавите их через env.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # Только этот токен передаётся в подпроцесс
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

Сокрытие credentials в ошибках

Если вызов MCP-инструмента завершается ошибкой, паттерны credentials автоматически редактируются из сообщения об ошибке перед показом LLM:

GitHub PAT (ghp_...)
OpenAI-ключи (sk-...)
Bearer-токены
Паттерны token=, key=, API_KEY=, password=, secret=

Sampling (запросы LLM от сервера)

Hermes поддерживает capability sampling/createMessage из MCP — серверы могут запрашивать LLM-комплитации через агента во время выполнения инструментов. Это позволяет рабочие процессы «agent-in-the-loop» (анализ данных, генерация контента, принятие решений).

Sampling включён по умолчанию. Настройка для каждого сервера:

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true            # по умолчанию: true
      model: "gemini-3-flash"  # переопределение модели (опционально)
      max_tokens_cap: 4096     # максимум токенов на запрос
      timeout: 30              # таймаут вызова LLM (секунды)
      max_rpm: 10              # максимум запросов в минуту
      allowed_models: []       # белый список моделей (пусто = все)
      max_tool_rounds: 5       # лимит циклов инструментов (0 = отключить)
      log_level: "info"        # подробность аудита

Отключите sampling для непроверенных серверов: sampling: { enabled: false }.

Жизненный цикл подключения

Каждый сервер работает как долгоживущая asyncio Task в фоновом потоке-демоне
Подключения сохраняются на протяжении всего времени жизни процесса агента
При обрыве соединения автоматически запускается переподключение с экспоненциальным backoff (до 5 попыток, макс. 60 сек)
При остановке агента все подключения корректно закрываются
discover_mcp_tools() идемпотентна — повторные вызовы подключаются только к серверам, которые ещё не подключены

Перезагрузка конфигурации

После изменения конфигурации выполните команду /reload-mcp для переподключения серверов без перезапуска агента.

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

«MCP SDK not available» — установите пакет: pip install mcp
«No MCP servers configured» — добавьте секцию mcp_servers в config.yaml
«Failed to connect to MCP server ‘X’» — проверьте, что команда (npx, uvx) установлена и доступна в PATH; увеличьте connect_timeout
«Requires HTTP transport but not available» — обновите пакет: pip install --upgrade mcp
Инструменты не появляются — убедитесь, что сервер находится под mcp_servers (не mcp или servers); проверьте YAML-отступы; ищите имена с префиксом mcp_
Подключение рвётся — клиент повторяет до 5 попыток с backoff. Проверьте процесс сервера и сетевое подключение