MCP: программный интерфейс

Кроме REST, у GetMyBot есть интерфейс MCP (Model Context Protocol): он рассчитан на ИИ-агентов и ассистентов, которые вызывают инструменты, а не дёргают эндпоинты вручную. REST остаётся первичным интерфейсом; MCP: удобная альтернатива для агентных сценариев. Имена инструментов, ресурсов и промптов ниже совпадают с тем, что публикует сервер.

Адрес и авторизация

MCP доступен по эндпоинту /mcp (транспорт Streamable HTTP, метод POST). Авторизация: тот же персональный токен, что и для REST: заголовок Authorization: Bearer mbp_…. Отдельные токены заводить не нужно: один PAT работает и для REST, и для MCP. Токен привязан к одному кабинету: list_bots и остальные инструменты видят боты только этого кабинета, а get_balance, get_transactions и connect_bot относятся к нему же (см. Кабинет токена). Каждый инструмент требует того же scope, что и соответствующий REST-эндпоинт; токен со scope * имеет полный доступ. Если scope не хватает: вызов отклоняется (fail-closed), как и в REST.

Если токен выпущен для чужого кабинета, инструменты уровня кабинета проверяют ещё и права кабинета владельца токена: connect_bot требует bots.create, инструменты биллинга: billing.read или billing.write. Scope * прав кабинета не даёт. Если прав нет, инструмент возвращает ошибку permission denied: missing cabinet right (участника в кабинете нет, кабинет доступен только через расшаренного бота) или permission denied: missing cabinet right: <право> (у участника нет конкретного права). Права выдаёт владелец кабинета в карточке «Доступ к кабинету»; сами операции доступа по MCP недоступны.

Подключение к Claude Code / Cursor

Добавьте GetMyBot как удалённый MCP-сервер. Пример конфигурации (mcpServers): подставьте свой домен и токен:

{
  "mcpServers": {
    "mybot": {
      "url": "https://ваш-домен/mcp",
      "headers": {
        "Authorization": "Bearer mbp_ВАШ_ТОКЕН"
      }
    }
  }
}

Claude Code: положите этот блок в .mcp.json проекта или добавьте сервер командой claude mcp add. Cursor: добавьте тот же блок в настройки MCP (Settings → MCP → Add server). После подключения клиент получит список инструментов, ресурсов и промптов автоматически.

Инструменты по доменам

Сервер публикует инструмент на каждую PAT-доступную операцию REST. Покрытие полное, а не выборочное. Ниже: инструмент и требуемый scope. Имена в формате глагол_существительное (snake_case).

Боты (bots)

• list_bots: bots:read
• get_bot: bots:read
• validate_bot_token: bots:write
• connect_bot: bots:write
• update_bot: bots:write
• delete_bot: bots:write
• sync_bot: bots:write
• change_bot_token: bots:write
• transfer_bot: bots:write
• get_bot_settings: settings:read
• update_bot_settings: settings:write (в том числе test_user_ids – тестовые пользователи без списаний)
• get_widget_settings: settings:read
• update_widget_settings: settings:write

get_widget_settings отдаёт бренд/лаунчер/панель/приветствие/пречат/расписание/поведение веб-виджета, его origins, widgetKey и revision. update_widget_settings требует expected_revision из прочитанного снимка и отклоняет сохранение, если ревизия успела сдвинуться. update_bot_settings тоже может целиком переписать widget_experience, но идёт мимо этой валидации, проверки «аватар принадлежит боту» и замка по ревизии — для виджета это не путь.

Каналы и WhatsApp-шаблоны (bots)

Мультиканальность (Telegram + WhatsApp + VK + веб-виджет) доступна и через MCP. Каналы и шаблоны гейтятся общими scope bots:read / bots:write: отдельного channel-scope нет.

• list_channels: bots:read: список каналов бота (platform tg/wa/vk/web, external_id, name, enabled, callback_url).
• connect_channel: bots:write: подключить канал WhatsApp, VK или веб-виджет (platform + creds; для platform: "web" creds не нужны — вместо них обязательный непустой origins).
• delete_channel: bots:write: отключить канал.
• list_wa_templates: bots:read: каталог WhatsApp-шаблонов канала (name, language, status, category, body).
• sync_wa_templates: bots:write: пересинхронизировать каталог шаблонов из Meta.
• create_wa_template: bots:write: создать WhatsApp-шаблон и отправить на модерацию Meta.
• update_wa_template: bots:write: изменить шаблон (в статусах APPROVED/REJECTED/PAUSED).
• delete_wa_template: bots:write: удалить шаблон.

Telegram-каналы подключаются через connect_bot, а не connect_channel: последний рассчитан на wa, vk и web. Категории шаблонов: MARKETING / UTILITY / AUTHENTICATION. create_wa_template сразу отправляет черновик на модерацию Meta; статус меняется асинхронно: читайте его через list_wa_templates (при необходимости обновив каталог sync_wa_templates).

Ответ connect_channel для platform: "web" отличается от остальных платформ: {"widget_key": "…"}, а не {"id": …}. Вызов идемпотентен — повторное подключение того же бота вернёт тот же ключ, а не заведёт второй виджет. Настройка внешнего вида и поведения виджета — отдельная пара get_widget_settings/update_widget_settings выше, а не connect_channel.

Загрузка медиа-заголовка шаблона (изображение/видео/документ) через MCP пока не поддерживается: только через web-интерфейс или REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Реакции (reactions)

• list_reactions: reactions:read
• get_reaction: reactions:read
• create_reaction: reactions:write
• update_reaction: reactions:write
• delete_reaction: reactions:write
• import_reactions: reactions:write
• test_formula: reactions:write: проверить расширенную формулу на примере текста. Поля: bot_id, formula, sample (в REST то же поле называется sample_text). Контекст пустой: ctx и параметры не подставляются, пример текста доступен как {text} / {answer}.
• reorder_reaction: reactions:write
• get_reaction_links: reactions:read
• list_reaction_folders: reactions:read
• create_reaction_folder: reactions:write
• update_reaction_folder: reactions:write
• delete_reaction_folder: reactions:write
• add_reaction_to_folder: reactions:write
• remove_reaction_from_folder: reactions:write
• add_reactions_to_folder: reactions:write

Импорт через import_reactions создаёт реакции, но пропускает медиа: в MCP-контексте нет premium-проверки и Telegram-приёмника для файлов. Если в бандле SamBot есть картинки/видео/документы: используйте полнофункциональный REST-импорт (POST /api/bots/{botID}/reactions/import), он переносит и медиа.

Рассылки (broadcasts)

• start_broadcast: broadcasts:write (опц. paid, опц. сегмент по меткам)
• get_broadcast: broadcasts:write: для рассылок, запущенных из реакции через start_broadcast, отчёт включает blocked – события блокировки, атрибутированные рассылке в течение 24 часов после доставки.
• pause_broadcast: broadcasts:write
• resume_broadcast: broadcasts:write
• cancel_broadcast: broadcasts:write

Метки (labels)

• list_labels: labels:read
• create_label: labels:write
• delete_label: labels:write
• set_label_favorite: labels:write
• assign_user_label: labels:write – назначить метку подписчику (tg_user_id) по каноническому UUID label_id, необязательно на срок ttl_days от 0 до 106751 дня; 0 означает постоянную метку, по истечении срока метка снимается и срабатывает событие «Метка истекла»
• remove_user_label: labels:write – снять метку с подписчика по каноническому UUID label_id

Коллекции и записи (collections)

• list_collections: collections:read
• create_collection: collections:write
• update_collection: collections:write
• delete_collection: collections:write
• list_records: collections:read
• create_record: collections:write
• update_record: collections:write
• delete_record: collections:write

Сценарии (flows)

• list_flows: flows:read
• get_flow: flows:read
• create_flow: flows:write
• update_flow: flows:write
• delete_flow: flows:write

Интеграции, подключения, доступы (integrations)

• list_integrations: integrations:read
• get_integration_sheets: integrations:read
• get_integration_status: integrations:read
• create_integration: integrations:write
• update_integration: integrations:write
• delete_integration: integrations:write
• rotate_integration_token: integrations:write
• list_connections: integrations:read
• create_connection: integrations:write
• test_connection: integrations:write
• update_connection: integrations:write
• delete_connection: integrations:write
• list_credentials: integrations:read
• create_credential: integrations:write
• update_credential: integrations:write
• delete_credential: integrations:write

CRM (crm): только чтение

У CRM-подключений своя пара скоупов, и инструментами опубликованы только чтения. Подключение, синхронизация, повтор задачи и разрешение конфликта остаются только в REST, поэтому агент может наблюдать за CRM-интеграцией, но не может менять её поведение. Ни один из инструментов никогда не возвращает креды.

• list_crm_connections: crm:read: подключения бота с провайдером, статусом и возможностями.
• get_crm_connection: crm:read: безопасная сводка одного подключения.
• get_crm_mapping: crm:read: текущая ревизия маппинга подключения.
• list_crm_operations: crm:read: последние операции синхронизации, новейшие первыми, при желании в рамках одного подключения.
• get_crm_operation: crm:read: одна операция с её задачами; сырой полезной нагрузки запроса задачи не отдаёт.
• list_crm_conflicts: crm:read: задачи, ждущие ручного разбора конфликта.

Что такое подключение, маппинг и операция: на странице CRM-интеграции.

Браузерный пуш и клиентский SDK (web_push, customer_sdk): только чтение

Обе вертикали опубликованы только на чтение. Включение проекта, ротация ключей VAPID и секрета личности, тестовая отправка и отзыв устройства намеренно остаются только в REST: агент может отчитаться по этим каналам, но не может их изменить или запустить. Ни один инструмент не отдаёт приватный ключ VAPID, адрес пуш-подписки, секрет личности или пуш-токен устройства.

• get_web_push_config: web_push:read: очищенная конфигурация Web Push для бота.
• get_web_push_status: web_push:read: включён ли браузерный пуш.
• get_web_push_report: web_push:read: счётчики подписок и квитанций.
• get_customer_sdk_status: customer_sdk:read: включён ли проект мобильного SDK.
• get_customer_sdk_report: customer_sdk:read: счётчики установок и пуш-токенов.

Что означают эти числа: на страницах «Пуш в браузере» и «Клиентский SDK».

Медиа (media)

• upload_media: media:write
• get_media: media:write
• download_media: media:write: скачать байты медиа-актива в base64 ({mime, size_bytes, data_base64}), например чтобы перезалить его в другого бота через upload_media. Отказывает на активах крупнее 2 MB.

Шаблоны (templates)

• list_templates: templates:read
• delete_template: templates:write
• create_template_from_bot: templates:write
• apply_template: templates:write

Подписчики, чаты, диалоги (subscribers)

• list_subscribers: subscribers:read (пагинация offset/limit, поиск, фильтры по меткам и is_blocked=true|false; каждая строка содержит is_blocked и blocked_at, если подписчик заблокировал бота)
• list_chats: subscribers:read
• list_dialogs: subscribers:read: треды операторского инбокса: подписчик, платформа, превью последнего сообщения, last_seen; keyset-пагинация через cursor/next_cursor.
• read_dialog: subscribers:read: сообщения диалога, старые страницы через before_id; у расшифрованных аудио/видео-сообщений в meta приходят transcript_status/transcript/transcript_error.
• send_dialog_message: subscribers:write: операторская отправка текста подписчику: учитывает 24-часовое окно WhatsApp и маршрутизацию каналов, расход метерится по владельцу токена.
• send_dialog_reaction: subscribers:write: отправить подписчику готовую реакцию бота (как кнопка «отправить реакцию» в операторском чате).
• transcribe_dialog_message: subscribers:write: запустить или получить расшифровку аудио/видео-сообщения. Идемпотентный: первый вызов ставит фоновую задачу ({"status":"pending"}), поллинг повторным вызовом до {"status":"done","text":…}; неудачная расшифровка перезапускается автоматически. Нужна интеграция «Распознавание речи» у бота.

Статистика и аналитика (stats)

• get_stats: stats:read
• get_stats_summary: stats:read
• get_stats_recent: stats:read
• get_stats_log: stats:read
• get_reaction_health: stats:read
• get_analytics: stats:read
• get_analytics_chats: stats:read
• get_funnel: stats:read

Общие эксперименты (experiments)

• list_experiments: experiments:read
• get_experiment: experiments:read
• get_experiment_report: experiments:read

Эти инструменты доступны только для чтения. Они возвращают неизменяемое определение эксперимента или отчёт по одной версии. В отчёте валюты разделены и указана выбранная модель атрибуции; инструменты не создают назначения, не записывают факты, не меняют статус и не выбирают победителя.

{
  "name": "get_experiment_report",
  "arguments": { "bot_id": "<bot-id>", "experiment_id": "<experiment-id>", "version": 2 }
}

Сохранённые воронки событий пока доступны только по REST. Не путайте устаревший get_funnel выше, который возвращает автоматическую воронку статистики, с сохранённым определением воронки или её когортой. Для этих сценариев используйте ограниченные REST-эндпоинты из руководства по воронкам.

Биллинг: чтение (billing)

• get_balance: billing:read
• list_tariffs: billing:read
• get_transactions: billing:read

В чужом кабинете все три требуют права кабинета billing.read, иначе: permission denied: missing cabinet right.

Отправка сообщений

• send_message: broadcasts:write: отправка сообщения от имени бота; расход баланса учитывается автоматически по владельцу токена.

Ресурсы

Помимо инструментов сервер отдаёт ресурсы: их можно читать, чтобы не угадывать структуру:

• mybot://openapi.yaml: полная OpenAPI-спека (та же, что отдаётся по /openapi.yaml).
• mybot://reference: компактный справочник: список инструментов с их scope и конвенции (базовый адрес, пагинация, формат ошибок, лимиты).
• mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection: JSON-схемы конфигов. Самое ценное для корректной генерации реакций (триггер, условия, чаты, действия), сценариев и коллекций.
• mybot://bots: динамический список ваших ботов (быстрый контекст без вызова инструмента).

Промпты

Готовые сценарии (slash-команды у MCP-клиента):

• setup_autoresponder: собрать бота-автоответчик (аргументы: бот, тема/набор вопросов).
• segment_broadcast: рассылка по сегменту меток (аргументы: бот, метки, реакция/текст).
• diagnose_reaction: разобраться, почему реакция не срабатывает (читает реакцию, reaction-health и порядок).
• import_from_sambot: провести импорт бандла SamBot и проверить результат.
• weekly_report: сводка по статистике/аналитике бота за период.

Когда выбирать MCP, а когда REST

• Пишете интеграцию, синхронизацию, скрипт или собственную панель: берите REST.
• Подключаете GetMyBot к ИИ-ассистенту или агенту, который умеет MCP: берите /mcp.

И тот, и другой интерфейс работают под одним токеном и подчиняются одним и тем же правам владельца. Если инструмента под задачу не нашлось: соответствующий REST-эндпоинт всегда есть в интерактивном справочнике.

Rollout-гейты одинаковы на обеих поверхностях. Copilot, Flow Intelligence, Explainable Replay и Vertical Playbooks закрываются fail-closed, если кабинет не включён в rollout.

Customer AI и workflow tools

Mutations попадают в audit с surface MCP и PAT token id. OAuth возвращает browser handoff URL; callback и webhooks не публикуются как tools. Provider keyring, routing и reconciliation не доступны customer agents.

Что дальше

• Скиллы для ИИ-агентов: готовые обёртки GetMyBot для Claude Code и других агентов.
• Авторизация и токены: создать PAT для MCP.
• Быстрый старт API: REST-альтернатива.
• Интерактивный справочник: REST-эндпоинты целиком.