Перейти к содержанию

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-сервера:

  1. Откройте Настройки → MCP-серверы.
  2. Добавьте сервер с типом Streamable HTTP.
  3. Укажите URL, по которому доступен сервер (единый эндпоинт /mcp).
  4. Проверьте сервер (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 и утечек.
  • Проектное включение пользовательских серверов проходит через владельца проекта — человеческий контроль для недоверенных серверов.
  • Все вызовы попадают в аудит.

Что дальше