MCP-инструменты и права
Обновлено
Как выдаются права
В токене приложения MCP есть блок «Заявки» с шестью группами прав. Каждое право имеет тот же технический идентификатор, что соответствующий инструмент. Идентификаторы групп помогают разработчику ориентироваться в структуре; конкретные действия разрешаются правами инструментов.
| Группа в интерфейсе | Идентификатор | Задачи |
|---|---|---|
| Чтение | requests.read |
Просмотр, поиск, аналитика и выгрузка структуры формы |
| Конструктор форм | requests.forms |
Формы, поля, настройки, загрузка формы и тест уведомлений |
| Статусы заявок | requests.statuses |
Общий справочник статусов |
| Работа с заявками | requests.write |
Создание, правка, комментарии, удаление и CSV |
| Массовые операции | requests.bulk |
Импорт, массовая смена статуса и удаление |
| Контакты | requests.contacts |
Поиск по всей базе контактов |
В списке прав показаны инструменты просмотра заявок и отдельная группа конструктора форм.
Чтение
| Инструмент | Право в интерфейсе | Назначение |
|---|---|---|
requests_get_schema |
Словарь приложения | Типы и роли полей, режимы форм, статусы, описанные ключи настроек |
requests_list_forms |
Список форм | Формы, активность и количество заявок; only_active по умолчанию false |
requests_get_form |
Форма целиком | Поля с идентификаторами и настройки; секреты маскируются |
requests_list_requests |
Список заявок | Фильтры по форме, статусу, контакту и датам; краткое представление |
requests_get_request |
Карточка заявки | Значения полей, роли, параметры, файлы со ссылками и комментарии |
requests_search_requests |
Поиск заявок | По значениям полей и по имени связанного контакта |
requests_get_stats |
Статистика | Итоги, статусы, формы и дни |
requests_get_stats_by_hour |
Статистика по часам | 24 значения за день, включая нулевые часы |
requests_export_form |
Выгрузить форму | Структура без заявок; исключённые настройки перечислены в omitted_settings |
Список и поиск заявок используют limit от 1 до 100, по умолчанию 20, и offset, по умолчанию 0. Полную карточку нужно запрашивать отдельно. Фильтры дат списка принимают YYYY-MM-DD или YYYY-MM-DD HH:MM:SS; дата без времени в date_to включает весь день.
Конструктор форм
| Инструмент | Право в интерфейсе | Назначение |
|---|---|---|
requests_create_form |
Создать форму | Название, описание, режим и порядок; поля добавляются отдельно |
requests_update_form |
Изменить форму | Частичная правка, включая начало и конец приёма заявок |
requests_clone_form |
Скопировать форму | Выключенная копия с полями и настройками, без заявок |
requests_delete_form |
Удалить форму | Вместе с полями, настройками и заявками; требуется подтверждение |
requests_set_form_settings |
Настройки формы | Запись переданных пар «ключ — значение» |
requests_add_field |
Добавить поле | Тип, подпись, обязательность, порядок и настройки |
requests_update_field |
Изменить поле | Частичная правка |
requests_delete_field |
Удалить поле | С подтверждением; значения в старых заявках сохраняются |
requests_sort_fields |
Порядок полей | Полный упорядоченный список идентификаторов |
requests_import_form |
Загрузить форму | Новая выключенная форма из JSON-выгрузки |
requests_test_notification |
Проверить канал уведомлений | Реальная отправка: email, sms, push или telegram; с подтверждением |
Статусы заявок
| Инструмент | Право в интерфейсе | Назначение |
|---|---|---|
requests_create_status |
Создать статус | Новый общий статус с названием и цветом |
requests_update_status_definition |
Изменить статус | Название, цвет и порядок самого статуса во всём приложении |
requests_delete_status |
Удалить статус | С подтверждением; при наличии заявок нужен move_to_status_id. Последний статус удалить нельзя |
Первый статус по порядку считается начальным. При смене порядка меняется и трактовка «новых» заявок в статистике.
Работа с заявками
| Инструмент | Право в интерфейсе | Назначение |
|---|---|---|
requests_create_request |
Создать заявку | Полный конвейер создания; можно передать дату, статус, контакт и файлы |
requests_update_request |
Изменить заявку | Частичная правка, добавление и снятие файлов; снятие требует подтверждения |
requests_update_status |
Изменить статус | Перевод одной заявки в другой статус |
requests_add_comment |
Комментарий к заявке | Комментарий от имени пользователя токена с учётом act_as |
requests_delete_comment |
Удалить комментарий | С подтверждением |
requests_delete_request |
Удалить заявку | Со значениями, параметрами и комментариями; с подтверждением |
requests_export_requests |
Выгрузка в CSV | Текст CSV и признаки полноты выборки; ограничения — в работе с данными |
В группе «Работа с заявками» подпись «Изменить статус» относится к одной заявке. Одноимённое право в группе «Статусы заявок» меняет справочник.
Массовые операции и контакты
| Инструмент | Право в интерфейсе | Назначение |
|---|---|---|
requests_import_requests |
Перенос заявок пачкой | До 50 записей одной формы, с external_id, без уведомлений |
requests_bulk_update_status |
Массовая смена статуса | До 100 идентификаторов, один новый статус, подтверждение |
requests_bulk_delete |
Массовое удаление | До 100 идентификаторов, подтверждение |
requests_search_contacts |
Поиск контактов | Имя, email или телефон; запрос от двух символов, limit от 1 до 50, по умолчанию 20 |
Массовая смена статуса возвращает списки updated, missing и failed. Удаление — deleted и missing. Проверяйте результат по каждой записи.
Доступ к контактам и данным
Для поиска контактов пользователь токена должен иметь полный доступ к «Заявкам» либо доступ к Контактам, CRM или Команде. Одного права requests_search_contacts недостаточно.
Та же проверка прав пользователя применяется к явному contact_id при создании, импорте и привязке существующей заявки. Без неё возвращается forbidden. Отвязка при правке через contact_id: null такой проверки не требует.
Без доступа к контактам номер contact_id остаётся видимым, но блок contact и автор комментария author возвращаются как null. Значения, которые посетитель ввёл в поля заявки, включая имя, email и телефон, остаются данными самой заявки и доступны на чтение. Учитывайте это при выдаче прав.
Подтверждения
Удаление формы, поля, заявки, комментария и статуса, тестовая отправка, массовая смена статуса и массовое удаление требуют confirm: true. При правке заявки подтверждение требуется для снятия файлов.
Без подтверждения возвращается confirm_required. Перед удалением формы ответ содержит число её полей и заявок. Попросите агента показать последствия и дождаться вашего решения. Тестовое сообщение действительно уходит получателям.
Примеры просьб
Покажи заявки формы «Обратный звонок» за сегодня и открой последнюю.
Найди обращения, где в полях встречается указанный мной телефон.
Посчитай заявки за сентябрь по дням и статусам.
Подготовь список заявок для перевода в выбранный статус, покажи его мне.
Скопируй выбранную форму и покажи настройки выключенной копии.MCP также предоставляет агенту материал «Заявки: порядок работы и подводные камни» с идентификатором requests-basics через механизм ресурсов приложения.
В разделе навыков показана памятка о полях формы, ролях и подтверждении операций со ссылками для открытия и копирования.