MCP-инструменты¶
MCP (Model Context Protocol) — открытый протокол, который подключает к агенту внешние инструменты и источники данных: веб-поиск, работу с браузером, корпоративные API и многое другое. Каждый MCP-сервер предоставляет набор инструментов, которые агент может вызывать как обычные.
MCP-инструменты отделены от встроенных: они появляются в подсказке только активных серверов сессии и подчиняются режимам.
Что такое MCP-сервер¶
- Сервер объявляет список инструментов и краткие описания; полные схемы параметров агент видит при вызове.
- Имя инструмента складывается из имени сервера и имени инструмента:
{сервер}_{инструмент}. - Сервер может передать агенту собственные
instructions— они показываются вместе с его описанием. - Состав инструментов меняется динамически, поэтому MCP не кэшируется и всегда пересобирается под текущую сессию.
Транспорты¶
| Транспорт | Как работает | Где применять |
|---|---|---|
| stdio | Локальный процесс, запускается как дочерний | Локальная разработка |
| Streamable HTTP | Единый HTTP-эндпоинт /mcp |
Docker / Kubernetes, общий сервер |
stdio — только администратор
Локальный запуск MCP-сервера — это выполнение произвольного кода (RCE- риск). Поэтому stdio-серверы на уровне инстанса добавляет только администратор. HTTP-серверы может добавить любой пользователь.
Реестр серверов¶
Все серверы хранятся в едином реестре:
- HTTP-сервер добавляет любой пользователь; в записи фиксируется автор и признак доверия (проверенный / из сообщества).
- stdio-сервер добавляет администратор на уровне инстанса.
- Администратор задаёт, какие серверы включать по умолчанию в новых проектах.
Реестр — источник истины¶
Реестр одинаково работает в локальном и в серверном режиме, и это единственный источник правды о подключённых серверах:
- В локальном режиме реестр доступен. Добавление, проверка, включение и удаление серверов работают без серверного бэкенда.
- Серверы из конфигурации переносятся в реестр. Если сервер описан в
config.yaml, при старте он попадает в реестр (один раз на имя) и остаётся там: правка реестра больше не стирает конфигурацию. - Состав активных серверов берётся из реестра — тем же кодом, что и в серверном режиме.
Управлять реестром можно из интерфейса или из CLI:
synth mcp list
synth mcp add --name playwright --type http --url http://127.0.0.1:8931/mcp
synth mcp test playwright
synth mcp reconnect playwright
synth mcp remove playwright
Проверка сервера (probe)¶
Перед регистрацией сервер можно проверить — подключиться и посмотреть список инструментов, не добавляя их в реестр. Это удобно, чтобы убедиться в доступности и корректности URL.
Уровни и включение¶
Серверы настраиваются на трёх уровнях:
| Уровень | Кто управляет | Что задаёт |
|---|---|---|
| Система | администратор | Мастер-флаг: выключенный сервер недоступен нигде и никогда. Здесь же — включение по умолчанию в новых проектах |
| Проект | владелец проекта | Разрешённые серверы проекта и серверы, включённые по умолчанию для новых сессий |
| Сессия | пользователь | Личные серверы и точечное включение/отключение, в том числе системных |
Правила сочетания уровней:
- Сервер активен, только если он разрешён системой и проектом, не отключён в сессии и попал в набор по умолчанию или включён вручную.
- По умолчанию серверы выключены: без явного включения сервер виден в списке, но неактивен.
- При конфликте имён приоритет: система → проект → сессия.
- Системное и проектное отключение действует и на старые сессии; смена дефолтов влияет только на новые проекты и сессии.
- Отключённый сервер не исчезает из списка: он показывается с пометкой
disabledи причиной — система запретила, проект не разрешил, отключён в сессии или не входит в набор по умолчанию.
Доступность по режимам¶
Для каждого сервера и инструмента можно задать, доступен ли он в Plan и в Act. Недоступный в текущем режиме инструмент отклоняется. Это позволяет, например, оставить в режиме плана только инструменты чтения.
Политика контекста¶
MCP-инструменты — заметная часть контекста, поэтому ими можно управлять:
| Политика | Поведение |
|---|---|
| consistency | В подсказку идут все определения; недоступность помечается отдельно. Приоритет — стабильность кэша |
| available | В подсказку идут только доступные инструменты. Приоритет — экономия контекстного окна |
| auto | Выбор по модели и провайдеру: локальные модели → available, облачные → consistency |
По умолчанию действует auto. Политику можно переопределить для конкретной
сессии.
Настройка в интерфейсе¶
- Настройки → MCP-серверы — реестр: добавление HTTP- и stdio-серверов, проверка, включение по умолчанию, админские настройки.
- Правая панель → «Сессия» — тумблеры серверов для текущей сессии; отключённые видны с причиной.
- Правая панель → «Проект» — какие серверы доступны проекту и включены по умолчанию.
- Статистика — вкладка с раскладкой по серверам: статус, инструменты, доступность по режимам и оценка токенов.
Пример: подключение HTTP-сервера¶
Порядок добавления HTTP (Streamable HTTP) MCP-сервера:
- Откройте Настройки → MCP-серверы.
- Добавьте сервер с типом
Streamable HTTP. - Укажите URL, по которому доступен сервер (единый эндпоинт
/mcp). - Проверьте сервер (probe) и включите нужные инструменты.
Набор инструментов задаёт сам сервер. Например, MCP-сервер веб-инструментов может предоставлять поиск в интернете, извлечение контента страниц и управление headless-браузером — состав вы увидите на шаге проверки.
Ограничения
Извлечение контента выполняется без JavaScript — для страниц-приложений (SPA) используйте браузерные инструменты сервера. Внешние сервисы могут ограничивать частоту запросов.
Из чата: команда /instance¶
Агент может работать с реестром и разбираться в инстансе сам — без обращения к API вручную.
- Команда
/instance— встроенный сценарий самопомощи: агент отвечает на вопросы об инстансе, его данных, MCP-серверах, проектах и сессиях. - Инструменты инстанса. Чтение:
synth_info(версия, режим, каталог данных, состояние хранилища),synth_mcp_list(серверы, их статус, причина неактивности, сетевая политика),synth_mcp_test(разовая проверка подключения без регистрации). - Изменение реестра.
synth_mcp_add,synth_mcp_update,synth_mcp_remove,synth_mcp_enable,synth_mcp_reconnect— агент может добавить сервер, включить его на уровне сессии, проекта или инстанса и переподключить после сбоя. В режиме плана изменяющие инструменты заблокированы. - Проекты и сессии. Агент видит список проектов и сессий, может открыть проект и присоединиться к нему.
- Без секретов. В ответах есть адреса и статусы, но нет ключей, заголовков авторизации и содержимого переменных окружения: ссылка с учётными данными редактируется.
Пример: спросите агента «почему MCP-сервер второй не активен» — он посмотрит реестр и ответит с причиной.
Безопасность¶
- Секреты и заголовки авторизации MCP-вызовов маскируются в промптах и журналах.
- Для пользовательских HTTP-серверов по умолчанию запрещён доступ к приватным и служебным сетевым диапазонам — защита от SSRF и утечек.
- Проектное включение пользовательских серверов проходит через владельца проекта — человеческий контроль для недоверенных серверов.
- Все вызовы попадают в аудит.