Устранение неполадок MCP
Прежде чем повторять вызов, проверьте обнаружение инструментов, аутентификацию, доступ к организации, аргументы и результаты, которые не удалось определить.
Выберите, что проверить дальше, по признакам проблемы: если инструмент отсутствует, проверьте подключение, а если вызов отклонён — сообщение об ошибке аргумента или прав доступа. Сохраните имя инструмента, входные данные без секретов, ответ и соответствующий ресурс или версию источника. Эти сведения помогут завершить нужную работу, не повторяя запись с неизвестным результатом.
Нужные инструменты отсутствуют #
Сравните настроенную конечную точку со списком инструментов, который возвращает клиент. /mcp и /main предоставляют один и тот же набор инструментов после аутентификации. /account после аутентификации перенаправляет на /main.
Найдите members_listMemberships и engines_list и следуйте примерам первых запросов на чтение. Точные имена и схемы берите из актуального ответа tools/list. Наличие конечной точки API ещё не означает, что она доступна через MCP.
Если скрыта только часть инструментов, проверьте список разрешённых инструментов и настройки подтверждений в клиенте. Включите только то, что нужно для задачи. Если инструмент должен быть доступен, но его нет, сохраните для отчёта сведения о сервере и его версии, а также результаты обнаружения без секретов.
GET возвращает 405 #
Настройте Streamable HTTP для /mcp. После аутентификации GET-запрос к /mcp или /main возвращает 405 с Allow: POST. Клиент отправляет сообщения MCP методом POST. Если токен отсутствует или недействителен, сервер возвращает 401 ещё до передачи запроса на обработку. Аутентифицированный запрос к /account вместо этого возвращает 308 с перенаправлением на /main. Эти ответы на GET не показывают, работает ли корректное подключение MCP через POST. Выберите нужный транспорт и изучите ошибку подключения в клиенте.
Проблема с аутентификацией или выбрана не та организация #
Для 401 проверьте, что подключение прошло OAuth от имени нужного пользователя Lingo.dev. Серверу на хостинге нужен действительный пользовательский bearer-токен. Персональный или служебный ключ API не принимается ни в x-api-key, ни в качестве bearer-токена. Дайте клиенту обновить авторизацию или подключитесь заново через раздел управления учётными записями. Не включайте токены в диагностические данные.
Вызовите members_listMemberships, выберите нужную организацию из data и передайте её ИД в поле организации следующего инструмента. Для engines_list это поле orgId. Выбор другой организации из того же списка не требует повторной авторизации OAuth. Если вход выполнен не под той учётной записью, подключитесь заново: при обычном перезапуске клиент может использовать сохранённый сеанс.
Если членство отображается в ssoRequired, войдите в Lingo.dev через поставщика удостоверений этой организации и подключитесь заново. Если и data, и ssoRequired пусты, завершите настройку организации по адресу https://lingo.dev/orgs/start, затем снова запросите список членств. Недоступная организация может не существовать, пользователь может в ней не состоять, или для доступа может требоваться SSO. Не считайте каждый такой ответ признаком того, что срок действия учётных данных истёк.
Если инструмент отказывает в вызове из-за отсутствия разрешения или права доступа, проверьте требования операции, а не проходите аутентификацию снова и снова. Доступ к организации и право на конкретную запись проверяются отдельно. Объясните, каких полномочий не хватает. Не выбирайте без ведома пользователя роль или учётные данные с более широкими правами.
Инструмент сообщает, что настройка организации не завершена #
Организация создана недавно, и её создатель ещё не завершил настройку в веб-приложении: подключение интеграций, добавление коллег и создание первого движка. До завершения настройки инструменты уровня организации могут быть недоступны. Повторный вызов или авторизация не заменят эти шаги. members_listMemberships остаётся доступным. Откройте ссылку из сообщения, https://lingo.dev/orgs/<orgId>, под учётной записью создателя организации, выполните указанные в сообщении шаги и повторите вызов. См. Как завершить настройку новой организации.
Инструмент отклоняет аргументы #
Сравните входные данные с точной схемой, полученной через подключение. Сейчас аргументы инструментов передаются как поля верхнего уровня. Вложенные значения остаются там, где их определяет схема. Не добавляйте не предусмотренные схемой обёртки body, params или query. Явно указывайте поле организации там, где оно требуется: оно не подставляется из bearer-токена. Необязательное поле intent описывает задачу. Поддерживаемые операции с учётной записью см. в разделе Возможности.
Проверьте, что обозначает каждый ИД. members_remove.id — это ИД членства из members_list, а members_setRole.userId — ИД пользователя, связанного с этим членством. ИД движка локализации не заменяет ИД записи в журнале запросов. Копируйте непрозрачные курсоры или пары «временная метка/ИД» с полной точностью, а не восстанавливайте их по отображаемым датам.
Учитывайте различия, заданные схемой: между отсутствующими значениями и null, числами и строками, массивами и одиночными значениями. Прежде чем искать обходной путь для ошибки аргумента, проверьте схему подключённого инструмента.
Результат записи в учётной записи или выполнения задания неизвестен #
Прежде чем повторять вызов, запросите соответствующий ресурс или статус задания. Сетевая ошибка может возникнуть уже после того, как сервер принял запрос на создание ключа, приглашение, решение по проверке, предложение или задание. Выясните, внесено ли нужное изменение, вместо того чтобы автоматически отправлять его снова.
Если вы отправили задание провижининга, запросите provisioningJobs_get с сохранённым ИД задания, прежде чем решать, нужен ли повторный вызов. Для других операций проверьте сохранённый ресурс и правила, по которым подключённый инструмент сообщает о завершении. Сведения о рабочих процессах перевода см. в справочнике CLI или API.
Не хватает документации или подтверждающих данных #
Выполните поиск с помощью localization_search, затем передайте path из результата в docs_fetch, чтобы прочитать страницу целиком. Если путь не работает, снова найдите нужную задачу и используйте актуальный результат. База знаний использует отдельный путь хранения, не совпадающий с файловым хранилищем сайта. Поэтому страница сайта может отсутствовать в индексе базы знаний или быть там устаревшей. Прежде чем делать вывод, что возможность недоступна, проверьте актуальный справочник на сайте.
Сообщая о нерешённой проблеме MCP, укажите задачу, которую пытались выполнить, точное имя инструмента, версию сервера и ответ без секретов. Подтверждение получения отчёта не означает, что срок исправления уже определён.
Если вопрос касается качества, уточните, чего не хватает: подтверждающих данных из источника, завершённой оценки, применимого критерия или однозначного ответа. В каждом случае дальнейшие шаги будут разными. В разделе Измерение описано, как сообщать об имеющихся данных, не засчитывая случаи без ответа как успешные.