MCP-инструменты и права
Обновлено
Доступ к инструментам
Плагин регистрирует инструменты в сервере приложения MCP. Раздел прав называется VK Реклама. Каждому инструменту соответствует отдельное право с тем же техническим именем; права объединены в девять групп с названиями ниже.
При выдаче токена MCP разрешите необходимые действия. Право Лиды из лид-форм находится в группе Кабинет и статистика, но возвращает персональные данные — учитывайте его отдельно при выборе доступа.
Права MCP разрешают вызов инструмента, а доступ API VK определяет, какие кабинеты и операции доступны подключённым реквизитам. Одно не заменяет другое.
В списке прав отдельно показаны чтение статистики, аудитории, справочники и группы изменения рекламы.
Кабинет и статистика
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_get_account |
Кабинет VK Рекламы | Проверка подключения, сведения кабинета, баланс, валюта и шаг бюджета |
vkads_get_rate_limits |
Лимиты запросов | Лимиты API и доступные остатки запросов |
vkads_get_notifications |
Уведомления кабинета | Сообщения, предупреждения и ограничения VK |
vkads_get_campaigns |
Кампании | Кампании со статусами, бюджетами и стратегией |
vkads_get_adgroups |
Группы объявлений | Группы по campaign_id или своим ids, бюджеты, ставки и стратегия |
vkads_get_ads |
Объявления | Объявления по adgroup_ids или ids, модерация, ссылки и тексты |
vkads_get_stats |
Статистика | Итоговые и дневные показатели за период |
vkads_get_goal_stats |
Конверсии по целям | Конверсии по каждой цели пикселя |
vkads_get_today_spend |
Расход сегодня | Итог сегодня и доступные оперативные показатели |
vkads_get_top_objects |
Топ объектов | Рейтинг кампаний, групп или объявлений по метрике |
vkads_get_leads |
Лиды из лид-форм | Заявки либо список форм при view=forms |
vkads_get_agency_clients |
Клиенты агентства | Список клиентов агентства или менеджера |
Аудитории и пиксели
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_get_pixels |
Пиксели | Счётчики кабинета; with_goals=true добавляет цели, максимум у десяти счётчиков за вызов |
vkads_get_audiences |
Аудитории | Один вид аудитории за вызов: segments, users_lists, vk_groups или pricelists |
Справочники
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_find_regions |
Поиск регионов | Поиск по query, расшифровка ids или дочерние регионы по parent_id |
vkads_get_interests |
Интересы | Дерево интересов с поиском |
vkads_get_packages |
Пакеты размещения | Доступные пакеты, цели и модели оплаты; по умолчанию только пригодные для создания кампании |
Данные маркировки (ОРД)
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_get_ord_profile |
Данные маркировки | Прочитать данные рекламодателя и проверить заполненность названия |
vkads_set_ord_profile |
Запись данных маркировки | Записать name, site, phone с подтверждением; ИНН не меняет |
Запуск и остановка показов
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_set_campaign_status |
Запуск и остановка кампаний | Статусы кампаний из campaign_ids |
vkads_set_adgroup_status |
Запуск и остановка групп | Статусы групп из adgroup_ids |
vkads_set_ad_status |
Запуск и остановка объявлений | Статусы объявлений из ad_ids |
Эти инструменты принимают status=active для запуска и status=blocked для остановки, до 20 объектов за вызов. Удаление выполняется отдельным инструментом.
Бюджеты и ставки
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_set_budget |
Бюджеты | Изменить дневной или общий бюджет: level=campaign либо adgroup, номер в id |
vkads_set_bid |
Ставки | Изменить ставку или предельную цену по adgroup_id; сумма в аргументе price |
Создание кампаний и объявлений
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_upload_image |
Загрузка картинок | Загрузить JPG/PNG из image_url либо image_base64, получить номер для объявления; без confirm |
vkads_create_campaign |
Создание кампаний | Создать остановленную кампанию с одной группой, без объявлений |
vkads_create_adgroup |
Создание групп | Создать остановленную группу в кампании campaign_id |
vkads_create_ad |
Создание объявлений | Создать остановленное объявление в группе adgroup_id |
Правка кампаний и объявлений
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_update_campaign |
Правка кампаний | Изменить название и даты кампании по id |
vkads_update_adgroup |
Правка групп | Изменить название и таргетинг группы по id |
vkads_update_ad |
Правка объявлений | Изменить название, тексты, ссылку и картинки объявления по id |
Удаление
| Инструмент | Название права | Назначение |
|---|---|---|
vkads_delete_objects |
Удаление | Безвозвратно удалить до 20 объектов уровня level по ids, с confirm=true и фразой confirm_text |
Примеры просьб агенту
Покажи кампании VK Рекламы и расход за последние семь завершившихся дней.
Сведи результат в таблицу. Ничего не меняй.Покажи уведомления кабинета VK Рекламы, затем объявления с причинами
отклонения на модерации. Объясни, что мешает показам.Покажи пиксели нашего домена и их цели. Отдельно покажи конверсии
после клика за согласованный период.Найди пакеты для рекламы сайта и регион Казань. Подготовь предпросмотр
кампании с одной группой. Бюджет и тексты сначала согласуй со мной.Подготовь остановку выбранных кампаний. Покажи номера, названия
и изменение статусов, затем дождись моего подтверждения.Плагин также регистрирует памятку VK Реклама: сценарии и подводные камни с идентификатором vkads-basics. Её доступность в клиенте зависит от поддержки документации приложением MCP и клиентом.
На условных данных агент показывает статусы кампаний, показы, клики и расход за неделю.
Что учитывать разработчику
Аргументы инструментов передаются объектом согласно их MCP-схемам. Названия параметров не унифицированы: например, создание объявления использует adgroup_id, а его правка — id. Используйте схему конкретного инструмента.
Для списков с limit и offset стандартный размер страницы — 50, максимальный — 50; у отдельных справочников свои значения по умолчанию. Поиск сообществ и прайс-листов в vkads_get_audiences выполняется только внутри полученной страницы. Для полного поиска нужно обходить страницы.
В списках рекламных объектов по умолчанию выбираются активные и остановленные объекты; для удалённых используется statuses. У текстов в vkads_get_ads есть ограничение выдачи до 300 символов.
При штатном выполнении ответ содержит ok=true. Контролируемые ошибки содержат ok=false, error_code, error_message; предпросмотр также возвращается как confirm_required с preview, а не как выполненная операция. Читайте warnings и результаты по каждому объекту: успешная обработка запроса не гарантирует применения всех изменений.