На этой странице

Клиент MCP: подключение серверов, регистрация инструментов (stdio/HTTP).

Метаданные навыка¶


Источник	Встроенный (устанавливается по умолчанию)
Путь	`skills/mcp/native-mcp`
Версия	`1.0.0`
Автор	Hermes Agent
Лицензия	MIT
Теги	`MCP`, `Инструменты`, `Интеграции`
Связанные навыки	`mcporter`

Справочник: полный SKILL.md¶

info

Ниже приведено полное определение навыка, которое Hermes загружает при его активации. Это то, что агент видит в качестве инструкций, когда навык активен.

Встроенный MCP-клиент¶

Hermes Agent имеет встроенный MCP-клиент, который подключается к MCP-серверам при запуске, обнаруживает их инструменты и делает их доступными как инструменты первого класса, которые агент может вызывать напрямую. Никакой мостовой CLI не требуется — инструменты с MCP-серверов появляются рядом со встроенными инструментами, такими как terminal, read_file и т.д.

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

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

Подключиться к MCP-серверам и использовать их инструменты из Hermes Agent
Добавить внешние возможности (доступ к файловой системе, GitHub, базы данных, API) через MCP
Запускать локальные MCP-серверы на stdio (npx, uvx или любая команда)
Подключаться к удалённым HTTP/StreamableHTTP MCP-серверам
Чтобы MCP-инструменты автоматически обнаруживались и были доступны в каждом разговоре

Для разовых вызовов MCP-инструментов из терминала без настройки используйте навык mcporter.

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

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

Установите MCP SDK:

[code] pip install mcp # or, if using uv: uv pip install mcp

[/code]

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

Добавьте MCP-серверы в ~/.hermes/config.yaml под ключом mcp_servers:

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

[/code]

Перезапустите Hermes Agent. При запуске он:

Подключится к серверу
Обнаружит доступные инструменты
Зарегистрирует их с префиксом mcp_time_*
Внедрит их во все наборы инструментов платформ

Затем вы можете использовать инструменты естественным образом — просто попросите агента показать текущее время.

Справочник по конфигурации¶

Каждая запись в mcp_servers — это имя сервера, сопоставленное с его конфигурацией. Есть два типа транспорта: stdio (на основе команды) и HTTP (на основе URL).

Транспорт Stdio (команда + аргументы)¶

[code] mcp_servers: server_name: command: "npx" # (обязательно) исполняемый файл для запуска args: ["-y", "pkg-name"] # (опционально) аргументы команды, по умолчанию: [] env: # (опционально) переменные окружения для подпроцесса SOME_API_KEY: "value" timeout: 120 # (опционально) таймаут вызова инструмента в секундах, по умолчанию: 120 connect_timeout: 60 # (опционально) таймаут начального подключения в секундах, по умолчанию: 60

[/code]

Транспорт HTTP (URL)¶

[code] mcp_servers: server_name: url: "https://my-server.example.com/mcp" # (обязательно) URL сервера headers: # (опционально) HTTP-заголовки Authorization: "Bearer sk-..." timeout: 180 # (опционально) таймаут вызова инструмента в секундах, по умолчанию: 120 connect_timeout: 60 # (опционально) таймаут начального подключения в секундах, по умолчанию: 60

[/code]

Все опции конфигурации¶

Опция	Тип	По умолчанию	Описание
`command`	string	—	Исполняемый файл для запуска (транспорт stdio, обязательно)
`args`	list	`[]`	Аргументы, передаваемые команде
`env`	dict	`{}`	Дополнительные переменные окружения для подпроцесса
`url`	string	—	URL сервера (транспорт HTTP, обязательно)
`headers`	dict	`{}`	HTTP-заголовки, отправляемые с каждым запросом
`timeout`	int	`120`	Таймаут вызова инструмента в секундах
`connect_timeout`	int	`60`	Таймаут начального подключения и обнаружения

Примечание: Конфигурация сервера должна содержать либо command (stdio), либо url (HTTP), но не оба одновременно.

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

Обнаружение при запуске¶

Когда Hermes Agent запускается, discover_mcp_tools() вызывается во время инициализации инструментов:

Считывает mcp_servers из ~/.hermes/config.yaml
Для каждого сервера запускает подключение в выделенном фоновом цикле событий
Инициализирует MCP-сессию и вызывает list_tools() для обнаружения доступных инструментов
Регистрирует каждый инструмент в реестре инструментов Hermes

Соглашение об именовании инструментов¶

MCP-инструменты регистрируются по шаблону именования:

[code] mcp_{server_name}_{tool_name}

[/code]

Дефисы и точки в именах заменяются на подчёркивания для совместимости с API LLM.

Примеры:

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

Автоматическое внедрение¶

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

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

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

Идемпотентность¶

discover_mcp_tools() идемпотентен — повторные вызовы подключаются только к серверам, которые ещё не подключены. Серверы, с которыми произошла ошибка, повторно запрашиваются при последующих вызовах.

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

Транспорт Stdio¶

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

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

[/code]

Подпроцесс наследует фильтрованное окружение (см. раздел Безопасность ниже) плюс любые переменные, которые вы укажете в env.

Транспорт HTTP / StreamableHTTP¶

Для удалённых или общих MCP-серверов. Требует, чтобы пакет mcp включал поддержку HTTP-клиента (mcp.client.streamable_http).

[code] mcp_servers: remote_api: url: "https://mcp.example.com/mcp" headers: Authorization: "Bearer sk-..."

[/code]

Если поддержка HTTP недоступна в вашей установленной версии mcp, сервер завершится с ImportError, а остальные серверы продолжат работу в обычном режиме.

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

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

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

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

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

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

[/code]

Очистка учётных данных в сообщениях об ошибках¶

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

GitHub PAT (ghp_...)
Ключи в стиле OpenAI (sk-...)
Bearer-токены
Общие шаблоны token=, key=, API_KEY=, password=, secret=

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

«MCP SDK не установлен — пропускаем обнаружение MCP-инструментов»¶

Пакет mcp для Python не установлен. Установите его:

[code] pip install mcp

[/code]

«MCP-серверы не настроены»¶

Ключ mcp_servers отсутствует в ~/.hermes/config.yaml или пуст. Добавьте хотя бы один сервер.

«Не удалось подключиться к MCP-серверу "X"»¶

Распространённые причины:

Команда не найдена: Исполняемый файл command отсутствует в PATH. Убедитесь, что npx, uvx или соответствующая команда установлены.
Пакет не найден: Для npx-серверов npm-пакет может не существовать или может потребоваться -y в аргументах для автоустановки.
Таймаут: Серверу потребовалось слишком много времени для запуска. Увеличьте connect_timeout.
Конфликт портов: Для HTTP-серверов URL может быть недоступен.

«MCP-серверу "X" требуется HTTP-транспорт, но mcp.client.streamable_http недоступен»¶

Ваша версия пакета mcp не включает поддержку HTTP-клиента. Обновите:

[code] pip install --upgrade mcp

[/code]

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

Проверьте, что сервер указан в разделе mcp_servers (не mcp или servers)
Убедитесь, что отступы в YAML правильные
Посмотрите логи запуска Hermes Agent на предмет сообщений о подключении
Имена инструментов имеют префикс mcp_{server}_{tool} — ищите этот шаблон

Подключение постоянно разрывается¶

Клиент повторяет попытку до 5 раз с экспоненциальной задержкой (1с, 2с, 4с, 8с, 16с, максимум 60с). Если сервер принципиально недоступен, он прекращает попытки после 5 попыток. Проверьте процесс сервера и сетевое подключение.

Примеры¶

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

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

[/code]

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

Сервер файловой системы (npx)¶

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

[/code]

Регистрирует инструменты, такие как mcp_filesystem_read_file, mcp_filesystem_write_file, mcp_filesystem_list_directory.

Сервер GitHub с аутентификацией¶

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

[/code]

Регистрирует инструменты, такие как mcp_github_list_issues, mcp_github_create_pull_request и т.д.

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

[code] 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

[/code]

Несколько серверов¶

[code] 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

[/code]

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

Сэмплинг (запросы LLM, инициированные сервером)¶

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

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

[code] 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" # уровень детализации аудита

[/code]

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

Отключите сэмплинг для ненадёжных серверов с помощью sampling: { enabled: false }.

Примечания¶

MCP-инструменты вызываются синхронно с точки зрения агента, но выполняются асинхронно в выделенном фоновом цикле событий
Результаты инструментов возвращаются в формате JSON с либо {"result": "..."}, либо {"error": "..."}
Встроенный MCP-клиент независим от mcporter — вы можете использовать оба одновременно
Подключения к серверам постоянны и разделяются между всеми разговорами в одном процессе агента
Добавление или удаление серверов требует перезапуска агента (горячей перезагрузки пока нет)
Метаданные навыка
Справочник: полный SKILL.md
Когда использовать
Предварительные требования
Быстрый старт
Справочник по конфигурации
Как это работает
Типы транспорта
- Транспорт Stdio
- Транспорт HTTP / StreamableHTTP
Безопасность
- Фильтрация переменных окружения
- Очистка учётных данных в сообщениях об ошибках
Устранение неполадок
Примеры
Сэмплинг (запросы LLM, инициированные сервером)
Примечания

Метаданные навыка​¶

Справочник: полный SKILL.md​¶

Встроенный MCP-клиент¶

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

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

Быстрый старт​¶

Справочник по конфигурации​¶

Транспорт Stdio (команда + аргументы)​¶

Транспорт HTTP (URL)​¶

Все опции конфигурации​¶

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

Обнаружение при запуске​¶

Соглашение об именовании инструментов​¶

Автоматическое внедрение​¶

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

Идемпотентность​¶

Типы транспорта​¶

Транспорт Stdio​¶

Транспорт HTTP / StreamableHTTP​¶

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

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

Очистка учётных данных в сообщениях об ошибках​¶

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

«MCP SDK не установлен — пропускаем обнаружение MCP-инструментов»​¶

«MCP-серверы не настроены»​¶

«Не удалось подключиться к MCP-серверу "X"»​¶

«MCP-серверу "X" требуется HTTP-транспорт, но mcp.client.streamable_http недоступен»​¶

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

Подключение постоянно разрывается​¶

Примеры​¶

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

Сервер файловой системы (npx)​¶

Сервер GitHub с аутентификацией​¶

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

Несколько серверов​¶

Сэмплинг (запросы LLM, инициированные сервером)​¶

Примечания​¶

Метаданные навыка¶

Справочник: полный SKILL.md¶

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

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

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

Справочник по конфигурации¶

Транспорт Stdio (команда + аргументы)¶

Транспорт HTTP (URL)¶

Все опции конфигурации¶

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

Обнаружение при запуске¶

Соглашение об именовании инструментов¶

Автоматическое внедрение¶

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

Идемпотентность¶

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

Транспорт Stdio¶

Транспорт HTTP / StreamableHTTP¶

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

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

Очистка учётных данных в сообщениях об ошибках¶

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

«MCP SDK не установлен — пропускаем обнаружение MCP-инструментов»¶

«MCP-серверы не настроены»¶

«Не удалось подключиться к MCP-серверу "X"»¶

«MCP-серверу "X" требуется HTTP-транспорт, но mcp.client.streamable_http недоступен»¶

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

Подключение постоянно разрывается¶

Примеры¶

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

Сервер файловой системы (npx)¶

Сервер GitHub с аутентификацией¶

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

Несколько серверов¶

Сэмплинг (запросы LLM, инициированные сервером)¶

Примечания¶