Senler.io как MCP-сервер

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

Это обратный сценарий по отношению к обычному разделу «MCP-серверы»: там внешний сервер подключается к агенту Senler, здесь внешний AI-клиент подключается к Senler.

Project MCP и User MCP

Подключение	Область доступа	Как определяется проект
Senler.io Project MCP	Один проект и выданные для него OAuth-права	`project_id` зашит в проектный OAuth-токен
Senler.io User MCP	Пользователь и разрешённые ему ресурсы	Для прямого личного подключения целевой проект выбирается для запроса; внутри агента или диалога проект приходит из подписанного контекста Senler

Project MCP удобен, когда внешнее приложение должно работать только с одним подключённым проектом. Переданный в тексте или параметрах другой ID не меняет проект такого подключения.

User MCP подходит для работы от имени пользователя. Он может авторизоваться через пользовательский OAuth или MCP access key вида mcp_sk_…, который связан с сохранённой авторизацией. Ключ передавайте только как секрет подключения и никогда не помещайте в запрос агента, документацию или параметры метода.

Какие инструменты видит 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.

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

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

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

Используйте в 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. Он не должен угадывать поля визуальной формы или вызывать конфигуратор повторно во время выполнения опубликованной автоматизации.

Как MCP авторизуется в плагине

Токен внешнего AI-клиента работает только между клиентом, MCP и API Senler. Backend плагина не получает MCP access key, пользовательский OAuth-токен или проектный OAuth-токен.

Цепочка вызова выглядит так:

AI-клиент → Senler MCP → API Senler → management session плагина → endpoint действия

После проверки проекта, права can_use_project_apps, активной установки и OpenAPI Senler создаёт подписанный одноразовый launch_code. Backend приложения проверяет его своим Client Secret и возвращает собственный короткоживущий management_token. Только этот токен Senler передаёт в endpoint действия как Authorization: Bearer <management_token>.

Если backend плагина затем сам обращается к API Senler, ему нужен отдельный API-ключ или OAuth access token приложения с нужными правами. management_token и исходный MCP-токен для вызова API Senler не используются. Техническая реализация описана в статье «Действия приложения».

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

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