Интеграции

Инструменты MCP

Обновлено 25 октября 2026

Права токена

В приложении MCP права плагина находятся в группе «Топвизор». Каждый инструмент имеет отдельное право с тем же техническим именем, что и инструмент.

Раздел прав	Техническая группа	Состав
Чтение	`topvisor.read`	19 инструментов чтения и 6 инструментов получения цены
Запись: проекты, регионы, запросы	`topvisor.write`	15 инструментов управления проектом и семантикой
Запись: аудит и расписание	`topvisor.settings`	5 инструментов управления страницами, настройками аудита и расписанием
Платные проверки	`topvisor.paid`	6 инструментов запуска проверок

Можно разрешить добавление запросов и запретить удаление либо оставить только чтение. Разрешение инструмента не отменяет проверки внутри плагина: запись требует подтверждения, платный запуск — разрешения в настройках и подтверждённой цены.

Право на topvisor_schedule_update относится к разделу «Запись: аудит и расписание». Этот инструмент включает будущие списания, поэтому дополнительно проверяет флажок платных проверок, confirm и confirm_price. Отдельного требования права из группы topvisor.paid в его коде нет.

Права токена не заменяют доступ пользователя Топвизора к проектам. Если API не разрешает работу с проектом, плагин возвращает отказ.

Права инструментов Топвизора В токене показаны отдельные группы чтения, платных проверок и записи с инструментами управления проектом и запросами.

Чтение данных

Эти инструменты читают существующие данные и не запускают новые проверки.

Инструмент	Назначение и особенности
`topvisor_bank_balance`	Тариф и сгруппированные итоги операций за всё время. Текущий остаток счёта не возвращается.
`topvisor_bank_log`	Пополнения и списания с назначением и проектом; `view=summary` — суммы по назначениям.
`topvisor_projects_list`	Проекты аккаунта с состоянием съёма. По умолчанию без архивных.
`topvisor_project_searchers_regions`	Поисковики и регионы проекта, включая нужный для позиций `region_index`.
`topvisor_competitors_list`	Конкуренты, добавленные в проект; их идентификаторы используются для чтения позиций конкурентов.
`topvisor_keyword_groups_list`	Группы запросов и число запросов; `include_folders` позволяет получить и папки.
`topvisor_keywords_list`	Запросы, группы и целевые страницы. С `volumes` — собранная частотность; с `relevant_regions` — результат подбора релевантных страниц.
`topvisor_positions_history`	Позиции и релевантные страницы по датам в одном регионе; есть отбор по группам и чтение позиций конкурента. До 31 даты съёма за вызов.
`topvisor_positions_summary`	Сводка между двумя датами: динамика, ТОПы, средняя позиция и видимость.
`topvisor_positions_summary_chart`	Ряд показателей по датам съёма в одном регионе, до 31 точки.
`topvisor_snapshots_history`	Сохранённые снимки выдачи в регионе. По умолчанию ТОП-10 и до 20 запросов; сниппеты включаются отдельно.
`topvisor_snapshots_competitors`	Домены из снимков и `count_urls` по датам. Сортировка — по числу URL на последнюю дату. Средней позиции и видимости в этом ответе нет.
`topvisor_audit_indexing`	Существующие результаты индексации страниц в Яндексе, Google или Bing.
`topvisor_audit_watcher`	Изменения Радара: `view=summary` — счётчики, `view=changes` — страницы. `with_diff` запрашивает прежнее и новое значение. Нужны минимум две проверки.
`topvisor_audit_check_status`	Ход позиций, частотности, релевантных страниц, кластеризации, индексации, Радара или карты сайта. Подбор запросов выполняется синхронно и здесь не отслеживается.
`topvisor_regions_search`	Поиск региона по названию; возвращает `region_key` для добавления региона и других операций.
`topvisor_audit_pages_list`	Страницы проекта и участие в индексации, Радаре, анализе и карте сайта.
`topvisor_audit_settings_get`	Поисковики индексации, типы отслеживания Радара, регулярное выражение и User-Agent.
`topvisor_schedule_get`	Настроенные автозапуски позиций, частотности, индексации и Радара.

Ещё шесть читающих инструментов получают стоимость. Они перечислены вместе с парными инструментами запуска в статье «Проверки и расписание».

Изменение проектов и семантики

Инструмент	Что меняет
`topvisor_project_create`	Создаёт проект по адресу сайта. Регионы, запросы и проверки добавляются отдельно.
`topvisor_project_update`	Имя, архив и параметры съёма: снимки, сниппеты, поддомены, фильтр выдачи, исправление опечаток.
`topvisor_project_delete`	Удаляет проект с историей позиций и другими данными без возврата.
`topvisor_competitors_create`	Добавляет сайты конкурентов. Состав конкурентов влияет на стоимость последующих съёмов.
`topvisor_competitors_update`	Включает или выключает конкурентов.
`topvisor_competitors_delete`	Удаляет конкурентов без возврата. Для временного исключения используйте выключение.
`topvisor_searchers_regions_create`	Добавляет регион по `region_key`; при необходимости создаёт поисковик в проекте. Возвращает регион с его `region_index`.
`topvisor_searchers_regions_update`	Включает или выключает регион либо поисковик; меняет устройство, глубину и язык региона.
`topvisor_searchers_regions_delete`	Удаляет регион или поисковик. Для временного исключения используйте выключение.
`topvisor_keyword_groups_create`	Создаёт группы запросов в папке проекта.
`topvisor_keyword_groups_update`	Имя, включение, папка или восстановление группы из корзины через `restore=true`.
`topvisor_keyword_groups_delete`	Удаляет группы вместе с запросами. В описании инструмента указан срок корзины Топвизора — 3 дня.
`topvisor_keywords_create`	Добавляет до 1000 запросов за вызов: строки или объекты с `name`, `group_name`, `target_url`. Использует существующую группу по `group_id` либо группу по имени. Отсеивает дубли.
`topvisor_keywords_update`	Текст одного запроса, целевая страница, перенос в группу и восстановление из корзины. При переименовании возвращается новый `keyword_id`.
`topvisor_keywords_delete`	Удаляет запросы. Для восстановления в пределах корзины используется `topvisor_keywords_update` с `restore=true`.

Для записи в существующий проект project_id нужно передать явно. Проект по умолчанию не подставляется. Создание нового проекта принимает адрес сайта, поскольку идентификатора у него ещё нет.

Подтверждение изменений

Агент вызывает инструмент без confirm=true.
Если есть изменения для согласования, инструмент возвращает ok: false, error_code: confirm_required и поле preview на верхнем уровне ответа. Для подготовки предпросмотра возможны читающие запросы к API; изменения не отправляются.
Агент объясняет, что изменится и каковы последствия.
После вашего согласия он повторяет вызов с confirm=true.
Если изменение состоит из нескольких шагов и часть не выполнена, агент проверяет фактическое состояние перед исправлением.

confirm_required — ожидаемый запрос подтверждения. Если объект уже в нужном состоянии, вместо предпросмотра возможен nothing_to_change.

Архивирование проекта задаётся archived=true. Запись снимков — do_snapshots=true, сниппетов — with_snippets=true; включение этих параметров влияет на цену будущих съёмов. После изменения состава проекта или параметров проверки цену нужно получать заново.

Изменение аудита и расписания

Инструмент	Что меняет
`topvisor_audit_pages_create`	Добавляет до 500 полных адресов за вызов либо импортирует карту через `sitemap_url`. Флаги `indexing`, `watcher`, `audit` включают нужные виды проверки.
`topvisor_audit_pages_update`	Включает или выключает уже имеющиеся страницы в проверках по идентификаторам, адресам либо все сразу.
`topvisor_audit_settings_update`	Поисковики индексации (`yandex`, `google`, `bing`), типы Радара (`title`, `description`, `h1`, `content`), регулярное выражение, User-Agent, предел редиректов и обработку JavaScript.
`topvisor_schedule_update`	Включает или меняет автозапуск. Нужны `confirm=true` и подтверждённая цена одного запуска; до включения возвращает оценку расходов.
`topvisor_schedule_delete`	Выключает автозапуск выбранного вида проверки. Требует подтверждения записи; флажок платных проверок включать не нужно.

Адреса страниц для добавления должны относиться к сайту проекта или его поддоменам. Если страницы уже существуют, включайте их через topvisor_audit_pages_update.

В watcher_regexp допустимо до 500 символов и ровно одна захватывающая группа. Например, price: (\d+). Плагин проверяет регулярное выражение перед отправкой.

Идентификаторы и чтение результатов

project_id берите из topvisor_projects_list.
region_index берите из topvisor_project_searchers_regions. Это индекс региона внутри конкретного проекта.
region_key берите из topvisor_regions_search. Он нужен, например, при добавлении региона, для частотности и кластеризации. Подставлять его вместо region_index нельзя.
competitor_id, идентификаторы групп и запросов берите из соответствующих списков.
В истории меньшая позиция лучше. Значение null означает отсутствие позиции в отслеживаемой глубине выдачи.
Даты относятся к фактическим съёмам. Длинный период с большим числом съёмов разбивайте на части, чтобы учесть ограничение 31 даты.
У списков с постраничностью учитывайте next_offset; неполный ответ не следует считать полным списком.

Плагин также регистрирует справочные материалы для агента: «Топвизор: сценарии и подводные камни» и «Топвизор: SEO-сценарии». Их получение зависит от возможностей MCP-клиента.

Примеры просьб к агенту

Покажи проекты Топвизора, затем регионы выбранного проекта с region_index.
Сравни позиции сайта за две доступные даты в нужном регионе.

Покажи домены из снимков выдачи и число URL каждого домена.
Отдельно перечисли конкурентов, которые добавлены в проект.

Подготовь добавление моих запросов в группу «Каталог» выбранного проекта.
Покажи дубли и список изменений. Записывай только после моего подтверждения.

Покажи страницы с изменениями title и H1 по данным Радара.
Если проверок недостаточно, объясни, каких данных не хватает.

Проверь расписание проекта. Подготовь выключение ненужного автозапуска
и покажи мне изменения до сохранения.

Пример сравнения позиций сайта В ответе показаны позиции запросов за две даты, сдвиг и страницы сайта.

Пример просмотра поисковой выдачи В таблице выдачи показаны домены, страницы, отметки конкурентов и положение сайта на девятом месте.