Конфигурация MCP в Claude Code: .mcp.json, области видимости и диагностика

2026-09-09 Обновлено: 2026-09-14

Claude Code читает MCP-серверы из двух файлов: .mcp.json в корне проекта для серверов, разделяемых с командой, и ~/.claude.json для ваших собственных локальных серверов и серверов уровня пользователя. Оба используют один и тот же объект mcpServers, где каждая запись называет type - http, sse, ws или stdio, и сервер, который не появляется, почти всегда означает неверный type, нераскрытую переменную окружения либо вход, который так и не завершился.

Формат .mcp.json

Файл проекта с одним удаленным сервером и одним локальным выглядит так:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Поле type обязательно всякий раз, когда присутствует url. url без type сообщается как ошибка конфигурации (сообщение советует добавить "type": "http", либо sse, либо ws), что заменило собой более старую и куда менее полезную жалобу на отсутствующий command. Значение streamable-http принимается как псевдоним для http. Удаленному серверу, которому нужен статический токен, добавляют объект headers; локальному - command, args и env. Необязательный timeout - это лимит на один вызов инструмента в миллисекундах. Серверы WebSocket можно объявить только в файле либо через claude mcp add-json; флаг --transport значение ws не принимает.

Команда claude mcp add с --scope project сама записывает этот файл, поэтому ручное редактирование нужно только для полей, которые команда не раскрывает, либо когда вы предпочитаете просмотреть изменение в pull request.

Как держать секреты вне файла

Поскольку .mcp.json предназначен для коммита, токены вписывать в него не стоит. Claude Code раскрывает переменные окружения в command, args, env, url и headers: ${VAR} берет значение переменной, а ${VAR:-default} откатывается на значение по умолчанию, когда она не задана.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Упомянутая переменная, которая не задана и не имеет значения по умолчанию, не мешает серверу загрузиться; буквальный текст ${API_KEY} отправляется как есть, а claude mcp list печатает предупреждение. Это предупреждение - первое, что стоит искать, когда сервер подключается, но каждый вызов отклоняется как неавторизованный.

Для сервера с поддержкой OAuth скрывать вообще нечего: оставьте в записи только type и url, и каждый пользователь входит один раз из /mcp. Токен хранится для каждого пользователя отдельно, вне репозитория, и удаляется обратно командой claude mcp remove.

Подтверждение, приоритет и управляемые серверы

В первый раз, когда Claude Code видит сервер в .mcp.json проекта, интерактивная сессия спрашивает, использовать ли его; неинтерактивные запуски (claude -p, Agent SDK, облачные сессии) загружают его без вопросов. Решение запоминается для каждого проекта; claude mcp reset-project-choices сбрасывает его, чтобы можно было подтвердить заново после изменения.

Когда одно имя определено в нескольких местах, порядок такой: локальная область, затем область проекта, затем область пользователя, затем серверы, которые предоставляют плагины, затем коннекторы из claude.ai. Используется вся выигравшая запись целиком. Организации могут навязать фиксированный список серверов через управляемый файл конфигурации либо настройку managedMcpServers (Claude Code 2.1.259 и новее); они стоят выше любой области уровня пользователя, а управляемый файл, заявляющий эксклюзивный контроль, заставляет claude mcp add отказать с сообщением о том, что действует корпоративная конфигурация. Списки разрешений и запретов (allowedMcpServers, deniedMcpServers) тоже могут ограничивать, какие URL или команды пользователи могут добавлять, и запрет всегда побеждает.

Чтение вывода статуса

claude mcp list сообщает по каждому серверу один из статусов: подключен, требуется аутентификация, не удалось подключиться, ожидает подтверждения, отклонен через disabledMcpjsonServers, либо отключен для этого проекта. Стоит знать несколько менее очевидных предупреждений, которые он печатает: скрытые пробелы в начале или конце значения (вставленный токен, закончившийся переносом строки), одно и то же имя, указывающее на разные эндпоинты в двух областях, и горстка зарезервированных имен, которые нельзя использовать для собственных серверов. Серверы WebSocket в списке вообще не показываются; проверяйте их через claude mcp get <name> или /mcp.

Частые сбои и их решения

Удаленный сервер показывает "needs authentication" либо отвечает 401 или 403. Откройте /mcp, выберите сервер и завершите вход в браузере, либо выполните claude mcp login <name>. Если сервер использует статический токен, проверьте значение заголовка и предупреждение о нераскрытых переменных.
Локальный сервер не подключается при запуске. Выполните его команду вручную в той же оболочке, чтобы увидеть настоящую ошибку; обычные причины - отсутствующая среда выполнения, пакет, который нужно установить, либо обязательная переменная окружения. Медленно запускающиеся серверы упираются в лимит запуска, который поднимает MCP_TIMEOUT в миллисекундах, например MCP_TIMEOUT=10000 claude.
Сервер подключается, но инструмент возвращает усеченный результат. Вывод инструмента по умолчанию ограничен 25 000 токенами, с предупреждением от 10 000; MAX_MCP_OUTPUT_TOKENS поднимает этот предел.
Инструменты как будто отсутствуют в диалоге. Claude Code откладывает определения инструментов до момента, когда они действительно нужны, чтобы контекст оставался компактным, так что в начале загружаются только имена и инструкции сервера; ассистент все равно находит их, когда запрос совпадает. Установите "alwaysLoad": true в записи сервера, если хотите, чтобы его полные определения присутствовали с самого первого хода.
Удаленный сервер обрывается посреди сессии. Claude Code повторяет попытку для оборвавшегося соединения до пяти раз с растущими задержками и до трех раз для неудавшегося первого HTTP-соединения, но не для ошибок аутентификации и не для локальных серверов, так что сбой аутентификации сам себя не исправит.

Проверка конфигурации на живом сервисе

Самый быстрый способ проверить .mcp.json проекта - сервер, чьи ответы можно проверить независимо. С закоммиченным { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } и каждым разработчиком, вошедшим один раз через /mcp, запрос вроде "запусти HTTP-проверку нашего staging-URL из Европы и Азии" должен вернуться с настоящими кодами состояния и временем отклика из контрольных точек HostTracker, что либо подтверждает, что файл читается корректно, либо сужает проблему до входа в систему. Сопутствующее руководство, как добавить MCP-сервер в Claude Code, подробнее разбирает путь через командную строку и области видимости.