Почему MCP-сервер не подключается — 4 причины по частоте

Симптом знакомый: команду добавления ты выполнил, она ответила «Added…», а инструментов у агента нет. Или в списке горит красное ✘ Failed to connect.

Первое, что надо знать: сообщение «Added» не значит, что сервер работает. Оно значит только, что строчка сохранилась в конфиг. Запуск и проверка связи происходят позже — и именно там всё и ломается.

Дальше — четыре причины по частоте. Начинай сверху: первая покрывает больше случаев, чем остальные вместе.

Причина 1: ты добавил сервер в другой папке

Самая частая — и вообще не поломка.

По умолчанию сервер добавляется в область local: он привязан к тому проекту, из которого ты выполнил команду. Перешёл в другую папку, запустил агента — и там его честно нет.

Как проверить. Зайди в ту же папку, где добавлял, и выполни:

claude mcp list

Если здесь сервер виден, а в рабочем проекте нет — диагноз подтверждён.

Как починить. Реши, где он тебе нужен, и добавь заново с нужной областью:

claude mcp add --scope user --transport http имя https://адрес/mcp

--scope user — сервер во всех твоих проектах. --scope project — файл .mcp.json в корне проекта, его коммитят и он работает у всей команды.

Отдельная ловушка. Если ты правил конфиг руками — проверь путь. Читаются ровно два файла: ~/.claude.json и .mcp.json в корне проекта. Пути вроде ~/.claude/mcp.json или ~/.claude/config/mcp.json выглядят логично, но их никто не читает. Файл лежит, а сервера нет.

Причина 2: сервер не стартует

Статус ✘ Failed to connect или ✘ Connection error. Тут надо разделить два случая, и проверяются они по-разному.

Локальный сервер: запусти его команду руками. Просто выполни в терминале ровно то, что ты указывал после --:

npx -y @playwright/mcp@latest

Что видишь — то и диагноз:

• Команда запустилась и висит, ожидая ввода. Так и должно быть: сервер жив, проблема в конфиге. Чаще всего — забыл разделитель -- в команде добавления. Без него аргументы уезжают не туда. Сверь: claude mcp get имя покажет, какую команду агент пытается запустить.
• Команда падает с ошибкой. Читай текст — там прямо написано, чего не хватает: не установлен Node.js, нет браузера, не найден пакет.

Сервер по ссылке: постучись в адрес.

curl -I https://адрес/mcp

Ответ читается так:

• 404 или 405 — сервер жив. Многие MCP-эндпоинты отвечают только на POST, так что это нормальный признак «адрес доступен».
• 401 или 403 — сервер жив, но нужна авторизация. Добавь токен: --header "Authorization: Bearer твой_токен".
• Тишина, таймаут — проблема в адресе или в сети. Проверь URL целиком: claude mcp get имя.

И частая мелочь при вставке токена — лишний пробел или перенос строки на конце. Выглядит одинаково, работает по-разному.

Причина 3: не хватило 30 секунд на старте

Симптом: первый раз ✘ Failed to connect, а через минуту-другую тот же сервер внезапно ✔ Connected.

Это таймаут запуска. По умолчанию на старт даётся 30 секунд, а npx в первый раз качает пакет — и не успевает.

Как проверить. Подожди полминуты и повтори claude mcp list. Позеленел — причина была в этом.

Как починить. Если пакет тяжёлый и не успевает стабильно, подними лимит (значение в миллисекундах):

MCP_TIMEOUT=60000 claude

Причина 4: подключился, но инструментов ноль

Статус зелёный, а агент говорит, что ничего не умеет. Это уже не связь — сервер стартовал, но не зарегистрировал ни одного инструмента.

Почти всегда причина одна: не хватает переменной окружения, обычно API-ключа. Без него сервер поднимается, но показать ему нечего.

Как проверить. Внутри сессии выполни /mcp, выбери сервер и посмотри его список инструментов. Пусто — диагноз подтверждён.

Как починить. Посмотри в документации сервера, какие переменные он ждёт, и передай их флагом:

claude mcp add имя --env API_KEY=твой_ключ -- npx -y пакет

Важен порядок: --env идёт до разделителя --, иначе флаг уедет в команду сервера. Что это за переменные вообще — разбирали в статье про переменные окружения.

Правлю .mcp.json, а ничего не меняется

Файл читается при старте сессии. Выйди и зайди заново — правки подхватятся.

Если и после перезапуска пусто, выполни claude mcp list в терминале и поищи предупреждение о разборе: кривую запись пропускают молча, но в предупреждении называют поле. Остальные серверы при этом продолжают работать — поэтому «часть есть, часть нет» выглядит загадочно.

Сервер висит в статусе «Pending approval»

Это не ошибка. Так помечают серверы из общего .mcp.json проекта: их надо один раз подтвердить внутри сессии. Если когда-то отклонил по ошибке — сбрось решения командой claude mcp reset-project-choices.

С чего начать, если ничего не помогло

Вернись к базе и пройди путь заново на заведомо рабочем сервере — пошаговый разбор подключения занимает пять минут. Если чистый пример подключается, а твой нет — дело в конкретном сервере, и дальше читать надо его документацию. Что такое MCP и почему серверы вообще так устроены — в базовой статье.