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 работать с внешними инструментами и данными. Если подключение не удалось, не ставьте диагноз только по статусу: учитывайте способ подключения и подробности ошибки. В статье разобраны локальный запуск, удалённая связь и аутентификация, конфигурация и одобрение.

Главное: (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 TypeScript SDK связывает код -32000 с ConnectionClosed. По предшествующим записям выясните, что закрыло соединение: например, завершение сервера или обрыв связи. По одной формулировке нельзя установить, завершился ли процесс до инициализации или связь оборвалась позже. См. обработку закрытия соединения в SDK.

Возможен и дефект, не связанный с вашей конфигурацией. Например, Issue #20713 содержит пользовательский отчёт об отключении при инициализации Claude Code 2.1.19 на macOS. Не выдавайте диагноз пользователя за подтверждённую Anthropic причину или актуальную ошибку во всех средах. При отправке отчёта укажите ОС, версию, способ подключения и журналы с удалёнными секретами.

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 сам по себе не позволяет отличить сбой локального запуска от проблемы удалённой связи. Прочитайте HTTP-код или текст ошибки в Issue: из claude mcp get <name> либо в подробностях /mcp. Отказ 401/403 при подключении с фиксированным заголовком Authorization тоже приводит к статусу failed. Кроме того, ноль инструментов не обязательно означает ошибку, если сервер предоставляет только ресурсы или промпты. Сначала выясните, должен ли он предоставлять инструменты. См. официальное описание подробностей статуса.

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

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

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

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

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

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

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

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

Примечание: при большом числе MCP-серверов определения инструментов занимают контекст (особенно при постоянной загрузке). Claude Code по умолчанию откладывает загрузку определений благодаря поиску инструментов, поэтому влияние невелико, но разумно отключать неиспользуемые серверы. Перегрузка контекста может вызвать даже 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.

FAQ

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

Q. Пишет «needs authentication», и инструменты не работают.
A. Это удалённый (HTTP) сервер запрашивает аутентификацию (401/403). Откройте /mcp и выполните аутентификацию для этого сервера; процесс перейдёт к одобрению OAuth в браузере. После завершения токены надёжно сохраняются и автоматически обновляются. Учтите, что некоторые сервисы (Microsoft 365, Gmail, Google Calendar) не поддерживают локальную аутентификацию из Claude Code и должны подключаться через Settings → Connectors на claude.ai.

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

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

В. Сервер настроен, но воспользоваться им не удаётся.
О. Убедитесь, что общий проектный .mcp.json расположен в корне проекта, затем проверьте синтаксис, область действия и одобрение. Неопределённая ${VAR} без значения по умолчанию вызывает предупреждение и остаётся буквальным текстом при загрузке конфигурации, что может нарушить запуск или аутентификацию. Для HTTP укажите также type. Повторное одобрение само по себе не отменит настройки отклонения или управляемые политики.

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