Управление MCP

Раздел «AI» → «MCP» предназначен для настройки инструментов, которые AI-ассистент и встроенный MCP-сервер могут вызывать от имени пользователя.

Доступ к разделу «AI» контролируется глобальным разрешением view:ai-page. Настройка MCP-серверов, инструментов и коллекций — отдельными глобальными разрешениями read: / edit: (см. ролевую модель).

Обзор

В AI-ассистенте инструменты отображаются со следующими типами:

• internal — встроенные инструменты портала (описаны в документации MCP-сервера);
• external — инструменты, полученные из подключённого upstream MCP-сервера;
• custom — пользовательские MCP-инструменты.

Любой инструмент, включая internal, доступен только через включённую MCP-коллекцию, которую пользователь может использовать. Права на действие с объектом портала проверяются при вызове отдельно.

MCP-серверы

Подключите upstream MCP-сервер, чтобы импортировать его инструменты в каталог портала.

1. Перейдите в «AI» → «MCP» → «MCP-серверы».
2. Нажмите «Подключить MCP-сервер».
3. На вкладке «Основная информация» укажите «Название», «Идентификатор», «Описание», «Владелец» и «Команда владелец».
4. На вкладке «Авторизация»:
   1. Включите переключатель «Включить».
   2. Выберите «Транспорт» (HTTP или SSE).
   3. Укажите «URL» upstream MCP-сервера.
   4. При необходимости добавьте «Заголовки» и «Учётные данные» для авторизации.
5. Нажмите «Сохранить».

После сохранения откройте карточку сервера и нажмите «Синхронизировать», чтобы загрузить каталог инструментов. На вкладке «Инструменты» включите нужные инструменты и при необходимости задайте «Теги». Включите их в коллекцию, чтобы предоставить доступ пользователям и агентам.

Чтобы подготовить подключение без доступа к его инструментам, сохраните сервер с выключенным переключателем «Включить». Он останется выключенным после создания; инструменты станут доступны для вызовов только после его включения и выдачи доступа через коллекции.

Учётные записи

Для синхронизации каталога и проверки доступности выберите «Системная учётная запись» и заполните у неё реквизиты, используемые в заголовках. Она нужна для этих операций и тогда, когда сервер не требует авторизации.

Вызовы инструментов по умолчанию используют реквизиты вызывающего пользователя. Чтобы всегда обращаться к серверу с реквизитами определённого пользователя, включите «Выбрать учётную запись для вызовов» и заполните «Учётная запись для вызовов». Системная учётная запись синхронизации сама по себе не меняет реквизиты вызовов.

Автоматическая синхронизация

На вкладке «Авторизация» включите «Периодическая синхронизация», задайте «Периодичность запуска» в формате cron и выберите системную учётную запись. Без автоматической синхронизации обновляйте каталог кнопкой «Синхронизировать».

Каталог заменяется только после успешного получения полного списка инструментов. Неудачная синхронизация сохраняет последний успешный каталог и показывает «Каталог устарел: последняя синхронизация не удалась». Изменение списка на внешнем сервере вступает в силу после успешной синхронизации.

Проверка доступности и ошибки

Кнопка «Проверить доступность» проверяет соединение с сервером, но не обновляет каталог. Состояние соединения и актуальность каталога показываются отдельно:

Если системная учётная запись или учётная запись для вызовов заблокирована либо не выбрана, измените настройки сервера. После исправления реквизитов проверьте операцию именно с исправленной учётной записью: успешный вызов с личными реквизитами другого пользователя не снимает ошибку настроенной учётной записи.

Ошибки авторизации личных реквизитов относятся к вызывающему пользователю и не означают недоступность сервера для всех. При сетевой ошибке проверьте результат изменяющей операции во внешней системе перед повтором.

MCP-инструменты

Создайте пользовательский MCP-инструмент, который AI-ассистент вызывает напрямую, без upstream MCP-сервера.

1. Перейдите в «AI» → «MCP» → «MCP-инструменты».
2. Нажмите «Добавить».
3. На вкладке «Основная информация» укажите «Название», «Описание», «Владелец», «Команда владелец» и «Теги».
4. На вкладке «Конфигурация»:
   1. Включите переключатель «Включить».
   2. Задайте «Схему аргументов» (JSON Schema с корневым типом object).
   3. При необходимости укажите «Сопоставление path-параметров» — объект JSON, который сопоставляет имена аргументов с сегментами {placeholder} в URL исполнителя.
   4. При необходимости укажите «Сопоставление query-параметров» — объект JSON, который сопоставляет имена аргументов с именами query-параметров URL.
   5. При необходимости укажите «Сопоставление body-параметров» — объект JSON, который сопоставляет имена аргументов с именами полей JSON-тела запроса.
5. На вкладке «Авторизация» укажите «URL» эндпоинта исполнителя, «HTTP-метод», «Заголовки» и «Учётные данные». При необходимости включите «Выбрать учётную запись для вызовов», чтобы использовать реквизиты выбранного пользователя вместо вызывающего. В URL можно использовать сегменты {placeholder} для path-параметров и плейсхолдеры учётных данных, например {{ .credentials.tenant_id }}.
6. Нажмите «Сохранить».

Сохраните инструмент с выключенным переключателем «Включить», если его пока нельзя использовать. Выключенное состояние сохраняется при создании; для вызовов инструмент потребуется включить и добавить в доступную коллекцию.

Пример. В схеме аргументов задан аргумент space_id, URL исполнителя — https://api.example.com/v1/spaces/{spaceId}/boards, сопоставление path-параметров — {"space_id": "spaceId"}. При вызове инструмента с space_id=42 запрос будет отправлен по адресу https://api.example.com/v1/spaces/42/boards.

Аргументы передаются эндпоинту исполнителя следующим образом:

• Сопоставление path-параметров и сопоставление query-параметров применяются для всех HTTP-методов. В URL как query-параметры добавляются только аргументы, указанные в «Сопоставлении query-параметров».
• Для GET и DELETE тело запроса не отправляется. Аргументы, которые не указаны в «Сопоставлении path-параметров» или «Сопоставлении query-параметров», не передаются.
• Для POST, PUT и PATCH JSON-тело запроса строится по «Сопоставлению body-параметров». Если сопоставление пустое, в тело попадают все аргументы инструмента, включая аргументы для path и query. Если сопоставление задано, в тело попадают только указанные в нём аргументы.

MCP-коллекции

MCP-коллекция объединяет инструменты и определяет, какие из них доступны пользователю и агенту. Она может содержать отдельные инструменты, MCP-серверы целиком и группы инструментов портала целиком.

Создание коллекции

Чтобы подготовить фиксированный набор инструментов чтения каталога:

1. Откройте «AI» → «MCP» → «MCP-коллекции» и нажмите «Создать коллекцию».
2. Заполните название, идентификатор, описание, владельца и команду.
3. Включите коллекцию переключателем «Включить».
4. В составе коллекции нажмите «Добавить в коллекцию» и выберите отдельные инструменты get_resources и get_resource_entities.
5. Нажмите «Сохранить».
6. В меню коллекции выберите «Настроить доступ» и выдайте пользователям или командам роль с use:mcp-collections.

Пользователь сможет вызывать эти инструменты из MCP-клиента с собственным API-токеном. Для агента дополнительно подключите коллекцию к агенту. Права на чтение ресурсов и сущностей каталога предоставляются отдельно.

Группы и серверы целиком

В «Добавить в коллекцию» можно выбрать «Группы портала целиком», например «Каталог», «Обозреватель каталога» или «Курируемые», либо «MCP-серверы целиком». Новые инструменты выбранного источника входят в коллекцию автоматически после обновления портала или синхронизации сервера.

«Обозреватель каталога» предназначен для поиска, подсчёта и группировки сущностей, обхода связей и диагностики процессов. Состав инструментов и примеры вызовов — в справочнике MCP. «Курируемые» объединяет специализированные инструменты с префиксом curated_, включая запуск процессов, чтение навыков и подготовку рабочих пространств.

Просмотрите состав и исключите ненужные инструменты, затем сохраните. Исключение из одной коллекции не отменяет доступ, предоставленный другой коллекцией.

Если набор должен оставаться фиксированным, добавляйте отдельные инструменты. Группы могут включать операции изменения и удаления данных; проверяйте их состав перед выдачей доступа.

Доступ и включение

Выключенная коллекция не предоставляет инструменты. Владение коллекцией и участие в её команде дают права при включённой настройке owner-is-admin; доступ остальных пользователей задаётся ролями. Супер-администратор имеет доступ ко всем коллекциям.

Каталог

Раздел «Каталог» показывает все инструменты, доступные текущему пользователю с учётом MCP-коллекций и прав доступа. Раздел предназначен только для просмотра. Редактирование выполняется на страницах «MCP-серверы», «MCP-инструменты» и «MCP-коллекции».

Связь с AI-ассистентом и MCP-сервером

Чтобы выдать инструменты агенту:

1. Откройте редактирование агента в «AI» → «Агенты» → «Каталог».
2. На вкладке «Инструменты и навыки» выберите «MCP-коллекции» и сохраните.
3. Убедитесь, что запускающему пользователю разрешены нужные инструменты через доступные ему коллекции.
4. Выдайте пользователю право использовать агента и необходимые права на объекты портала.
5. Запустите новый диалог или задание и проверьте вызов инструмента.

Набор инструментов запуска — пересечение инструментов коллекций агента и инструментов, доступных запускающему пользователю. Пользователь может получать тот же инструмент через другую коллекцию; совпадение самой коллекции не требуется.

Без коллекций агент работает без MCP-инструментов. Правило действует для платформенного и внешних агентов в ассистенте, виджете и процессе. Для агента из источника коллекции задаёт источник.

Внешний MCP-клиент использует коллекции своего пользователя; привязка к агенту для него не требуется. Рабочее пространство вызывает MCP от имени владельца и использует его доступ к инструментам.

Настройка после обновления

При переходе на модель коллекций прежние списки «MCP-инструменты» агентов и источников не переносятся. До обновления сохраните списки, затем создайте соответствующие коллекции, выдайте доступ пользователям и назначьте коллекции агентам и источникам.