MCP (Model Context Protocol)

· 7 мин чтения · admin

Что такое MCP (Model Context Protocol)

MCP (Model Context Protocol) — это протокол, позволяющий Hermes Agent подключаться к внешним серверам инструментов и использовать их возможности: работу с GitHub, базами данных, файловыми системами, браузерами, внутренними API и многим другим. Если вам нужно, чтобы агент работал с инструментом, который уже существует где-то снаружи, MCP — самый чистый способ это сделать.

Возможности MCP

  • Доступ к внешним инструментам — без необходимости писать нативный инструмент для Hermes
  • Два типа серверов — локальные stdio-серверы и удалённые HTTP-серверы в одном конфиге
  • Автоматическое обнаружение — инструменты регистрируются при запуске
  • Утилиты для ресурсов и промптов — когда сервер их поддерживает
  • Фильтрация — настройка видимых инструментов на каждый сервер
  • Sampling — серверы могут запрашивать LLM-комплишены через агента во время выполнения инструментов
  • Переподключение — автоматическое реконнект с экспоненциальным backoff (до 5 попыток)

CLI-команды для MCP

Hermes предоставляет набор 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   Настроить выбор инструментов (toggle)

Примеры использования CLI

# Добавить stdio-сервер
hermes mcp add github --command "npx" -- "-y" "@modelcontextprotocol/server-github"

# Добавить HTTP-сервер
hermes mcp add remote-api --url "https://mcp.example.com/mcp"

# Проверить подключение
hermes mcp test github

# Посмотреть все серверы
hermes mcp list

# Удалить сервер
hermes mcp remove github

Конфигурация в config.yaml

MCP-серверы настраиваются в ~/.hermes/config.yaml (или профильном config.yaml) под ключом mcp_servers:

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

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

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

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

Подключение MCP-серверов

Stdio-серверы

Stdio-серверы запускаются как локальные процессы и общаются через stdin/stdout. Это самый распространённый вариант для инструментов, работающих на вашей машине.

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

HTTP-серверы

HTTP-серверы работают по сети и подключаются через URL. Подходят для общих сервисов и удалённых API.

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

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

Инструменты с MCP-серверов регистрируются с префиксом:

mcp_{server_name}_{tool_name}

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

  • Сервер 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.

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

Укажите tools: с перечнем разрешённых инструментов — все остальные будут скрыты:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    tools: ["list_issues", "create_issue"]

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

Укажите exclude_tools: с перечнем запрещённых инструментов:

mcp_servers:
  stripe:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-stripe"]
    exclude_tools: ["delete_customer", "refund_charge"]

Полное отключение сервера

Чтобы временно отключить сервер, используйте enabled: false:

mcp_servers:
  github:
    enabled: false
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]

Slash-команда /reload-mcp

Для перезагрузки MCP-серверов во время сессии без перезапуска агента:

/reload-mcp

Эта команда:

  • Отключает все текущие MCP-соединения
  • Повторно читает конфигурацию из config.yaml
  • Подключается ко всем серверам заново
  • Перерегистрирует инструменты

Полезно после изменения конфигурации MCP-серверов без необходимости перезапускать весь агент.

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

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

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: []      # whitelist моделей (пусто = все)
      max_tool_rounds: 5      # лимит вызовов инструментов (0 = отключить)
      log_level: "info"       # подробность аудита

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

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

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

Для 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 автоматически редактируются из сообщения об ошибке: GitHub PATs, OpenAI-ключи, Bearer-токены, generic-паттерны token=, key=, API_KEY=, password=, secret=.

Примеры использования

  • GitHub — управление issues и pull requests через MCP-сервер GitHub с фильтрацией только на нужные операции
  • Файловая система — доступ к файлам конкретного проекта без расширения прав
  • Stripe — работа с платежами, но с исключением опасных операций вроде возвратов
  • Внутренние API — подключение к корпоративным сервисам через HTTP-серверы
  • Время — получение текущего времени через mcp-server-time

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

Временной сервер (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

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

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

Удалённый 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

Все инструменты от всех серверов регистрируются и доступны одновременно.

Типичные проблемы

«MCP SDK not available»

Пакет mcp не установлен:

pip install mcp

«No MCP servers configured»

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

«Failed to connect to MCP server ‘X’»

  • Команда не найдена: бинарник command не в PATH
  • Пакет не найден: для npx-серверов может потребоваться -y в args
  • Таймаут: увеличьте connect_timeout
  • Недоступность: для HTTP-серверов проверьте URL

Инструменты не появляются

  • Проверьте ключ mcp_servers (не mcp или servers)
  • Убедитесь в правильном отступе YAML
  • Имена инструментов имеют префикс mcp_{server}_{tool}

Примечания

  • MCP-инструменты вызываются синхронно с точки зрения агента, но работают асинхронно на фоновом event loop
  • Результаты возвращаются как JSON: {"result": "..."} или {"error": "..."}
  • Нативный MCP-клиент независим от mcporter — можно использовать оба одновременно
  • Соединения персистентные и разделяются между всеми сессиями в одном процессе агента
  • Для добавления или удаления серверов: перезапуск агента или /reload-mcp
  • Подробнее: скилл native-mcp