🏠 Главная › user guide › mcp native mcp

{/ Эта страница автоматически передается из навыков SKILL.md с помощью сайта/scripts/generate-skill-docs.py. Редактируйте исходный SKILL.md, а не эту страницу. /}

Родной Mcp

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

Метаданные навыки
Источник Встроенный (устанавливается по умолчанию)
Путь skills/mcp/native-mcp
Версия 1.0.0
Автор Агент Гермес
Лицензия Массачусетский технологический институт
Платформы Linux, MacOS, Windows
Теги MCP, Инструменты, Интеграции
Связанные навыки mcporter

Справочник: полный SKILL.md:::информация

Ниже приведено полное описание навыков, которые Hermes загружает при его активации. Агент увидит эту инструкцию, когда навыки активны.

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

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

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

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

Для разовых, одноразовых вызовов инструментов MCP из терминала без настройки текущего навыка mcporter.

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

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

pip install mcp
# или, если используете uv:
uv pip install mcp

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

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

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

Перезапустите агент Гермес. При запуске он: 1. Подключится к серверу 2. Обнаружить доступные инструменты 3. Зарегистрирует их с префиксом mcp_time_* 4. Внедрить их во все наборы инструментов платформы.

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

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

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

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

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

Транспорт HTTP (url)

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

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

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

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

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

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

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

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

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

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

mcp_{server_name}_{tool_name}

Дефисы и точки в названии заменяются для подчёркивания для совместимости с 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 доступны в каждом разговоре без дополнительных настроек.

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

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

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

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

Транспортная студия

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

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

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

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

Для удалений или настройки серверов MCP. Требуется пакет mcp для поддержки HTTP-клиента (mcp.client.streamable_http).

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

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

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

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

Для стандартных серверов Hermes НЕ обеспечивает полное окружение вашей обработки подпроцессов MCP. Наблюдаются только безопасные базовые переменные:

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

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

Удаление учётных данных из сообщений об ошибках

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

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

«MCP SDK недоступен – пропуск обнаружения инструмента MCP»

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

pip install mcp

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

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

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

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

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

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

pip install --upgrade mcp

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

Соединение постоянно разрывается

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

Примеры

Сервера времени (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

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

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

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

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

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

Серверы также могут включать в себя «инструменты» по запросу для многократных процессов с инструментами. Конфигурация max_tool_rounds собственные бесконечные циклы инструментов. Метрики аудита для каждого сервера (запросы, ошибки, токены, количество использованных инструментов) отслеживаются через get_mcp_status().

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

Примечания