enВойти в Senler

Вызов методов через MCP

Сначала подключите Project MCP или User MCP и подтвердите необходимые права. Действия выполняются в пределах прав подключения, а не по одному знанию ID проекта.

Какие инструменты видит AI

Чтобы не передавать модели тысячи методов Senler и установленных приложений сразу, MCP оставляет компактный набор инструментов обнаружения. Через них User MCP находит в том числе методы управления developer-приложениями пользователя:

ИнструментКогда использовать
searchНайти методы API Senler и действия установленных приложений по задаче.
describe_methodПолучить полную схему параметров, ответа и метаданные одного точного метода.
executeВызвать точный метод, найденный через search.
search_documentationНайти документацию о поведении, настройках и ограничениях.
get_documentation_pageПрочитать полную страницу по точному document_ref из поиска или ссылки в уже прочитанной статье.

Некоторые MCP-клиенты умеют динамически показывать найденный метод как отдельный инструмент. В таком клиенте AI может вызвать его напрямую. Также клиент может показывать служебные инструменты состояния подключения, но это не меняет основной протокол обнаружения.

Для вопроса «как настроить» AI сначала использует search_documentation, затем get_documentation_page. Для чтения или изменения фактических данных он использует search, при необходимости describe_method, затем execute.

Инструменты search_documentation и get_documentation_page доступны без пользовательской авторизации: они читают справку. Это позволяет отвечать на вопросы об интерфейсе и из VK. Авторизация нужна отдельно для чтения или изменения конкретного проекта; профиль VK сам по себе не даёт такого доступа.

Например, по справке можно объяснить, когда появляется кнопка «Опубликовать». Но справка не показывает, есть ли неопубликованные изменения у конкретного агента. Если у помощника нет доступа к проекту, состояние можно уточнить по описанным признакам или скриншоту пользователя. Ответ на основе справки не является проверкой настроек проекта.

Как вызвать метод

AI не должен придумывать имя метода или поля формы. Правильная последовательность:

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

Используйте в search короткие русские фразы, так как большинство описаний методов API Senler написано по-русски.

Например, в Project MCP:

{"query":"получить аккаунты Prodamus"}

Поиск может вернуть prodamus__list_accounts. Если сведений достаточно, вызов выглядит так:

{
  "method_name": "prodamus__list_accounts",
  "parameters": {}
}

Для RefLink аналогичный поиск может вернуть reflink__list_campaigns. Префикс до __ задаёт разработчик приложения, поэтому AI всегда берёт полное имя из текущего ответа search, а не строит его самостоятельно.

User MCP также позволяет создавать и настраивать приложения, принадлежащие разработчику. Полный порядок, разделение appId и project_id, правила черновиков и ручные действия описаны в статье «Разработка приложения через User MCP».

Как передавать project_id

Для Project MCP не передавайте project_id в search, describe_method или execute: сервер берёт его из проверенного проектного OAuth-токена.

Для User MCP действуют два режима:

  • если User MCP вызывается агентом или диалогом внутри проекта, проект уже находится в подписанном контексте выполнения — project_id не нужен;
  • при прямом личном подключении User MCP используйте уже известный целевой project_id в search, а затем повторите тот же ID в describe_method и execute для метода установленного приложения.

Пример прямого User MCP:

{
  "query": "получить реферальные кампании",
  "project_id": "<ID проекта>"
}
{
  "method_name": "reflink__list_campaigns",
  "project_id": "<тот же ID проекта>",
  "parameters": {}
}

project_id здесь — верхнеуровневый служебный параметр MCP, а не поле parameters плагина. Само действие не должно объявлять project_id в OpenAPI.

Нужно ли передавать ID приложения

Нет. search получает не ID приложения, а описание задачи. Senler сам добавляет в поиск действия всех активных приложений, установленных в выбранном проекте. Чтобы сузить поиск, достаточно упомянуть понятное имя приложения или нужное действие, например «аккаунты Prodamus» или «кампании RefLink».

Действие появляется, только если:

  • плагин установлен и активен в целевом проекте;
  • разработчик включил публикацию действий и указал доступный URL OpenAPI;
  • операция размечена x-senler-app-action;
  • текущее подключение имеет право can_use_project_apps.

Для вызова действия достаточно can_use_project_apps «Использование установленных приложений». can_manage_project_apps относится к установке, изменению и удалению приложений и отдельно для вызова действия не требуется. Если разрешение добавили в политику OAuth после подключения, пройдите OAuth заново: расширение политики не добавляет новые права в уже выпущенный токен.

Как AI настраивает формы приложения

OpenAPI действия заменяет для AI неизвестную визуальную форму:

  • context: app описывает обычную работу с данными встроенной или основной страницы;
  • context: agent_tool возвращает проверенную нормализованную конфигурацию инструмента агента;
  • context: automation_step возвращает конфигурацию шага и при необходимости его ветки.

Для двух последних контекстов AI сначала вызывает конфигуратор приложения по его схеме, затем сохраняет значение из app_action.result.configuration_path и ветки из branches_path соответствующим методом API Senler. Он не должен угадывать поля визуальной формы или вызывать конфигуратор повторно во время выполнения опубликованной автоматизации.

Технический обмен между Senler и backend плагина описан в авторизации действий приложения. Токен внешнего AI-клиента не передаётся плагину.

Если метод не найден или недоступен

  • повторите search короткими русскими словами и близкими синонимами;
  • не выполняйте придуманное имя после пустого поиска;
  • для прямого User MCP проверьте, что один и тот же project_id передан в обнаружение и вызов действия;
  • проверьте установку и активность плагина в нужном проекте;
  • проверьте право can_use_project_apps в действующем токене, а не только в текущих настройках OAuth-приложения;
  • после изменения OpenAPI подождите до 30 секунд и повторите поиск;
  • если describe_method не находит имя, сначала снова получите его через search в том же проекте.
Предыдущая
Senler.io MCP
Далее
Авторизация