Содержание
Вы настроили сервер MCP (Model Context Protocol), но при открытии /mcp он завис в подобном состоянии — знакомо?
/mcp
filesystem ✓ connected (12 tools)
github ✗ failed
notion △ needs authentication
my-server ⏸ pending approvalMCP даёт Claude Code «руки» — внешние инструменты (операции с файлами, GitHub, базы данных, различные API), однако его соединения дают сбой чаще, чем можно ожидать. Причины делятся на три семейства: «сбой запуска локального подпроцесса», «удалённая аутентификация» и «ошибки в файле конфигурации», и статус /mcp подсказывает, какое из них перед вами. В этой статье разобраны как читать статус, устранение причин по отдельности, главная ловушка Windows и рабочий процесс диагностики — на основе официальной информации.
Главное — сразу. (1) Сначала посмотрите статус через /mcp (и claude mcp list) — failed (сбой запуска), needs authentication (аутентификация) и pending approval (ожидание одобрения) требуют совершенно разных действий. (2) Для локального (stdio) обычные виновники — пути и переменные окружения, плюс проблема с npx на Windows. (3) Для удалённого (HTTP) обычный виновник — OAuth. (4) Если застряли, запустите claude --debug mcp, чтобы увидеть вывод ошибок сервера (stderr). Поведение и значения по умолчанию меняются от версии к версии, поэтому сверяйтесь с актуальной официальной документацией.
Статус подсказывает решение
— failed / needs auth / pending лечатся по-разному
✗ failed = проблема локального запуска, △ needs auth = удалённая аутентификация, ⏸ pending = ожидание одобрения.
Не сваливайте всё «не подключается» в кучу — сначала классифицируйте по статусу; это кратчайший путь.
1. О чём говорит эта ошибка
Серверы MCP бывают двух общих типов подключения. (1) stdio (локальный) — Claude Code запускает команду сервера как подпроцесс на вашей машине и общается через стандартный ввод-вывод. (2) HTTP (удалённый) — подключается к облачному серверу по URL (более старый SSE объявлен устаревшим). Что значит «не подключается», сильно зависит от типа.
Локальный (stdio) сбой почти всегда означает «сама команда не смогла запуститься» — неверный путь, npx не разрешается (особенно на Windows) или сервер немедленно падает из-за отсутствия обязательной переменной окружения. Удалённый (HTTP) сбой обычно означает «OAuth не завершён» — сервер возвращает 401/403 и показывает needs authentication. А когда ни то ни другое, но конфигурация не действует, подозревайте расположение файла конфигурации, опечатку в JSON или одобрение проекта.
Поэтому первый шаг — «открыть /mcp, прочитать статус и определить, к какому из трёх семейств это относится». Воспринимать любую ошибку как абстрактное «не подключается» и тыкать наугад — это окольный путь. В следующем разделе разберём, как читать статус.
2. Сначала прочтите статус через /mcp
Запустите /mcp в сессии (или claude mcp list / claude mcp get <name> из оболочки), чтобы увидеть состояние каждого сервера. Основные статусы и их значения:
| Статус | Значение | Куда смотреть в первую очередь |
|---|---|---|
| ✓ connected | Подключено. Рядом показано число инструментов | Если число инструментов 0: «подключено, но нет инструментов» → переподключение / отладка |
| ✗ failed | Не удалось запустить или исчерпаны попытки | Локальный запуск = команда, путь, npx, переменные окружения (§3, §4) |
| △ needs authentication | Удалённый вернул 401/403. OAuth не пройден | Выполните аутентификацию из /mcp (одобрите в браузере) |
| ⏸ pending approval | Ожидание одобрения сервера из проектного .mcp.json | Одобрите в /mcp. Если ошибочно отклонили: claude mcp reset-project-choices |
| ✗ rejected | Проектный сервер, который вы ранее отклонили | То же (reset-project-choices для повторного одобрения) |
Суть: «failed = проблема запуска, needs authentication = аутентификация, pending = одобрение» — статус однозначно определяет ваше действие. Часто упускаемый случай — «connected, но 0 инструментов» — сервер запустился, но не возвращает список инструментов; переходите к переподключению или проверьте логи через claude --debug mcp.
3. Основные причины сбоев и их устранение
Вот характерные причины failed (сбой локального запуска) и проблем с конфигурацией в паре со способами устранения.
Главные причины failed / проблем конфигурации
spawn ... ENOENT.env каждого сервера (в .mcp.json или --env). env из settings.json НЕ доходит до MCP.MCP_TIMEOUT (мс) при запуске, например MCP_TIMEOUT=10000 claude..mcp.json кладётся в корень репозитория (не в .claude/, не в settings.json). Неопределённая ${VAR} ломает разбор конфигурации.needs authentication. OAuth из /mcp. Внимание: отклонённый статический заголовок аутентификации показывается как failed.
Для локального проверяйте по порядку: 1) путь → 2) переменные окружения → 4) расположение конфигурации.
Для удалённого 6) аутентификация — это почти всё. Ловушка Windows из следующего раздела тоже очень распространена.
Проектный .mcp.json можно распространять через git, и при первом использовании он запрашивает одобрение. Если вы случайно закроете этот запрос, сервер останется выключенным (pending/rejected). Запустите claude mcp reset-project-choices, чтобы заново пройти одобрение. Сочетайте это с основами MCP и межагентным A2A, чтобы увидеть полную картину связности.
4. Когда сбой происходит на Windows (главная ловушка)
На нативной Windows крайне распространён случай, когда MCP-серверы на основе npx не подключаются с ошибкой spawn npx ENOENT / Failed to connect. Причина: npx в Windows на самом деле является пакетной обёрткой (npx.cmd), а запуск процесса в Node не может напрямую разрешить .cmd.
Решение: оберните в cmd /c
Сделайте так, чтобы command был cmd, а не напрямую npx, и передайте /c npx ... в качестве args:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}Либо запускайте под WSL — это надёжно. Если where npx показывает путь, но запуск всё равно не удаётся, в первую очередь подозревайте именно эту проблему с .cmd. Некоторые случаи, привязанные к конкретной версии, могут быть исправлены в более поздних выпусках, поэтому попробуйте также обновиться до последней версии.
5. Рабочий процесс диагностики
Когда причина неясна, действуйте сверху вниз. Хитрость в том, чтобы убедиться, что сервер работает отдельно, прежде чем винить Claude Code.
Изолируйте сверху вниз
/mcp и claude mcp list / get, чтобы проверить статус (failed, auth или pending).claude --debug mcp, чтобы прочитать stderr (вывод ошибок) сервера. Причина падения обычно прямо здесь.npx ... в той же оболочке?). Если нет — проблема возникает раньше Claude Code.npx @modelcontextprotocol/inspector) — изучите список инструментов и вызывайте их в интерфейсе.mcp*.log. /doctor тоже проверяет.
Правило: сначала убедитесь, «запускается ли сервер отдельно?».
Как только это улажено, остальное сужается до конфигурации (путь, env, расположение) или аутентификации.
Примечание: добавление слишком большого числа MCP-серверов приводит к тому, что определения инструментов съедают контекст (особенно при настройках постоянной загрузки). Claude Code по умолчанию откладывает определения инструментов через поиск инструментов, поэтому влияние невелико, но всё же разумно отключать серверы, которыми вы не пользуетесь. Перегрузка контекста может даже вызвать ошибку Prompt is too long.
6. Чек-лист профилактики
Привычки, чтобы не застревать на подключениях MCP.
(1) Указывайте локальные скрипты абсолютными путями. (2) Кладите ключи сервера в отдельный env каждого сервера (не в settings.json). (3) На Windows оборачивайте в cmd /c npx ... (или используйте WSL). (4) Держите .mcp.json в корне репозитория; следите за синтаксисом JSON и неопределёнными ${VAR}. (5) Серверы не должны писать логи в stdout (используйте stderr). (6) После изменения конфигурации перезагрузите (полностью перезапустите Desktop; заново одобрите проектные серверы). (7) Если застряли, изолируйте проблему через claude --debug mcp и отдельный запуск сервера, а при необходимости обновитесь до последней версии.
Итоги
При ошибках подключения серверов MCP в Claude Code кратчайший путь — классифицировать по статусу /mcp на три семейства. ✗ failed — это проблема локального запуска (путь, переменные окружения, тайм-аут, расположение конфигурации — а на Windows оборачивайте npx в cmd /c), △ needs authentication — это удалённый OAuth (пройдите аутентификацию из /mcp), а ⏸ pending approval — это проектный сервер, ожидающий одобрения (одобрите в /mcp; ошибочное отклонение исправляется через claude mcp reset-project-choices).
Диагностируйте по порядку: (1) статус через /mcp -> (2) stderr через claude --debug mcp -> (3) отдельный запуск -> (4) MCP Inspector -> (5) полный перезапуск Desktop. Убедитесь, что сервер работает отдельно, прежде чем винить Claude Code, и остальное сузится до конфигурации или аутентификации. Всего три привычки — переменные окружения в отдельном env сервера, .mcp.json в корне репозитория, логи в stderr — резко сокращают число инцидентов. Связанное: Что такое MCP, Монетизация серверов MCP, Сборник ошибок Claude Code.
FAQ
Q. /mcp показывает «failed». С чего начать?
A. failed — это в основном сбой запуска локального (stdio) сервера. Проверяйте по порядку: (1) путь к команде/скрипту (используйте абсолютные пути), (2) обязательные переменные окружения (кладите их в отдельный env сервера) и (3) на Windows оборачивайте в cmd /c npx .... Если причина всё ещё неясна, прочтите stderr сервера через claude --debug mcp и сначала проверьте, запускается ли сервер отдельно в той же оболочке.
Q. Пишет «needs authentication», и инструменты не работают.
A. Это удалённый (HTTP) сервер запрашивает аутентификацию (401/403). Откройте /mcp и выполните аутентификацию для этого сервера; процесс перейдёт к одобрению OAuth в браузере. После завершения токены надёжно сохраняются и автоматически обновляются. Учтите, что некоторые сервисы (Microsoft 365, Gmail, Google Calendar) не поддерживают локальную аутентификацию из Claude Code и должны подключаться через Settings → Connectors на claude.ai.
Q. На Windows мой сервер на npx просто не подключается.
A. npx в Windows на самом деле является пакетной обёрткой (npx.cmd), которая часто не запускается с spawn npx ENOENT. Измените command на cmd, а args на ["/c","npx","-y","package-name"], чтобы обернуть его. Запуск под WSL тоже надёжен. Если where npx показывает путь, но запуск всё равно не удаётся, это почти наверняка проблема с .cmd. Возможно, она исправлена в новых версиях, так что попробуйте также обновиться.
Q. Сервер «connected», но показывает 0 инструментов.
A. Сервер успешно запустился, но не возвращает список инструментов. Частая причина — stdio-сервер пишет логи в stdout и портит протокол — всегда направляйте логи в stderr. Сначала переподключитесь из /mcp; если это не помогает, проверьте вывод сервера через claude --debug mcp.
Q. Я настроил сервер, но он не появляется в /mcp.
A. Вероятная проблема — расположение файла конфигурации. Общий проектный сервер кладётся в .mcp.json в корне репозитория (он не читается ни в .claude/, ни внутри settings.json). Неопределённая ${VAR} тоже ломает разбор конфигурации. Проектным серверам нужно первичное одобрение; если закрыть запрос, сервер останется в состоянии pending — пройдите одобрение заново через claude mcp reset-project-choices.
