🔑 Ключи и права для MCP
Что это. Как устроен доступ ИИ-клиента: режим «Доступ через MCP» у API-ключа, пресеты прав для ИИ-клиентов и соответствие «инструмент → права».
Когда нужно. Когда вы выпускаете ключ для ИИ-клиента и решаете, что модели можно, а что нет.
Через MCP полномочия ключа получает модель, а моделью управляет текст: ваш запрос, но и переписка клиентов, документы базы знаний, ответы внешних систем. Это другой риск, чем у REST-интеграции, которая делает ровно то, что написано в коде. Поэтому ключ не становится MCP-ключом сам — это отдельное решение администратора.
Режим «Доступ через MCP»
У каждого API-ключа есть режим «Доступ через MCP»:
| Режим | Что можно ИИ-клиенту |
|---|---|
| «Без MCP» | Ничего: ключ работает только с REST API, ИИ-клиент получает 403 mcp_access_disabled. Такой режим у всех ключей, выпущенных до появления MCP, и у новых ключей без переключателя «Для ИИ-клиента (MCP)» |
| «Только чтение» | Только инструменты чтения |
| «Чтение и запись» | Ещё и изменения в пределах прав ключа и настроек MCP проекта: приоритет чата (chats_set_priority) и теги чата (tags_apply), а также действия, которые видят клиенты, — статус чата, статьи базы знаний, запуск и остановка ботов, публикация сценариев. Каждое такое действие выполняется только после подтверждения человеком в дашборде |
Режим задаётся при создании ключа переключателем «Для ИИ-клиента (MCP)» и пресетом, а у выпущенного ключа меняется в окне «Редактирование API-ключа» — в отличие от прав (scopes), которые после выпуска не меняются. В списке ключей у таких ключей есть бейдж «MCP: чтение» или «MCP: запись».
Режим действует только на инструменты MCP. В REST API ключ работает по своим правам (scopes) при любом режиме, и модель знает об этом из описания REST API, которое отдаёт Fixorix MCP, см. REST API тем же ключом. Поэтому режим «Только чтение» не мешает модели писать через REST API, если у ключа есть права на запись: ограничивайте ключ ИИ-клиента правами, а не только режимом.
Режим не расширяет права: запись работает, только если у ключа есть и права на запись (TECH_SUPPORT_WRITE, TAGS_WRITE, KNOWLEDGE_BASE_WRITE, BOTS_MANAGE, FLOWS_WRITE — смотря что нужно), и проект разрешает записи: «Максимальный риск» не ниже «Обратимые записи», а для действий, которые видят клиенты, — «Видимые клиентам действия» (это значение по умолчанию).
Пресеты
При включённом переключателе «Для ИИ-клиента (MCP)» в окне «Создание API-ключа» появляется выбор «Пресет». Пресет отмечает права в матрице и выбирает режим — дальше матрицу можно поправить вручную.
| Пресет | Режим | Права | Отдельные галочки в блоке «Дополнительно» |
|---|---|---|---|
| «ИИ-клиент: только чтение» | «Только чтение» | TECH_SUPPORT_READ, MESSAGES_READ, KNOWLEDGE_BASE_READ, BOTS_READ, WIDGETS_READ, FLOWS_READ, TAGS_READ | «Контакты» (USERS_READ) |
| «ИИ-клиент: оператор» | «Чтение и запись» | Всё из «только чтение» и TECH_SUPPORT_WRITE, TAGS_WRITE, KNOWLEDGE_BASE_WRITE | «Контакты» (USERS_READ), «Управление ботами» (BOTS_MANAGE), «Запись сценариев» (FLOWS_WRITE) |
Галочки вынесены отдельно, потому что через REST API эти права дают больше, чем нужно инструментам MCP:
| Галочка | Что даёт инструментам MCP | Что ещё даёт тот же ключ через REST |
|---|---|---|
«Контакты» (USERS_READ) | Поиск и профили клиентов (contacts_search, contacts_get) — персональные данные | Чтение участников проекта |
«Управление ботами» (BOTS_MANAGE) | Запуск и остановка ботов (bots_set_state) — каждый раз после подтверждения человеком в дашборде | Запуск, остановка и настройка ботов — без подтверждения |
«Запись сценариев» (FLOWS_WRITE) | Публикация черновика сценария (flows_publish) — каждый раз после подтверждения человеком в дашборде | Архивирование сценариев и отмена запусков — без подтверждения |
KNOWLEDGE_BASE_WRITE из пресета «оператор» нужен инструментам knowledge_create_document и knowledge_update_document — создание и правка статей базы знаний, а TECH_SUPPORT_WRITE — ещё и смене статуса чата (chats_set_status). По статьям базы знаний боты отвечают клиентам, а статус чата клиент может увидеть в уведомлении, поэтому эти инструменты, как и запуск ботов и публикация сценариев, выполняются только после подтверждения человеком в дашборде и только если «Максимальный риск» проекта — «Видимые клиентам действия».
Под пресетом окно показывает блок «Какие инструменты будут доступны» — «Доступно N из M» по отмеченным правам — и предупреждение о персональных данных, если владелец проекта их ещё не разрешил.
Чего нет ни в одном пресете
Эти права окно создания ключа помечает предупреждением «Эти права опасны для ИИ-клиента и не входят в пресеты», если отметить их вручную:
| Права | Почему не для ИИ-клиента |
|---|---|
USERS_WRITE, USERS_DELETE, USERS_MANAGE | Через REST это права уровня администратора: роли участников, приглашения, удаление участников |
SETTINGS_* | Настройки проекта |
Любые *_DELETE, включая TAGS_DELETE | Удаление данных |
AI_WRITE | Запись в векторное хранилище мимо базы знаний |
METRICS_WRITE | Правка дашбордов аналитики |
Инструментам MCP ни одно из этих прав не нужно. Исключение — TAGS_DELETE: с ним tags_apply не только вешает теги, но и снимает их. Если это нужно, отметьте право вручную — осознанно.
Какие права нужны инструментам
Инструмент виден клиенту, только если у ключа есть все его обязательные права. Без дополнительных инструмент работает, но пропускает часть ответа и пишет причину в поле notes.
| Инструмент | Обязательные права | Дополнительно | Режим «Доступ через MCP» | Подтверждение |
|---|---|---|---|---|
project_get_context | — | USERS_READ | «Только чтение» или «Чтение и запись» | — |
project_digest | — | BOTS_READ, FLOWS_READ, TECH_SUPPORT_READ | «Только чтение» или «Чтение и запись» | — |
chats_list | TECH_SUPPORT_READ | — | «Только чтение» или «Чтение и запись» | — |
chats_get | TECH_SUPPORT_READ | FLOWS_READ, TAGS_READ | «Только чтение» или «Чтение и запись» | — |
chats_get_transcript | MESSAGES_READ, TECH_SUPPORT_READ | — | «Только чтение» или «Чтение и запись» | — |
chats_analyze | TECH_SUPPORT_READ | — | «Только чтение» или «Чтение и запись» | — |
templates_list | TECH_SUPPORT_READ | — | «Только чтение» или «Чтение и запись» | — |
chats_set_priority | TECH_SUPPORT_READ, TECH_SUPPORT_WRITE | — | только «Чтение и запись» | — |
chats_set_status | TECH_SUPPORT_READ, TECH_SUPPORT_WRITE | — | только «Чтение и запись» | Любой участник проекта |
knowledge_search | KNOWLEDGE_BASE_READ | — | «Только чтение» или «Чтение и запись» | — |
knowledge_browse | KNOWLEDGE_BASE_READ | — | «Только чтение» или «Чтение и запись» | — |
knowledge_get_document | KNOWLEDGE_BASE_READ | — | «Только чтение» или «Чтение и запись» | — |
knowledge_create_document | KNOWLEDGE_BASE_READ, KNOWLEDGE_BASE_WRITE | — | только «Чтение и запись» | Редактор |
knowledge_update_document | KNOWLEDGE_BASE_READ, KNOWLEDGE_BASE_WRITE | — | только «Чтение и запись» | Редактор |
channels_list | BOTS_READ | WIDGETS_READ | «Только чтение» или «Чтение и запись» | — |
bots_diagnose | BOTS_READ | — | «Только чтение» или «Чтение и запись» | — |
bots_set_state | BOTS_MANAGE, BOTS_READ | — | только «Чтение и запись» | Редактор |
flows_list | FLOWS_READ | — | «Только чтение» или «Чтение и запись» | — |
flows_get | FLOWS_READ | — | «Только чтение» или «Чтение и запись» | — |
flows_list_runs | FLOWS_READ | — | «Только чтение» или «Чтение и запись» | — |
flows_get_run | FLOWS_READ | — | «Только чтение» или «Чтение и запись» | — |
flows_publish | FLOWS_READ, FLOWS_WRITE | — | только «Чтение и запись» | Администратор |
contacts_search | USERS_READ | — | «Только чтение» или «Чтение и запись» | — |
contacts_get | USERS_READ | TECH_SUPPORT_READ | «Только чтение» или «Чтение и запись» | — |
tags_list | TAGS_READ | — | «Только чтение» или «Чтение и запись» | — |
tags_apply | TAGS_READ, TAGS_WRITE, TECH_SUPPORT_READ | TAGS_DELETE | только «Чтение и запись» | — |
Если в колонке «Подтверждение» указана роль, это действие, которое видят клиенты: кроме прав нужен «Максимальный риск» проекта «Видимые клиентам действия», а выполняется оно только после подтверждения человеком в дашборде. Роль — минимальная, с которой сотрудник проекта может разрешить действие.
Инструменты с персональными данными — chats_get_transcript, chats_analyze, flows_get_run, contacts_search, contacts_get — кроме прав требуют разрешения владельца проекта, см. Персональные данные. Описания и аргументы всех инструментов — в каталоге.
Один ключ — один клиент
- Отдельный ключ на каждого человека и каждый клиент. История вызовов MCP (Настройки → «MCP» → «История») показывает, каким ключом сделан вызов, — с отдельными ключами по нему видно, кто что делал. Ключ, который ушёл не туда, отзывается без последствий для остальных.
- Не используйте для MCP ключ рабочей интеграции. У ключа общий лимит — 1000 запросов в минуту, и ИИ-клиент, который активно читает данные, будет съедать его у интеграции. К тому же у интеграции обычно больше прав, чем нужно модели.
- Начинайте с «только чтение». Режим всегда можно поднять до «Чтение и запись» в окне редактирования ключа, не выпуская новый ключ.
- Задайте срок действия ключу, который выдаёте на время: например, на эксперимент или подрядчику.
Кто что может
| Действие | Минимальная роль |
|---|---|
| Создать ключ с пресетом MCP, изменить «Доступ через MCP», отозвать ключ | Администратор |
| Изменить права (scopes) выпущенного ключа | Никто — только выпуск нового ключа |
Fixorix MCP · Подключение · Каталог инструментов · Scopes · REST API