MCP на практике

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

Что такое MCP и зачем он нужен

MCP (Model Context Protocol) — открытый протокол, позволяющий AI-агентам подключаться к внешним инструментам и данным через стандартизированный интерфейс. Вместо того чтобы писать интеграции для каждого сервиса отдельно, MCP даёт единый способ «подключить» файловые системы, Git, GitHub, базы данных и внутренние API к вашему ассистенту.

Hermes Agent имеет встроенный MCP-клиент — он подключается к серверам при старте, обнаруживает их инструменты и регистрирует их как собственные. Инструменты с MCP-серверов появляются рядом с встроенными (terminal, read_file и т.д.) и доступны на всех платформах (CLI, Telegram, Discord и др.).

Команды CLI для работы с MCP

Hermes предоставляет набор команд для управления MCP-серверами:

Команда	Описание
`hermes mcp serve`	Запустить Hermes как MCP-сервер (для IDE и внешних клиентов)
`hermes mcp add NAME`	Добавить MCP-сервер (`--url` для HTTP или `--command` для stdio)
`hermes mcp remove NAME`	Удалить MCP-сервер из конфигурации
`hermes mcp list`	Показать все настроенные серверы и их статус
`hermes mcp test NAME`	Проверить подключение к серверу
`hermes mcp configure NAME`	Интерактивный выбор инструментов (включить/выключить)

Внутри сессии используйте /reload-mcp для горячей перезагрузки MCP-серверов без перезапуска агента.

Конфигурация mcp_servers

MCP-серверы настраиваются в ~/.hermes/config.yaml (или профильном config.yaml) под ключом mcp_servers. Каждый сервер — имя с конфигурацией.

Stdio-транспорт (команда)

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

HTTP / StreamableHTTP транспорт (URL)

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

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

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

У сервера должен быть либо command (stdio), либо url (HTTP), но не оба одновременно.

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

Инструменты с 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

Фильтрация инструментов

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

Разрешите только нужные операции — ключевой приём безопасного использования:

mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] tools: include: [list_issues, create_issue, search_code] prompts: false resources: false

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

Если инструментов много и нужен «всё кроме опасных»:

tools: exclude: [delete_repo, force_push]

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

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

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

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

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

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

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" # детализация аудита

Серверы могут включать tools в запросы sampling для многошаговых workflow. Параметр max_tool_rounds предотвращает бесконечные циклы. Отключите sampling для ненадёжных серверов: sampling: { enabled: false }.

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

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

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

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
Все переменные XDG_*

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

Скрытие учётных данных в ошибках

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

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

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

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

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

MCP SDK not available — пакет mcp не установлен. Решение: pip install mcp
No MCP servers configured — нет ключа mcp_servers в config.yaml. Добавьте хотя бы один сервер.
Failed to connect to MCP server ‘X’ — команда не найдена на PATH, пакет не существует, таймаут подключения, или HTTP-эндпоинт недоступен.
Requires HTTP transport but streamable_http not available — обновите пакет: pip install --upgrade mcp
Инструменты не появляются — проверьте include/exclude, убедитесь что enabled: false не выставлен случайно. Проверьте YAML-отступы.
Подключение постоянно рвётся — клиент повторяет до 5 попыток с экспоненциальной задержкой (1с, 2с, 4с, 8с, 16с, макс. 60с). Проверьте сервер и сетевое подключение.

С чего начать

Лучшие серверы для первого опыта:

time (uvx mcp-server-time) — самый простой, не требует ключей
filesystem (npx @modelcontextprotocol/server-filesystem) — работа с файлами
GitHub (npx @modelcontextprotocol/server-github) — нужен PAT

Избегайте подключения крупных корпоративных систем без фильтрации — начните с узких, понятных интеграций. Используйте hermes mcp test NAME для проверки подключения перед использованием.