Действия приложения

Действия приложения — это выбранные методы backend плагина, описанные в OpenAPI. Через MCP AI может по просьбе пользователя работать с данными приложения или подготовить настройки его инструмента и шага. Пользователь не добавляет эти методы в агента или схему вручную: для работы через MCP они доступны только в проектах, где плагин установлен и активен.

Это отдельная возможность плагина:

• инструмент агента вызывается самим агентом во время диалога;
• шаг приложения выполняется внутри процесса автоматизации;
• действие для MCP вызывается AI, когда он помогает работать с интерфейсом и настройками плагина;
• метод отчёта передаёт данные из плагина в подключённую воронку.

Подготовьте интеграцию

Подготовьте OpenAPI с описаниями действий и реализуйте авторизацию backend. Для NestJS доступны декораторы SDK.

Включите действия в приложении

У приложения типа «Плагин» откройте раздел «Встроенная страница» и найдите блок «Действия приложения».

1. Включите «Публиковать действия в MCP».
2. Введите стабильный префикс методов длиной от 2 до 32 символов: строчные латинские буквы, цифры и _, начиная с буквы. Например, при префиксе my_plugin действие list_orders получит имя my_plugin__list_orders.
3. Укажите URL JSON-схемы OpenAPI backend приложения.
4. Нажмите отдельную кнопку «Сохранить» этого блока.

Префикс должен оставаться постоянным после публикации: полное имя метода использует AI и сохранённые сценарии. У двух активных установленных приложений одного проекта не должно быть одинакового полного имени действия.

Как MCP находит и вызывает действие

Действия установленных приложений не раздувают постоянный список MCP-инструментов. AI работает через общий протокол:

1. вызывает search с коротким описанием задачи;
2. берёт точное method_name из результата;
3. вызывает describe_method, если компактного ответа поиска недостаточно для вложенных параметров, схемы ответа или метаданных app_action;
4. вызывает execute с тем же method_name и объектом parameters по полученной схеме.

Например, поиск «получить аккаунты Prodamus» может вернуть prodamus__list_accounts, а поиск «получить реферальные кампании» — reflink__list_campaigns. AI не должен угадывать эти имена.

Область проекта зависит от вида MCP:

Подключение	Как определяется проект	Нужен ли project_id
Senler.io Project MCP	Проект зашит в проектный OAuth-токен	Нет; его нельзя подменить параметром
User MCP внутри агента или диалога проекта	Senler передаёт подписанный контекст выполнения	Нет; AI не должен его запрашивать
Прямое личное подключение User MCP	Выбранный проект не зашит в само подключение	Да; известный project_id повторяется в search, describe_method и execute

В прямом User MCP project_id — служебный верхнеуровневый параметр MCP-инструмента. Он не входит в parameters действия и не передаётся backend плагина. Подробный сценарий для AI-клиента описан в статье «Senler.io как MCP-сервер».

Проверьте в тестовом проекте

Установите и активируйте плагин в тестовом проекте. Для приватного приложения сначала откройте доступ этому проекту. Подключите Senler Project MCP или User MCP с правом использования приложений и дайте AI задачу, для которой подходит безопасное действие с read_only: true. Проверьте, что:

1. метод появился под именем <namespace>__<name>;
2. AI видит ожидаемые параметры и описание результата;
3. backend создаёт management session только для действительного launch_code;
4. действие получает Bearer-токен приложения и возвращает ответ за 15 секунд;
5. изменяющие и необратимые операции правильно отмечены флагами безопасности.

Не помещайте Client Secret, management token и закрытые данные в OpenAPI, описание действия или его параметры.

Если действие не появилось

• убедитесь, что плагин установлен и его установка активна в выбранном проекте;
• проверьте переключатель публикации и сохранение блока;
• откройте URL OpenAPI с сервера, а не только из браузера разработчика;
• запустите senler-app validate-openapi и убедитесь, что операция использует поддерживаемый HTTP-метод и точное расширение x-senler-app-action версии 1;
• подождите до 30 секунд после изменения схемы;
• проверьте уникальность полного имени <namespace>__<name> среди установленных приложений;
• для ошибки создания management session проверьте путь /api/embedded/management-session, подпись и срок launch_code, а также поле management_token в ответе;
• для ошибки выполнения проверьте endpoint, Bearer-токен, ответ backend и лимит 15 секунд.