# Lidfly Connection Doctor > Диагностировать подключение LidFly MCP v3 в Claude Code, Claude Desktop, Codex, Cursor, OpenCode и VS Code: неверный config, timeout транспорта, незавершённый или слетающий MCP OAuth, конфликт статического Authorization с OAuth, отсутствие provider-подключения и устаревшие skills. Использовать при Failed, Authenticate/Login, Authentication failed, requires OAuth reauthentication, SSE 405 и недоступных инструментах. - Skill: `awaik/lidfly-connection-doctor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add awaik/lidfly-connection-doctor` - Raw SKILL.md: https://api.skillmd.com/api/skills/awaik/lidfly-connection-doctor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: awaik (https://skillmd.com/u/awaik) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/awaik/lidfly-connection-doctor --- # LidFly Connection Doctor Определи слой сбоя и дай минимальное действие для восстановления. Не смешивай настройку AI-клиента, MCP OAuth, provider OAuth и skills. ## Определи клиент Используй доступный контекст, не угадывай: - Claude Code: команда `claude`, проектный `.mcp.json`, `CLAUDE.md`, `.claude/`. - Claude Desktop: интерфейс Connectors/Integrations и кнопки `Authenticate`/`Login`. - Codex CLI/app/extension: `AGENTS.md`, `.codex/config.toml`, `.agents/skills/`. - Cursor: `.cursor/mcp.json`, `AGENTS.md`, `.agents/skills/`. - OpenCode: `opencode.json`/`opencode.jsonc`, команда `opencode`, `AGENTS.md`, сгенерированные этим репозиторием `.agents/skills/`; `.opencode/skills/` проверяй только при явно подтверждённой ручной установке. - VS Code: только оболочка. Сначала определи, работает внутри Claude Code или Codex, и применяй инструкцию этого клиента. Не предлагай `.cursor/mcp.json` пользователю Claude. Не создавай параллельный config другого клиента. ## Диагностируй по порядку 1. Проверь, настроен ли удалённый Streamable HTTP endpoint `https://lidfly.ru/mcp/v3` в формате текущего клиента. 2. Проверь состояние MCP OAuth. 3. Только после успешного MCP OAuth проверь доступность верхнеуровневых LidFly tools. 4. Только после успешного MCP соединения проверяй provider-подключения через `get_provider_context`. 5. После рабочего MCP проверь наличие и свежесть skills. Не привязывай исправность к фиксированному числу tools или meta-tools. ## Классифицируй состояние ### Codex: частая повторная авторизация Если Codex после уже завершённого входа пишет `requires OAuth reauthentication` или снова требует браузерный вход после истечения access token, сначала определи версии всех процессов, которые используют общее хранилище: CLI, приложение и расширение Codex в VS Code. Для этого сценария поддерживается Codex 0.149 или новее. Если хотя бы один клиент старше, обнови его или полностью закрой все старые процессы Codex до изменения credentials. Не запускай новый login, пока старый CLI, приложение или расширение ещё работает: старый процесс может снова сохранить запись без issuer. Затем выполни одну миграцию в таком порядке: ```bash codex --version codex mcp logout lidfly codex mcp login lidfly codex mcp list ``` Классифицируй причину по границе клиента и сервера: - Если после истечения access token `/token` вообще не вызывался, ошибка возникла локально до обращения к LidFly. Это слой `mcp_oauth`: несовместимая legacy-схема credentials или отсутствующая issuer-привязка. Не обвиняй сервер, не меняй token TTL, `soft_rotation`, grants или rate limits и не предлагай повторять login без закрытия старых процессов. - Если `/token` вызывался и вернул `invalid_grant`, это отдельная серверная ветка refresh grant. Проверь безопасные события `oauth_refresh_*`, client binding и срок grant, не подменяя диагноз локальной issuer-ошибкой. - Если `/token` вернул успех, а следующий MCP-запрос не прошёл, проверяй доставку нового Bearer и MCP admission отдельно; новый браузерный вход сам по себе это не исправляет. При локальной диагностике credentials проверяй только наличие поля issuer и безопасные сроки. Никогда не показывай access/refresh token, authorization code, PKCE verifier, `state` или значения из Keychain. После миграции проверь read-only MCP-вызов, автоматический refresh после истечения 15-минутного access token и два параллельных актуальных процесса Codex без нового `/authorize`. Меняй только канонический `skills-source`. Generated-копии для AI-клиентов обновляй только через проверенный подписанный release, не вручную. ### Ожидается MCP OAuth Если UI показывает `Failed` и доступна кнопка `Authenticate` или `Login`, выдай ровно одно действие: > Нажмите `Authenticate`/`Login`, завершите вход в открывшемся браузере и затем повторите проверку подключения. На этом остановись. Не называй это timeout, не предлагай менять config и не обсуждай Яндекс, VK, Авито или другие provider tools до завершения MCP OAuth. ### Config отсутствует или неверен Исправляй только config обнаруженного клиента: - Claude Code: проектный `.mcp.json` или `claude mcp add` для remote HTTP OAuth. - Codex: `.codex/config.toml` и `codex mcp login lidfly`. - Cursor: `.cursor/mcp.json` с HTTP endpoint. - OpenCode: `opencode.json`/`opencode.jsonc`, `"type": "remote"`, URL `https://lidfly.ru/mcp/v3` и `opencode mcp auth lidfly`. - Claude Desktop: native Connector/Integration, без `.cursor/mcp.json`. - VS Code: config Claude Code или Codex, который реально работает внутри VS Code. Транспорт должен быть HTTP/Streamable HTTP, не SSE. ### Машиночитаемая ошибка аутентификации Если ответ LidFly содержит `credential_type`, используй его до разбора текста ошибки: - `legacy_or_unknown_bearer`: сервер не получил OAuth access token и не признал Bearer действующим API-ключом. Если для подключения ожидался OAuth, это слой `config`: безопасно проверь конфигурацию текущего клиента на статический `Authorization`, но не утверждай, что заголовок есть, пока не увидел его или серверная диагностика не доказала повторную отправку прежнего ключа. - `oauth_access_token`: до сервера дошёл OAuth-токен, но он истёк, отозван или больше не принимается. Это слой `mcp_oauth`: обнови токен или повтори вход. Не удаляй статический заголовок без отдельного доказательства. Не смешивай эти ветки: одинаковый HTTP `401` не означает одинаковую причину. ### OpenCode: статический Authorization перекрывает OAuth Если OpenCode после завершённого входа пишет `Authentication failed`, затем `SSE error: Non-200 status code (405)`, не делай вывод, что LidFly требует SSE. OpenCode сначала пробует Streamable HTTP, а SSE запускает как fallback после ошибки первого транспорта; `405` в этой последовательности вторичен. Классифицируй сбой как `config`, когда подтверждено хотя бы одно из следующего: - в блоке LidFly в `opencode.json`/`opencode.jsonc` есть `headers.Authorization` или другой статический Bearer API key; - в блоке LidFly стоит `"oauth": false`: этот флаг отключает OAuth, поэтому `logout`/`auth` не восстановят OAuth-доступ, пока флаг не удалён или не изменён; - серверная диагностика показывает один и тот же невалидный API key до и после успешной выдачи OAuth-токенов. Одно действие восстановления для подтверждённого OAuth-режима: удали только статический `headers.Authorization` и, если задан, `"oauth": false` из блока LidFly, не показывая значение заголовка, затем выполни `opencode mcp logout lidfly` и `opencode mcp auth lidfly`. Статический заголовок перекрывает OAuth-токен, поэтому новый API-ключ не создавай и LidFly на SSE не переключай. Если пользователь попросил исправить доступный локальный config, можешь удалить эти поля сам, сохранив остальные настройки. После входа сначала выполни `opencode mcp debug lidfly`: команда проверяет HTTP-соединение и OAuth discovery flow. Затем проверь `opencode mcp list` и доступность верхнеуровневых LidFly tools. Только после этого переходи к provider connections и skills. ### Connection timeout Ставь этот диагноз только после того, как config корректен и MCP OAuth не ожидает действия пользователя. Проверь доступность endpoint и повтори один безопасный connect/read. Не советуй повторять provider write. В OpenCode сначала выполни `opencode mcp debug lidfly`. Если HTTP/OAuth исправны, а получение списка tools завершается по timeout, проверь `timeout` в блоке LidFly: для remote MCP OpenCode по умолчанию ждёт 5000 мс. Увеличь только этот timeout до обоснованного значения, например `30000`, затем один раз повтори read-only проверку. Не маскируй увеличением timeout ошибки аутентификации или неверный endpoint. Если timeout повторяется, кратко зафиксируй клиент, endpoint и безопасный текст ошибки. Предложи `$lidfly-support-escalation`; не передавай токены, raw config с секретами или provider payload. ### MCP работает, provider не подключён Вызови напрямую `get_provider_context({ provider: ... })`. Если нужного подключения нет, объясни, какое подключение нужно добавить в LidFly. Не меняй MCP config: транспорт и MCP OAuth уже исправны. ### Skills отсутствуют или устарели Сначала докажи, что MCP tools доступны. Затем сравни project skills с текущим клиентским набором: - Claude Code: `.claude/skills`; - Codex: `.agents/skills` (legacy `.codex/skills` не считать основным); - Cursor: `.agents/skills`. - OpenCode: используй сгенерированные репозиторием `.agents/skills`; `.opencode/skills` проверяй только при явно подтверждённой ручной установке — sync этого репозитория туда не пишет. Предлагай обновить только skills текущего клиента. Отсутствие skills не выдавай за ошибку OAuth или транспорта. ## Формат ответа Сообщи: 1. обнаруженный клиент; 2. слой сбоя: `config`, `mcp_oauth`, `transport`, `provider_connection` или `skills`; 3. одно следующее действие; 4. что проверять после него. Для `Failed + Authenticate/Login` оставь только одно действие из раздела MCP OAuth.