Ошибки подключения MCP

Начните с трёх проверок: правильный ли адрес скопирован из Napulse, тот ли проект выбран при подключении и есть ли нужное действие в tools/list.

Подключение и HTTPПодключение и HTTP

Инструменты и данныеИнструменты и данные

Ошибки действий могут приходить при HTTP 200 внутри result.isError: true. Причина находится в result.content[].text; также проверяйте JSON-RPC error.

Лимиты по умолчанию — на каждый ключ или вход через браузер, два отдельных бюджета:

• чтение — пополнение 120 вызовов в минуту, кратковременный запас 30;
• изменения (инструменты, которые что-то меняют или отправляют) — 30 вызовов в минуту, запас 10.

Исчерпанные изменения не мешают чтению. Массовый инструмент считается одним вызовом: порции, которыми CRM обрабатывает диалоги внутри, бюджет не тратят. Администратор установки может изменить значения переменными MCP_RATE_LIMIT_READ_PER_MINUTE и MCP_RATE_LIMIT_READ_BURST (чтение), MCP_RATE_LIMIT_PER_MINUTE и MCP_RATE_LIMIT_BURST (изменения). Проверки инициализации и каталога не являются вызовами бизнес-инструментов.

Подключения и журнал на странице MCPПодключения и журнал на странице MCP

Список подключений и журнал вызовов — на странице Интеграции → MCP (или API), блок «Подключения и журнал». Подробнее — в разделе «Где видно подключения».

Запрос отправки завис или вернулся с предупреждениемЗапрос отправки завис или вернулся с предупреждением

1. Не повторяйте отправку автоматически.
2. Если в ответе есть delivery: "sent", провайдер подтвердил отправку. Предупреждение может относиться к дальнейшему сохранению результата в CRM.
3. Проверьте историю выбранного диалога и фактическую доставку доступным способом.
4. Повторяйте действие только после выяснения, было ли оно выполнено.

Аналогичный подход нужен после тайм-аута создания статьи, приглашения, задачи или запуска рассылки. Одинаковый JSON-RPC id служит сопоставлению ответа и запроса, а не гарантией защиты от повторного выполнения.

Ошибки OAuthОшибки OAuth

• Запрос согласия истёк: начните подключение заново во внешнем приложении.
• Адрес возврата не совпадает: разработчик клиента должен использовать точно зарегистрированный redirect URI.
• 503 temporarily_unavailable на обновлении токена без заголовка Retry-After: MCP выключен в проекте или на платформе. Подключение не удаляется; после включения MCP приложение продолжит работу само.
• invalid_grant: код или refresh token могли истечь, быть уже использованы или отозваны. Для пользователя решение — повторное подключение; для разработчика — проверка PKCE и ротации токенов.
• invalid_target: значение OAuth resource должно соответствовать адресу подключаемого /mcp.
• invalid_scope на обновлении токена: приложение попросило разрешение, которого не было в подключении, или у сотрудника не осталось ни одного из разрешений этого подключения. Если у сотрудника просто стало меньше прав, обновление проходит: новый токен получает только оставшиеся разрешения (поле scope в ответе), подключение продолжает работать. Если пропали все разрешения подключения, подключите ИИ заново с другими разрешениями или верните сотруднику права.
• После обновления токена нельзя повторно использовать старый refresh token: это отзывает семейство подключения.

Лимиты OAuth (HTTP 429)Лимиты OAuth (HTTP 429)

Адреса подключения (register, authorize, token, revoke) открыты без входа, поэтому у них есть лимиты. Решение на экране согласия (consent) требует входа в CRM и считается по сотруднику. Они считаются для каждого клиента отдельно: один чужой адрес или одна чужая сеть IPv6 не может закрыть подключение остальным. Поверх них есть общие потолки на всю установку, которые защищают базу от атаки с многих адресов сразу.

Обычное подключение обновляет токен примерно 12 раз в час (токен действует 5 минут), то есть расходует 2% своего лимита.

Лимит подключения (token:client в журнале сервера) расходуют только успешные обмен кода и обновление токена. client_id не секрет: ИИ-приложение отправляет его в каждом запросе. Неудачные попытки (чужой или выдуманный refresh token, неверный код) этот лимит не расходуют. Поэтому посторонний, узнавший client_id, не может заблокировать обновление токена чужому подключению.

Неудачные попытки с ответом 4xx считаются отдельно, по паре «подключение + адрес» (token:client-address-failures в журнале сервера, 600 в час). Пример: после отзыва ключа ИИ-клиент раз за разом шлёт мёртвый refresh token. После 600 неудач он получает 429 до конца часа, и дальше его попытки не расходуют лимит адреса. Остальные подключения того же облачного ИИ-приложения за тем же общим адресом продолжают работать. Посторонний, который повторяет чужой client_id со своего адреса, расходует только эту пару для своего адреса. Ошибки сервера (500, 503) не считаются. Перебор токенов с разными client_id упирается в лимит своего адреса. Отзыв (revoke) лимиты подключения не расходует и ими не ограничивается.

Лимит экрана согласия (consent:user) считается по сотруднику, а не по адресу: коллеги за одним офисным NAT его не делят. Запросы с чужой страницы (другой Origin) отклоняются раньше и лимит не расходуют. Экран показывает «Слишком много попыток подключения за последний час».

Облачные ИИ-приложения ходят к Napulse за всеми своими пользователями с нескольких общих адресов. Если один их пользователь подключает Napulse больше 100 раз за час, новые подключения остальных пользователей этого приложения с того же адреса получают 429 до конца часа (register:ip в журнале сервера). Уже подключённые продолжают работать.

Ответ при превышении: HTTP 429, тело {"error":"temporarily_unavailable"}, заголовок Retry-After — через сколько секунд счётчик обнулится (не больше часа). Что делать:

• Пользователю: подождите указанное время и подключитесь заново. Не нажимайте «Подключить» и «Разрешить подключение» много раз подряд: каждая попытка расходует лимит.
• Разработчику клиента: соблюдайте Retry-After, не повторяйте запрос в цикле, обновляйте токен только когда он истёк.
• Администратору: если 429 одновременно получают все клиенты, посмотрите в журнале сервера строки MCP OAuth rate limit reached: <лимит>. Лимит с окончанием :global (register:global, authorize:global, token:global) — сработал общий потолок: идёт атака с десятков адресов или сетей сразу, и этот шаг подключения закрыт для всех до конца часа или до перезапуска сервера. Лимит с окончанием :net48 — много запросов из одной сети IPv6 /48; он закрывает только эту сеть, остальные клиенты работают. token:client закрывает одно подключение, которое за час получило 600 токенов (зацикленный клиент); token:client-address-failures закрывает одно подключение с одного адреса после 600 неудачных попыток за час (клиент повторяет мёртвый refresh token: переподключите ИИ-приложение); consent:user — одного сотрудника. Если в строках только лимиты :ip, значит сервер не видит настоящие адреса. Проверьте переменную MCP_TRUSTED_PROXY_CIDRS: адрес обратного прокси (kamal-proxy) должен входить в список доверенных. Если переменная не задана, доверенными считаются локальные и частные сети. Строка MCP_TRUSTED_PROXY_CIDRS: ignored invalid entries в журнале означает опечатку в списке.

Счётчики хранятся в памяти процесса и обнуляются при перезапуске сервера.

Не путайте с ошибкой rate_limited в ответе инструмента: это отдельный лимит на частоту вызовов инструментов (см. таблицу выше).

Мониторинг отказов (для администратора платформы)Мониторинг отказов (для администратора платформы)

Отказы подключений ИИ видны в трёх местах. Журнал MCP (mcp_audit_log) пишет только запросы действующих подключений, а мониторинг считает все отказы: запросы без ключа, с отозванным ключом, с чужого сайта, с истёкшей сессией, ошибки OAuth.

Карточка. Админка → Мониторинг → «MCP: отказы за час / сутки». Видна только администратору платформы. На ней:

• число отказов за час и за сутки;
• причины за выбранное окно («Час» или «Сутки»): где отказали, причина, HTTP-статус, количество;
• последние 20 отказов: время (UTC), причина, инструмент или шаблон маршрута;
• сводка журнала MCP за сутки: сколько вызовов, сколько отказов, частые отказы (инструмент или маршрут и код ошибки) и проекты с отказами.

Счётчики живут в памяти процесса CRM и обнуляются при перезапуске и деплое (время начала подсчёта написано в карточке). Долгую историю смотрите в Grafana (ниже). Данные карточки отдаёт GET /api/admin/mcp/ops?windowMinutes=60|1440: только администратор платформы, без аргументов, cookie, IP-адресов, ключей и текстов, Cache-Control: no-store. Подключение ИИ (mcp.sid) эту ручку прочитать не может.

Причины отказов. Список закрытый: другие значения в счётчики не попадают.

Журнал сервера. Каждый отказ адаптера и охранника — одна JSON-строка в журнале CRM (journald), без ключей, адресов и аргументов:

{"event":"mcp_refusal","at":"2026-10-17T10:00:00.000Z","surface":"guard","reason":"guard_route_denied","status":403,"route":"/api/conversations/:conversationId","method":"GET"}
        

Отказы OAuth построчно не пишутся (их видно в карточке и метрике; для лимитов OAuth остаются строки MCP OAuth rate limit reached).

Оповещение. Если за 10 минут набирается больше 50 отказов invalid_or_revoked + guard_route_denied, в ops-чат Telegram уходит сообщение [production] WARNING MCP refusals с числом отказов. Следующее — не раньше чем через час. Работает, только если заданы OPS_ALERT_TELEGRAM_BOT_TOKEN и OPS_ALERT_TELEGRAM_CHAT_ID (тот же чат, что у остальных оповещений). Что делать: открыть карточку, посмотреть причины, проекты с отказами и последние отказы; при подозрении на утечку — отозвать ключ на странице MCP проекта.

Метрика и Grafana. Счётчик OTel leadforgeai.mcp.event.count с атрибутами lf.layer=mcp, mcp.surface (transport, guard, oauth), mcp.reason, http.response.status_code, mcp.tool (только имя инструмента каталога). После перевода OTLP → Prometheus он, скорее всего, называется leadforgeai_mcp_event_count_total.

Панель на уже существующей метрике HTTP-запросов (работает и без новой метрики, но не видит отказов внутри ответа 200):

sum by (http_route, http_response_status_code) (
          increase(leadforgeai_api_server_request_count_total{
            http_route=~"/mcp|/api/mcp/.+|/\\.well-known/oauth-.+",
            http_response_status_code=~"401|403|429|503"
          }[24h])
        )
        

Панель по новой метрике:

sum by (mcp_surface, mcp_reason) (increase(leadforgeai_mcp_event_count_total[24h]))
        

Имена метрик и меток после перевода OTLP → Prometheus не проверены на проде. Проверьте на хосте перед созданием панели:

curl -s 'http://127.0.0.1:19090/api/v1/label/__name__/values' | tr ',' '\n' | grep -E 'leadforgeai_(api_server_request_count|mcp_event_count)'
        

Если имя другое, поправьте его в запросах.

Что передать поддержкеЧто передать поддержке

Укажите время ошибки, название проекта, название инструмента, HTTP-статус и текст ошибки без секретов. Приложите минимальный набор аргументов, скрыв персональные сведения, если они не нужны для диагностики. Не присылайте API-ключ, OAuth-токены, cookies и полные заголовки авторизации.

Примеры API · Подключение · Правила доступа