Claude Code не подключается к серверу MCP: как читать статус и устранять ошибки

Вы настроили сервер MCP (Model Context Protocol), но при открытии /mcp он завис в подобном состоянии — знакомо?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP позволяет Claude Code работать с внешними инструментами и данными. При сбое подключения в журнале может появиться и строка MCP error -32000: Connection closed. Причину можно сузить, если сопоставить три вещи: статус, способ подключения и подробности ошибки. В статье по порядку разобраны локальный запуск, удалённая связь и аутентификация, конфигурация и одобрение.

Главное: (1) Прочитайте статус и подробности через /mcp и claude mcp get <name>. (2) failed бывает как у локальных, так и у удалённых серверов. Для stdio смотрите команду и переменные окружения; для HTTP — URL, сеть, ответ сервера и аутентификацию. (3) Если причина неясна, соберите журналы подключения через claude --debug=mcp. Исправляйте только то, на что указывает реальная ошибка, затем переподключитесь и проверьте результат.

1. О чём говорит эта ошибка

Когда соединение закрывается, в журнале появляется такая строка.

MCP error -32000: Connection closed

MCP error -32000: Connection closed означает, что соединение MCP закрылось. MCP TypeScript SDK связывает код -32000 с ConnectionClosed и выводит эту формулировку, когда соединение закрывается (см. обработку закрытия соединения в SDK). Эта строка сообщает только результат — «закрылось», а причина закрытия — в предшествующих записях журнала. Именно по ним различайте, завершился ли процесс сервера до инициализации или связь оборвалась уже после подключения.

Соединение может закрываться и при правильной конфигурации. Issue #20713 — отчёт пользователя о том, что в Claude Code 2.1.19 на macOS соединение закрывалось во время инициализации. «Состояние гонки» как причина — предположение автора отчёта, а сам Issue в апреле 2026 года закрыт с пометкой not planned. Отправляя собственный отчёт, укажите ОС, версию, способ подключения и журналы с удалёнными секретами.

MCP-серверы обычно используют два способа подключения. (1) stdio (локальный) — Claude Code запускает команду сервера как дочерний процесс на вашем компьютере и обменивается данными через стандартные потоки ввода-вывода. (2) HTTP (удалённый) — подключается к облачному серверу по URL (старый SSE устарел). Значение «не подключается» сильно зависит от способа подключения.

У локальных (stdio) серверов типичные сбои такие: команда не найдена, нет нужных переменных, сервер сразу завершается, журналы попадают в stdout. У удалённых (HTTP) серверов причинами становятся ошибка в URL, сеть, ответы 5xx, тайм-ауты и аутентификация. Ошибки в расположении, синтаксисе и области действия файла конфигурации встречаются при обоих способах.

Сначала запишите статус и подробности ошибки и посмотрите, используется ли stdio или HTTP. Меняя несколько настроек одновременно, трудно понять, какая помогла. Начните с таблицы ниже и проверяйте по одной подходящей причине.

2. Сначала прочтите статус через /mcp

Запустите /mcp в сессии (или claude mcp list / claude mcp get <name> из оболочки), чтобы увидеть состояние каждого сервера. Основные статусы и их значения:

failed появляется и при сбое локального запуска, и при сбое удалённой связи. Различить их помогают подробности: в claude mcp list — в конце строки ✘ Failed to connect, а в claude mcp get <name> и на экране подробностей /mcp — в строке Issue: выводятся HTTP-статус или код ошибки и текст ошибки, который вернул сервер. Отказ 401/403 при подключении с фиксированным заголовком Authorization тоже приводит к failed.

Если удалённый сервер отключается посреди сессии, Claude Code автоматически пытается переподключиться, и на это время в /mcp отображается pending (это не то же самое, что ожидание одобрения). Если все пять попыток не удались и сервер перешёл в failed, появляется уведомление MCP server "<name>" disconnected · open /mcp to reconnect (если нужна повторная аутентификация, статус становится needs authentication). Серверы stdio автоматически не переподключаются — подключите их заново вручную через /mcp. Кроме того, /mcp помечает серверы, которые объявляют возможность инструментов, но не предоставляют ни одного. Сервер, предоставляющий только ресурсы или промпты, с нулём инструментов работает нормально. См. официальное описание подробностей статуса.

3. Основные причины сбоев и их устранение

Пункты для проверки при сбоях подключения и несоответствиях конфигурации. Просматривайте по порядку, начиная с пунктов для вашего способа подключения.

Проектный .mcp.json можно распространять, но не включайте в коммит сами секреты. Например, используйте ссылку ${API_KEY} и задайте нужное значение в каждой среде. Некоторые защищённые имена переменных, включая учётные данные самого Claude Code, в удалённых URL и заголовках заменяются пустыми строками (официальные правила подстановки). В интерактивном сеансе запрашивается одобрение проектных серверов, а claude -p и SDK загружают их без такого запроса. Серверы, которые всё же не должны загружаться, внесите в disabledMcpjsonServers (официальная документация области project). По теме: основы MCP, A2A.

4. Проверка запуска npx в Windows

Если Windows сообщает spawn npx ENOENT, сначала посмотрите исполняемый файл и PATH командой where.exe npx. Затем попробуйте, работают ли Node/npm и запускается ли указанный пакет сам по себе. Согласно официальной документации Node, файлы .cmd в Windows нельзя исполнить сами по себе: их запускают через оболочку или cmd.exe.

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. Рабочий процесс диагностики

Когда причина неясна, действуйте сверху вниз. Хитрость в том, чтобы убедиться, что сервер работает отдельно, прежде чем подозревать Claude Code.

Примечание: Claude Code по умолчанию загружает определения инструментов по мере необходимости благодаря поиску инструментов, поэтому добавление серверов мало влияет на контекст. Но у серверов с alwaysLoad и в конфигурациях с отключённым поиском инструментов определения загружаются сразу, поэтому надёжнее отключать неиспользуемые серверы командой /mcp disable <name>. Перегрузка контекста ведёт к Prompt is too long.

6. Чек-лист профилактики

Привычки, которые помогут не застревать на подключениях MCP.

(1) Указывайте фактические пути исполняемых файлов и скриптов stdio. (2) Различайте переменные stdio и заголовки аутентификации HTTP; не помещайте секреты в общие файлы. (3) В Windows смотрите where.exe npx и Node/npm; пробуйте cmd.exe /c только при проблеме со способом запуска. (4) Поместите .mcp.json в корень проекта и проверьте синтаксис JSON, переменные и одобрение. (5) Направляйте журналы stdio в stderr, а не в stdout. (6) Меняйте по одному параметру, затем переподключайтесь и проверяйте результат на нужной операции.

Итоги

Исследуйте ошибки подключения MCP в Claude Code, сопоставляя статус, способ подключения и подробности ошибки. failed не ограничивается сбоем локального запуска: его вызывают и ошибки связи HTTP, и отклонённые фиксированные заголовки аутентификации. needs authentication — отправная точка для проверки аутентификации, а pending approval — для пересмотра одобрения проектного сервера.

Порядок действий: прочитайте статус и Issue: → прочитайте журналы для соответствующего способа подключения → проверьте отдельный запуск или связь → переподключитесь и попробуйте операцию. Категория отладки задаётся командой claude --debug=mcp. Добавьте --debug-file ./claude-mcp-debug.log, чтобы сохранить журналы. Удалите секреты перед передачей. По теме: Что такое MCP, Монетизация MCP-серверов, Обзор ошибок Claude Code.

Если в приложении Codex история видна, но сообщения не отправляются, это проблема не MCP, а состояния беседы. Она разобрана в статье «thread not found» в Codex: диагностика и пример восстановления.

FAQ

В. /mcp показывает failed. С чего начать?
О. Посмотрите способ подключения и Issue:. Для stdio кандидаты — команда, путь, переменные окружения и stderr; для HTTP — URL, сеть, ответ сервера и аутентификация. Отказ 401/403 при подключении с фиксированным заголовком Authorization тоже приводит к failed, и тогда в Issue: выводится HTTP-статус.

В. Пишет «needs authentication», и инструменты не работают.
О. Действия зависят от способа аутентификации. Для сервера OAuth войдите через /mcp. С собственным headersHelper это состояние возникает, если вызов инструмента вернул 401/403, а повтор с заново полученными учётными данными тоже не удался. Если helper передаёт заголовок Authorization, Claude Code не переключается на OAuth: исправьте источник и значение учётных данных, затем подключитесь снова. Коннекторы, предоставляемые Anthropic, например Microsoft 365, Gmail и Google Calendar, не поддерживают локальный OAuth из Claude Code. Если добавить такой коннектор через claude mcp add или .mcp.json и войти через /mcp, появится is Anthropic-hosted and doesn't support local OAuth: удалите эту запись и подключите коннектор в настройках коннекторов claude.ai. См. официальное описание собственной аутентификации.

В. Сервер npx не подключается в Windows.
О. Посмотрите where.exe npx и Node/npm, попробуйте запустить тот же пакет с теми же аргументами. Если проблема в запуске файла .cmd, запустите через cmd.exe /c npx .... Если запускаете через WSL, установите Node и пакет на стороне Linux.

В. Статус connected, но инструментов 0.
О. Сначала выясните, должен ли сервер предоставлять инструменты. Если сервер предоставляет только ресурсы или промпты, ноль инструментов — это нормально. Если сервер объявляет возможность инструментов, но их 0, /mcp помечает его: изучите доступные возможности, разрешения, настройки сервера и журналы, затем переподключитесь. Диагностические журналы stdio направляйте в stderr, а не в stdout, используемый протоколом.

В. Сервер настроен, но воспользоваться им не удаётся.
О. Убедитесь, что общий проектный .mcp.json расположен в корне проекта, затем пересмотрите синтаксис, область действия и одобрение. Неопределённая ${VAR} без значения по умолчанию вызывает предупреждение и загружается как буквальный текст, что приводит к сбою запуска или аутентификации. Для HTTP укажите также type. Если claude mcp get <name> возвращает ✘ Rejected, сервер внесён в disabledMcpjsonServers в одном из файлов настроек: не ограничивайтесь повторным одобрением, а удалите эту запись.

Справочники конфигурации и команд: настройки env, справочник CLI, справочник подключений MCP.