Перейти к содержимому
Экосистема AI Vibe

Разборы

Пустая строка в настройках Claude Code «убивает» ключ MCP из `.env`

Редакция 21 августа 2026 г.

Пустая строка в настройках Claude Code «убивает» ключ MCP из `.env`

Соло-разработчик с парком AI-агентов и MCP-серверов на своей машине может неделями не замечать: ключ API лежит в project .env, а patent-search MCP отказывается от запросов — сервер считает себя «не настроенным». Редакция советует не копать сервер первым делом: в кейсе hexisteme виновата не «битая» конфигурация, а пустая строка в глобальных настройках Claude Code, которая затеняет реальное значение ниже.

Когда MCP-сервер «не видит» ключ, хотя .env выглядит правильно

hexisteme ведёт на локальной машине небольшой парк AI-агентов и MCP-серверов. Во время очередного аудита обвязки — settings, server configs, env vars — обнаружился MCP-сервер, оборачивающий внешний patent-search API: в project .env лежал валидный ключ, но в рантайме сервер вёл себя как не настроенный.

«Файл есть» и «значение реально используется» — разные вопросы. Автор сначала проверил .env, убедился, что ключ на месте, и искал баг в сервере — переустановку, смену auth API, чтение конфига. Симптом типичен для стека агентов: MCP-инструмент молчит, хотя секрет «где-то записан».

Пустой placeholder в глобальных настройках Claude Code

Корневая причина оказалась выше project .env. В глобальном файле настроек Claude Code в блоке mcpServers..env для этого сервера та же переменная была задана как пустая строка "". Автор оставил её «для документации» — чтобы напомнить, какое имя ожидает сервер.

Этот блок инжектится в окружение процесса до того, как серверный код читает .env. Внешний слой побеждает: для механизма precedence KEY="" эквивалентно «задано», а не «отсутствует».

Claude Code global settings (mcpServers..env: KEY="")
        ↓ inject into process env (KEY already defined as "")
Project .env (valid API key) + load_dotenv(override=False)
        ↓ does NOT overwrite existing KEY
Server reads os.getenv → "" → self-disable as unconfigured

«It exists» и «it's the value actually being used» — разные вопросы. Пустой binding в верхнем слое перекрывает реальный секрет ниже — без исключения, error log и предупреждения.

Тот же класс багов встречается не только в Python: compose environment:, launchd plists, CI env declarations — везде, где layered config отдаёт приоритет внешнему слою.

Почему python-dotenv молчит при override=False

Сервер грузит конфиг через python-dotenv, вызов load_dotenv() с дефолтом override=False: если переменная уже есть в окружении, значение из .env не перезаписывается — даже когда существующее значение пустая строка.

Дальше os.getenv(...) возвращает "", сервер корректно считает, что ключа нет, и самоотключается. Исключений, error log и предупреждений о том, что .env проигнорирован, нет — отсюда и недели «мертвого» MCP при «очевидно правильном» файле на диске.

Переключить load_dotenv(override=True) hexisteme не рекомендует как общий fix: для этого кейса сработает, но может сломать другие сценарии, где внешний слой должен побеждать.

Как найти затенение при аудите обвязки MCP

Инцидент нашли не точечным дебагом «мертвого» сервера, а проходом аудита по всей обвязке — settings, server configs, env. Правило для соло-workflow с несколькими MCP-серверами: искать во всех слоях выше .env объявления вида KEY: "" и удалять привязку целиком. Пропуск ключа отдаёт приоритет ниже; пустая строка — нет.

Диагностика в точке чтения — не факт существования на диске:

print(repr(os.environ.get("THE_KEY")))

'' vs None сигнализирует затенение выше по цепочке. В посте имя переменной не раскрыто — в примерах используется placeholder THE_KEY; для своего patent-search MCP подставьте фактическое имя из конфига.

Что сделать: fix и привычки после инцидента

Правильный fix — удалить пустое объявление из верхнего слоя (у автора — однострочное удаление в settings file), а не переписывать сервер.

После кейса hexisteme зафиксировал две привычки для стека агентов:

  1. Не оставлять «documentation placeholder» с пустыми значениями в слоях с правом переопределения — ни в Claude Code settings, ни в shell exports, ни в container env.
  2. При «очевидно правильном» конфиге первым шагом — вывести эффективное значение в точке чтения, особенно если MCP-сервер внезапно самоотключается.

Для соло-разработчика с Claude Code и несколькими MCP-серверами одной строки в .env недостаточно: нужно понимать порядок слоёв конфигурации, иначе инструмент остаётся не настроенным при видимом секрете.

Источники