🧪 Решение проблем
Что это. Разбор ошибок Fixorix MCP: что значит ответ сервера, почему инструмента нет в списке, как пройти подтверждение действия и что делать в частых ситуациях.
Когда нужно. Когда ИИ-клиент не подключается, модель жалуется на ошибку инструмента или не видит нужный инструмент.
Ошибки бывают двух видов:
- Ошибки подключения — сервер отказал всему запросу: клиент показывает, что сервер
fixorixне подключился, или пишет HTTP-статус (401,403…). Это проблема ключа, настроек проекта или конфига клиента. - Ошибки инструмента — подключение работает, но конкретный вызов не удался. Модель получает текст, который начинается с кода ошибки:
<код>: <что не так и что делать>. Тексты ошибок сервер отдаёт на английском, как и описания инструментов, — модель пересказывает их на языке разговора. Чаще всего модель исправляется сама — например, берёт правильный идентификатор или сужает запрос.
Ошибки подключения
| Ответ | Что случилось | Что делать |
|---|---|---|
401 unauthorized — «An API key is required: Authorization: Bearer fxr_…» | Ключ не передан или заголовок не в формате Authorization: Bearer <ключ> | Проверьте конфиг клиента и что переменная FIXORIX_API_KEY задана, а клиент перезапущен после этого |
401 сразу после claude mcp add в Windows | Команда выполнена в PowerShell с ${FIXORIX_API_KEY}: это переменная самого PowerShell, а не окружения, и Claude Code сохранил заголовок Authorization: Bearer без ключа | claude mcp remove fixorix, затем команду из блока «Windows PowerShell» в подключении Claude Code — с $env:FIXORIX_API_KEY |
401 invalid_token — «The API key is invalid, revoked or expired» | Ключа с таким секретом нет, он отозван или истёк | Проверьте статус ключа на вкладке «API»; при необходимости выпустите новый |
403 mcp_access_disabled — «Enable MCP access for the key in Project settings → API» | У ключа режим «Без MCP» | Окно «Редактирование API-ключа» → «Доступ через MCP» → «Только чтение» или «Чтение и запись» |
403 mcp_disabled — «External MCP is turned off in this project» | В проекте выключен «Разрешить Fixorix MCP» | Администратор включает его: Настройки → «MCP» → «Подключение», карточка «Доступ» |
403 origin_not_allowed | Запрос пришёл из браузера со страницы стороннего сайта | Подключайтесь из ИИ-клиента, а не из веб-страницы |
404 | Такого адреса нет: опечатка, неизвестный тулсет или больше пяти тулсетов в /x/… | Сверьте адрес с разделом Адреса |
400 invalid_toolsets, 400 invalid_readonly | Неверный заголовок X-MCP-Toolsets или X-MCP-Readonly | Тулсеты — через запятую в одном заголовке; X-MCP-Readonly — true или false |
405 | Клиент обратился не методом POST — например, пытается подключиться по устаревшему транспорту SSE | Выберите в клиенте подключение по HTTP (Streamable HTTP) |
413 | Запрос больше 1 МиБ | Сократите аргументы вызова |
429 rate_limited | Исчерпан общий лимит ключа — 1000 запросов в минуту | Подождите до следующей минуты; не делите ключ ИИ-клиента с интеграциями |
429 too_many_failed_attempts | С вашего адреса было слишком много попыток с неверными ключами | Исправьте ключ в конфиге и повторите через минуту |
503 temporarily_unavailable | Проверить ключ сейчас не удалось | Повторите позже |
Клиент предлагает войти через браузер
Если вместо подключения клиент открывает окно входа (OAuth), значит, он не получил ключ: увидев 401, клиенты пытаются войти через аккаунт. Fixorix MCP пока принимает только API-ключ — проверьте, что ключ передаётся в заголовке Authorization. Из-за этого же пока не подключаются веб-версии Claude.ai и ChatGPT: им нужен вход по OAuth, он появится позже.
Ошибки инструментов
| Код | Что значит | Что делать |
|---|---|---|
invalid_arguments | Аргументы не подходят: лишнее поле, неверный тип, значение вне списка, или Fixorix отклонил значения. Причины unsafe_text и preview_too_large — см. Подтверждения | Модель видит, какое поле не так, и обычно исправляется сама |
forbidden | Не хватает доступа: прав ключа, режима «Чтение и запись», настроек проекта или адреса. Подробность — в тексте ошибки и в поле reason, см. таблицу ниже. С причиной approval_rejected — человек отклонил действие | Сделайте то, что написано в подсказке ошибки |
approval_required | Действие видят клиенты, и его нужно подтвердить в дашборде: ссылка — в тексте ошибки | См. Подтверждения и видимые клиентам действия |
pii_disabled | Инструмент читает персональные данные клиентов, а владелец проекта их не разрешил | Владелец включает их: Настройки → «MCP» → «Подключение», карточка «Доступ» → «Разрешить инструменты с персональными данными», см. Персональные данные |
not_found | Объекта нет — или он из другого проекта | Идентификаторы берите из ответов других инструментов (chats_list, knowledge_search, contacts_search…), а не из памяти модели |
conflict | Объект изменился одновременно с вызовом или такой же вызов ещё выполняется | Прочитайте объект заново и повторите |
rate_limited | Исчерпан лимит: вызовов, изменений или ИИ-анализа | Повторите через указанное в ошибке время |
timeout | Ответа не было вовремя. Исход неизвестен: изменение могло выполниться | Сначала проверьте результат чтением (например, chats_get), потом решайте, повторять ли |
unavailable | Сервис временно недоступен — вызов точно не выполнен — или инструмент выключен на стороне Fixorix | Повторите позже |
auth_expired | Ключ перестал действовать во время работы: его отозвали или истёк срок | Выпустите новый ключ и обновите конфиг клиента |
api_error | Fixorix ответил неожиданно, или ответ слишком большой | Сузьте запрос (фильтры, limit) или повторите позже |
Для разработчиков клиентов
Результат с ошибкой помечен isError: true, а машиночитаемые поля лежат в _meta["fixorix.ru/error"]: code, retryable (имеет ли смысл повтор без изменений), hint, reason, missingScopes (каких прав не хватает ключу), approvalUrl (ссылка на карточку подтверждения у approval_required) и violations (что не так с аргументами у invalid_arguments). Поля structuredContent у ошибки нет.
Подтверждения и видимые клиентам действия
Смена статуса чата, создание и правка статей базы знаний, запуск и остановка ботов и публикация сценариев выполняются только после подтверждения человеком в дашборде, см. Действия, которые видят клиенты. Ответы, которые при этом получает модель:
Код и reason | Что случилось | Что делать |
|---|---|---|
approval_required | Первый вызов: Fixorix ничего не изменил, а создал запрос на подтверждение. Ссылка на карточку — в тексте ошибки и в поле approvalUrl | Откройте ссылку, проверьте блок «Что изменится», нажмите «Разрешить» и попросите модель повторить вызов с теми же аргументами |
approval_required, approval_pending | Модель повторила вызов, а запрос ещё ждёт решения | Решите запрос по той же ссылке, затем повторите вызов |
approval_required, stale_preview | Объект изменился после того, как карточку построили: кто-то сменил статус чата, поправил статью, черновик сценария или состояние бота. Прежнее разрешение сгорело, создан новый запрос со свежей карточкой | Откройте новую ссылку из ошибки, проверьте карточку ещё раз и разрешите заново |
forbidden, approval_rejected | Сотрудник проекта отклонил это действие. 15 минут повтор с теми же аргументами отклоняется сразу | Не повторяйте вызов. Если отказ был ошибкой, через 15 минут повторный вызов создаст новый запрос |
invalid_arguments, unsafe_text | В тексте, который увидят клиенты, есть невидимые или управляющие символы или служебные маркеры. Что именно и в каком поле — в тексте ошибки и в поле violations | Попросите модель убрать перечисленные символы и повторить вызов. Если текст скопирован из документа или веб-страницы, вставьте его как обычный текст. Что разрешено, а что нет, — в разделе Текст, который увидят клиенты |
invalid_arguments, preview_too_large | Изменение не помещается в карточку целиком: строка длиннее 40 000 символов или карточка больше 200 000 символов. Запрос не создан — человек должен видеть всё, что подтверждает | Сократите текст или внесите правку в дашборде |
Пока запрос ждёт решения, ничего не выполняется: модель не может обойти подтверждение повтором или другими аргументами — для других аргументов просто появится новый запрос.
Инструмента нет в списке
Клиент получает только инструменты, доступные ключу прямо сейчас. Чтобы узнать, чего не хватает остальным, попросите модель вызвать project_get_context: в поле unavailable перечислены недоступные инструменты с причиной (reason) и подсказкой. Та же причина приходит в ошибке, если вызвать недоступный инструмент по имени.
reason | Почему инструмента нет | Что сделать |
|---|---|---|
scope_missing | У ключа нет нужных прав — они перечислены в missingScopes | Права выпущенного ключа не меняются: выпустите новый ключ с нужными правами, см. Ключи и права |
key_read_only | Инструмент меняет данные, а у ключа режим «Только чтение» | Переключите «Доступ через MCP» на «Чтение и запись» |
pii_disabled | Инструмент читает персональные данные, а владелец проекта их не разрешил | См. Персональные данные |
toolset_disabled | Тулсет выключен в настройках MCP проекта | Администратор: Настройки → «MCP» → «Подключение», карточка «Доступ» → «Тулсеты» |
project_risk_cap | Инструмент выше «Максимального риска» проекта. По умолчанию риск — «Видимые клиентам действия» и пропускает все инструменты, так что потолок опустил администратор проекта | Администратор поднимает «Максимальный риск»: для приоритета и тегов — до «Обратимые записи», для смены статуса чата, правки базы знаний, ботов и публикации сценариев — до «Видимые клиентам действия» |
endpoint_filter | Его отрезал адрес подключения: /readonly или /x/… без этого тулсета | Поменяйте адрес в конфиге клиента |
feature_unavailable | Инструмент выключен на стороне Fixorix. Все инструменты каталога включены по умолчанию | Напишите в поддержку |
Изменения настроек проекта и режима ключа доходят до сервера MCP за несколько секунд, но клиент может помнить старый список инструментов. Переподключите сервер в клиенте (в Claude Code — /mcp, в редакторах — перезапуск сервера или окна).
Если у клиента подключено много серверов, он может показывать модели не все инструменты. Сузьте набор адресом /x/… — оставьте только нужные тулсеты.
Частые ситуации
| Ситуация | Что проверить |
|---|---|
401, хотя ключ точно верный | Клиент запущен раньше, чем задана переменная FIXORIX_API_KEY, — перезапустите его. Claude Code берёт ключ только в момент claude mcp add: если переменная тогда была пустой, выполните claude mcp remove fixorix и добавьте сервер заново. В PowerShell для Claude Code используйте $env:FIXORIX_API_KEY, а не ${FIXORIX_API_KEY}, см. Подключение |
| Модель не видит переписку и контакты | Нужны права (MESSAGES_READ, USERS_READ) и разрешение владельца на персональные данные |
| Не снимаются теги | Для снятия тегов tags_apply нужен TAGS_DELETE — его нет в пресетах, отметьте вручную при выпуске ключа |
Нет chats_set_priority и tags_apply | Нужны режим «Чтение и запись», права на запись, «Максимальный риск» не ниже «Обратимые записи» и адрес без /readonly |
Нет chats_set_status, knowledge_create_document, knowledge_update_document, bots_set_state, flows_publish | То же, но «Максимальный риск» — «Видимые клиентам действия», а права — свои у каждого инструмента: TECH_SUPPORT_WRITE, KNOWLEDGE_BASE_WRITE, BOTS_MANAGE, FLOWS_WRITE, см. Ключи и права |
Разрешил действие, а модель снова получает approval_required | Разрешение действует на вызов с теми же аргументами, тем же ключом и в течение 15 минут после решения. Если модель поменяла аргументы, повторила позже или объект успел измениться (stale_preview), нужен новый запрос — откройте новую ссылку из ошибки |
| В карточке нет кнопок «Разрешить» и «Отклонить», а вместо них — «Решает …» | Ваша роль ниже нужной инструменту: статус чата разрешает любой участник, базу знаний и ботов — Редактор, публикацию сценария — Администратор. Попросите сотрудника с такой ролью открыть ту же ссылку |
Ответ обрезан (truncated: true) | Ответ длиннее 20 000 символов — сузьте запрос фильтрами или уменьшите limit |
not_found на объект, который точно есть | Модель взяла идентификатор из другого проекта или придумала его — попросите найти объект через список или поиск |
chats_analyze отвечает rate_limited | Исчерпан суточный лимит ИИ-анализа проекта — 300 вызовов, повторите завтра |
| Адрес MCP в браузере открывает страницу, а не ошибку | Так и задумано: браузеру сервер показывает страницу о подключении. ИИ-клиент по тому же адресу получает сервер MCP |
В оглавлении REST API (fixorix://rest-api/operations) нет нужного метода | У ключа нет хотя бы одного из прав метода, у ключа режим «Только чтение» или клиент подключён по адресу с /readonly — тогда в описании только методы чтения. Права выпущенного ключа не меняются: выпустите новый ключ |
Чтение ресурса REST API отвечает temporarily unavailable | Сервер не получил описание REST API. Повторите через минуту — инструменты MCP при этом работают |
Если ошибка не проходит, напишите в поддержку: приложите время вызова, имя инструмента и текст ошибки. Администратор проекта найдёт вызов на вкладке Настройки → «MCP» → «История».
Fixorix MCP · Подключение · Ключи и права · Каталог инструментов · Безопасность и лимиты