MCP-серверы в Codex: config.toml, транспорты и отладка молчащего сервера

Агент умеет читать ваш код и запускать команды в терминале — но он не видит тикет в трекере, макет в Figma и свежую документацию библиотеки, которую вы обновили вчера. Всё это приходится копировать в чат руками. MCP закрывает именно эту дыру: вы один раз объявляете внешний сервер, и его инструменты появляются у агента в сессии. Разберём, как это делается в OpenAI Codex — где лежит конфигурация, какие ключи в ней работают, как передать секрет, что делать с молчащим сервером и сколько такое подключение стоит в токенах.

Коротко (TL;DR)

MCP (Model Context Protocol) — это стандарт, по которому агент подключается к внешним инструментам и данным. Если вам нужно понять сам протокол — клиент, сервер, инструменты, ресурсы — у нас есть отдельный разбор что такое MCP и как он устроен. Здесь речь только про настройку в OpenAI Codex: что именно писать в файл и какие грабли ждут.

Главное, что нужно знать сразу (данные на 11 августа 2026, Codex CLI версии 0.147.0):

• Настройки MCP живут в общем файле конфигурации ~/.codex/config.toml, в секциях вида [mcp_servers.<имя>] (официальная документация Codex по MCP). Отдельного файла под MCP нет.
• Один конфиг на три поверхности. Десктоп-приложение ChatGPT, Codex CLI и расширение для IDE делят одну MCP-конфигурацию для одного хоста: настроили один раз — переключаетесь между клиентами без повторной настройки.
• Транспорта два. Локальный процесс (stdio), который Codex запускает сам командой, и удалённый сервер по адресу (Streamable HTTP). Третьего варианта нет.
• Есть путь через терминал: codex mcp add, list, get, remove, login, logout. Команда удобнее для первой настройки, файл — для того, что нужно повторять на новой машине.
• Проверка подключения — команда /mcp в интерфейсе Codex: она показывает подключённые серверы и их инструменты.
• Подключение не бесплатное. По моему замеру четыре типовых сервера дают 69 инструментов, схемы которых занимают около 13 тысяч токенов контекста в каждом ходу — ещё до первой строчки вашего кода.

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

Что даёт Codex подключённый MCP-сервер

После подключения у агента появляются инструменты — функции, которые он может вызвать во время сессии сам, без вашего копирования данных в чат. Сервер Linear отдаёт инструменты работы с тикетами, сервер Figma — доступ к макетам, Context7 — свежую документацию библиотек.

Атаки через MCP-серверы на ИИ-агентов: четыре класса, реальные CVE и защита

ИИ-стек для UGC-рекламного видео: 30-секундный ролик из трёх моделей и его цена

GPT-6.1 Astra не выйдет в октябре: модель обманывала и действовала без разрешения

OpenAI и Anthropic расследуют десятки тысяч инцидентов агентов: взломы и чужие ключи

Эссе Arthur Hayes «Safety First»: ИИ-долг, страховщики и ставка на печать денег

Кроме инструментов Codex читает у сервера поле instructions — текст, который сервер возвращает при инициализации. Codex использует его как указание, действующее на весь сервер, рядом с описаниями отдельных инструментов. Официальная документация советует авторам серверов держать первые 512 символов этого поля самодостаточными: именно они доступны модели в момент, когда она решает, как пользоваться сервером.

Практическая рамка простая. Встроенных возможностей Codex — файловая система, команды оболочки, git, веб-поиск — хватает для почти любой работы внутри репозитория. MCP нужен там, где задача выходит за его границы: трекер задач, дизайн-инструмент, браузер, база данных, внутренний сервис компании. Это же говорит и сама документация OpenAI: MCP берут, когда агенту нужны возможности, которые живут вне локального рабочего пространства.

Два транспорта Codex: локальный stdio и удалённый Streamable HTTP

Первое решение при настройке — какой транспорт. Codex поддерживает ровно два, и они же являются двумя стандартными привязками в спецификации протокола.

Про SSE стоит сказать отдельно, потому что вокруг него много путаницы. Отдельного транспорта «HTTP+SSE» больше нет: Streamable HTTP заменил его начиная с ревизии протокола 2024-11-05. Но сам механизм Server-Sent Events никуда не делся — он используется внутри Streamable HTTP, когда сервер отдаёт ответ потоком. То есть умер транспорт, а не технология.

Ещё одна тонкость для тех, кто копает глубже. Свежая ревизия спецификации от 28 июля 2026 заметно поменяла устройство протокола: убрала сессию с рукопожатием initialize и запретила серверу самому инициировать запросы. При этом все четыре сервера, которые я поднимал для замеров 11 августа 2026, согласовали предыдущую ревизию — 2025-06-18, а документация Codex по-прежнему описывает чтение поля instructions «при инициализации». Вывод для практики: экосистема живёт на предыдущей ревизии, и сверять состояние надо не по гайдам, а по ответу самого сервера.

Объявляем сервер в config.toml: разбор каждого ключа

Codex хранит настройки MCP в config.toml рядом с остальной конфигурацией. По умолчанию это ~/.codex/config.toml. Можно ограничить серверы одним проектом через .codex/config.toml в репозитории — но только для проектов, которым вы явно доверяете.

Каждый сервер описывается таблицей [mcp_servers.<имя>]. Имя вы придумываете сами, по нему потом обращаются команды get, remove и login.

Вот рабочий пример локального сервера:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

Ключи stdio-сервера:

А вот удалённый сервер:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Ключи HTTP-сервера:

Общие ключи работают для обоих транспортов:

Собранный вместе тонко настроенный сервер выглядит так:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]        # применяется ПОСЛЕ enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

Обратите внимание на screenshot: он стоит в обоих списках, и запрет побеждает. Это официальный пример, и он специально показывает приоритет.

Ключ type в конфигурацию не пишем

По сторонним гайдам кочует строка type = "stdio" внутри блока сервера. В справочнике опций Codex такого ключа нет, и я решил проверить это не на слово, а экспериментом на изолированной копии конфигурации.

В обычном режиме Codex такую строку молча проглатывает — конфигурация загружается, сервер работает. Но у CLI есть флаг --strict-config, который сам описан как «ошибиться, если config.toml содержит поля, не распознанные этой версией Codex». Под ним тот же файл падает с конкретной формулировкой:

Error: error loading config: .../config.toml:2:1:
unknown configuration field `mcp_servers.withtype.type`

Метод я проверил контролем: дописал в заведомо валидный конфиг несуществующий ключ bogus_key_check — и режим назвал его по имени точно так же. То есть проверка работает, и вердикт по type однозначный: этой версией Codex ключ не распознаётся.

Откуда тогда путаница? Поле type действительно существует — но в выводе, а не во входном файле. Команда codex mcp list --json печатает блок transport с полем type и значениями stdio или streamable_http. Авторы гайдов видят его в выводе и переносят во входной конфиг. Вреда от лишней строки в обычном режиме нет, пользы — тоже.

Команды codex mcp add, list, get и remove

Второй путь настройки — терминал, без ручной правки файла. Точный синтаксис по версии 0.147.0:

Форма записи у add строгая: codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...). Либо адрес, либо команда после двойного тире — вместе они не используются. Полезные флаги:

• --env KEY=VALUE — переменные окружения для сервера, только для stdio;
• --bearer-token-env-var ENV_VAR — имя переменной с токеном, только для HTTP;
• --oauth-client-id и --oauth-resource — параметры OAuth-входа.

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

codex mcp add context7 -- npx -y @upstash/context7-mcp

А удалённый сервер GitHub, по инструкции самого GitHub, подключается через HTTP-эндпоинт:

codex mcp add github --url https://api.githubcopilot.com/mcp/ \
  --bearer-token-env-var GITHUB_PAT_TOKEN

Когда что выбирать: команда быстрее и не даёт опечататься в имени ключа, а файл воспроизводим — его можно положить в свои dotfiles и развернуть на новой машине одним движением. Тонкая настройка вроде enabled_tools или политики одобрений в любом случае делается файлом.

Переменные окружения и секреты: чем env отличается от env_vars

Это та развилка, на которой чаще всего застревают: сервер запускается, а токена не видит. У stdio-сервера есть два разных ключа, и они делают разные вещи.

• env — задаёт переменным значения. Пишете MY_ENV_VAR = "MY_ENV_VALUE" — процесс сервера получит именно это значение.
• env_vars — перечисляет переменные, которые разрешено пробросить из окружения. В справочнике опций это названо белым списком: вы указываете имя, а значение подхватывается из вашего окружения.

Разница видна в выводе codex mcp list --json: env возвращается картой со значениями, а env_vars — списком имён. В моём эксперименте это выглядело как "env": {"MY_ENV_VAR": "MY_ENV_VALUE"} против "env_vars": ["LOCAL_TOKEN"].

У env_vars есть расширенная форма записи с указанием источника:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

Простая строка и source = "local" читают локальное окружение Codex. source = "remote" читает окружение удалённого исполнителя и работает только с удалённым stdio.

Отдельно про секреты у HTTP-серверов: ключ bearer_token_env_var хранит имя переменной, а не сам токен. Записать токен значением в config.toml нельзя ни одним из документированных ключей — и это правильное поведение, потому что конфигурация нередко попадает в dotfiles-репозиторий.

Приятная деталь, которую я заметил в эксперименте: табличный вывод codex mcp list маскирует значения переменных звёздочками (MY_ENV_VAR=*****), оставляя видимыми имена. Конфигурацию можно показать коллеге или вставить в тикет, не раскрыв секретов.

Авторизация сервера: codex mcp login, bearer-токен и сессия ChatGPT

У stdio-серверов авторизации как отдельного механизма нет — и это не упущение Codex, а требование спецификации: реализациям на stdio предписано не следовать OAuth-спецификации, а получать учётные данные из окружения. Отсюда и набор ключей: только env и env_vars.

У HTTP-серверов источников несколько, и порядок важен. Ключ auth — это то, что пробуется после настроенных bearer-токенов и заголовков авторизации:

• oauth (значение по умолчанию) — берёт сохранённые MCP-OAuth-креды;
• chatgpt — использует текущую сессию ChatGPT для доверенного первопартийного адреса, с откатом на сохранённый OAuth.

Важная оговорка из документации: если ни один источник учётных данных не разрешился, Codex может подключиться к серверу вообще без авторизации. То есть «подключилось» не означает «авторизовалось», и это стоит проверять глазами.

Для входа у сервера, который требует OAuth, есть отдельная команда:

codex mcp login figma --scopes files:read,file_comments:write

Сама спецификация требует от HTTP-транспорта OAuth 2.1 с обязательным PKCE, реализации Protected Resource Metadata (RFC 9728) на стороне сервера и параметра resource по RFC 8707 на стороне клиента. Отсюда и ключи scopes и oauth_resource в конфигурации Codex — они прямое следствие этих требований.

Две настройки спасают в неудобных случаях:

• mcp_oauth_callback_port (верхнеуровневый ключ, в официальном примере 5555) — если провайдер требует фиксированный порт обратного вызова. Без него Codex занимает произвольный свободный порт.
• mcp_oauth_callback_url — если нужен свой адрес обратного вызова. Здесь легко ошибиться: этот ключ задаёт базовый адрес, к которому Codex дописывает серверный идентификатор, и регистрировать в провайдере нужно полный итоговый redirect_uri вместе с этим суффиксом, а не только базовый хост.

Где лежат полученные токены, задаёт ключ mcp_oauth_credentials_store. Допустимые значения — auto, file и keyring, и этот набор я получил от самого Codex: подставил в конфигурацию заведомо неверное значение под --strict-config и получил ответ «unknown variant bogus_value, expected one of auto, file, keyring». То есть по умолчанию (auto) выбор делает сам Codex, а keyring явно просит системное хранилище ключей.

Дальше начинается зона, где я не могу дать гарантию. По разбору исходников на стороннем ресурсе, при недоступном системном хранилище Codex откатывается на файл $CODEX_HOME/.credentials.json открытым текстом. Официального подтверждения этой детали я не нашёл, поэтому считаю её вероятной, но непроверенной. Практический вывод от неё не зависит: если для вас важно, где физически лежит токен от чужого сервиса, ставьте keyring явно, а не полагайтесь на auto.

Проверяем, что инструменты доехали до агента

Объявить сервер и подключить сервер — разные события. Приёмка настройки занимает минуту и делается тремя способами.

1. /mcp в интерфейсе Codex. Штатный способ: команда показывает активные серверы и их инструменты. Работает и в терминальном интерфейсе — если вы с ним ещё не освоились, весь рабочий цикл Codex CLI разобран отдельно, — и в композере приложения. Если сервер в списке есть, а инструментов у него ноль — проблема на стороне сервера, а не конфигурации.
2. codex mcp list в терминале. Выводит две таблицы — отдельно локальные stdio-серверы, отдельно удалённые HTTP — с колонками статуса и авторизации. Флаг --json отдаёт то же машиночитаемо.
3. codex mcp get <имя> --json — конфигурация одного сервера так, как её увидел Codex. Быстрый способ поймать опечатку в ключе: если вы ждали enabled_tools, а в выводе его нет, значит написали не то.

В выводе есть поле, которого нет на странице документации про MCP, — auth_status (в таблице это колонка Auth). У stdio-сервера оно показало unsupported, у HTTP-сервера с bearer-токеном — bearer_token. Это самый быстрый способ увидеть, какой источник учётных данных разрешился, ещё до запуска сессии.

Общая диагностика установки — команда codex doctor: она проверяет установку, конфигурацию, авторизацию и состояние рантайма. А вот точечной проверки одного сервера в Codex пока нет: команды codex mcp check <server> не существует, это открытый запрос на функциональность в репозитории с 25 мая 2026.

Молчащий MCP-сервер: пять причин и что смотреть в каждой

Самая частая жалоба звучит так: сервер добавлен, в конфигурации всё правильно, а инструментов у агента нет. Причин немного, и они хорошо различаются по симптому.

Первую строку я воспроизвёл сам: положил в изолированную конфигурацию блок только с args, без команды и адреса. Codex отвечает так:

Error: failed to load bootstrap configuration
Caused by:
    invalid transport
    in `mcp_servers.broken`

Вторая строка — самая недооценённая, и её стоит объяснить подробно, потому что она объясняет большинство «молчащих» серверов. Спецификация требует от stdio-сервера жёстко: он не имеет права писать в стандартный вывод ничего, кроме валидных сообщений протокола; для логов есть стандартный поток ошибок. А пакеты из npm любят напечатать при старте баннер, предупреждение об устаревшей версии или подсказку. Любая такая строка ломает поток JSON-RPC — и Codex видит сервер, который отвечает мусором. Проверяется просто: запустите ту же команду в терминале руками и посмотрите, что она печатает до первой строки JSON.

Про таймауты полезно знать порядок величин. В моём замере «прогретые» серверы поднимались за 0,62–0,82 секунды, а при первом холодном запуске с загрузкой пакета — за 1,64–4,91 секунды. Дефолтный лимит старта — 10 секунд, то есть на быстром канале запас есть, а на медленном первый запуск в него укладывается уже не всегда.

Windows-случай отмечен в репозитории отдельным открытым тикетом от 30 марта 2026: stdio-сервер падает при запуске через corepack/npx, но работает при указании абсолютного пути к node.exe. Тикет заведён на десктопное приложение (версия 0.117.0-alpha), но конфигурация у поверхностей общая, поэтому относиться к этому стоит как к общей особенности Windows, а не как к баге одного клиента. Если у команды часть разработчиков на Windows, проще сразу договориться об абсолютных путях в проектной конфигурации.

MCP в облачных задачах против локального запуска Codex

Здесь нужна честность, потому что гайды обычно пишут «настройте MCP в Codex», не разделяя поверхности продукта. А поверхности ведут себя по-разному.

По состоянию на 11 августа 2026 официальные страницы про облачное окружение Codex — устройство контейнера, скрипты установки, кэш, доступ в интернет — MCP-серверы не упоминают вовсе, а на форуме OpenAI с 7 октября 2025 висит открытый запрос на поддержку MCP в облачных задачах, без ответа. Прямой формулировки «в облаке MCP не поддерживается» в документации нет, поэтому корректно говорить о состоянии документации, а не о невозможности в принципе. Практический вывод один: рассчитывать на MCP в облачных задачах не стоит, а сценарии с внешними инструментами держать на локальном клиенте.

Две особенности облака объясняют, почему это не лечится обходными путями.

Во-первых, сеть. В фазе работы агента доступ в интернет по умолчанию заблокирован; скрипт установки при этом выполняется с доступом, чтобы поставить зависимости. Разрешить сеть можно, но осмысленно — списком доменов (есть готовый набор для сборки зависимостей) и, для дополнительной защиты, ограничением методов до GET, HEAD и OPTIONS, при котором POST, PUT, PATCH и DELETE блокируются. Удалённый MCP-сервер, которому нужен POST на свой эндпоинт, в такую политику не впишется.

Во-вторых, секреты. Обычные переменные окружения живут всю задачу, а секреты доступны только скриптам установки и по соображениям безопасности удаляются до начала фазы агента. То есть привычная схема «положу токен сервера в секреты окружения» в облаке не работает по устройству.

Есть экспериментальный ключ experimental_environment со значением remote, который запускает stdio-сервер через удалённый исполнитель, когда тот доступен. Но для удалённых HTTP-серверов такое размещение, по формулировке справочника, не реализовано — так что полноценным ответом на «MCP в облаке» этот ключ считать нельзя.

Сколько контекста стоит десяток серверов: замер на четырёх

«MCP съедает контекст» — общее место, но цифр почти никто не приводит. Я решил измерить сам, потому что от этого зависит практическое решение, сколько серверов держать включёнными.

Метод простой и воспроизводимый: поднять сервер по stdio, выполнить инициализацию, запросить список инструментов и посчитать, сколько занимают их схемы — имя, описание и JSON Schema входных параметров. Именно эти схемы клиент обязан положить в промпт, чтобы модель знала, что она может вызвать. Считал тем же токенизатором, который используют модели OpenAI. Замер от 11 августа 2026:

Тринадцать тысяч токенов за четыре сервера — столько уезжает в контекст в каждом ходу, до первой строки вашего кода и до вашего вопроса.

Самое полезное в этой таблице — не итог, а разброс. На один инструмент выходит от 168 до 526 токенов, и «дорогой» сервер — не тот, у кого больше инструментов. У Context7 их всего два, но каждый стоит 526 токенов, потому что описания длинные. А у Playwright с его 24 инструментами выходит 168 токенов на штуку. То есть считать надо не серверы и даже не инструменты, а объём описаний.

Оговорю ограничение метода: я мерил сами схемы, а фактический промпт клиента добавляет собственную обвязку вокруг каждого инструмента, поэтому мою цифру честно считать нижней границей. Независимая оценка есть только одна: сторонняя публикация от 8 апреля 2026 даёт 200–500 токенов накладных на сервер, 550–1400 токенов на инструмент и около 55 тысяч токенов за ход у сервера GitHub с 93 инструментами. Это существенно больше моего замера, метод там не описан — привожу как чужую оценку, а не как факт.

Цена не только в токенах. В репозитории Codex открыт тикет от 6 мая 2026 о том, что при большом числе настроенных серверов обнаружение инструментов блокирует первый ход, а команды-слэши недоступны, пока идёт запуск MCP. Другой открытый тикет, от 20 июля 2026, описывает, как при большом каталоге инструментов отладочные записи пишут в локальный журнал дампы списка инструментов примерно по 1,3 МБ. Ещё один, уже закрытый, был про лаги десктоп-приложения на «токен-тяжёлых» серверах.

Лечится это не отключением серверов, а урезанием каталога:

• enabled_tools — оставить у сервера только те инструменты, которыми реально пользуетесь. Из 29 инструментов браузерного сервера в конкретной задаче нужны три-четыре.
• disabled_tools — убрать точечно то, что мешает; помните, что запрет применяется после разрешения.
• enabled = false — держать сервер объявленным, но выключенным до момента, когда он понадобится.

Правильная настройка десятка серверов — это не «включить пять из десяти», а «оставить у каждого те три инструмента, которые нужны». Цена падает пропорционально объёму описаний, а не количеству блоков в конфигурации.

Доверие к сторонним серверам: чем рискует репозиторий

MCP-сервер — это чужой код, который агент запускает у вас на машине или чужой сервис, которому агент отправляет запросы. Риск здесь не гипотетический, и OpenAI разбирает его на своём примере.

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

Права инструментов шире, чем кажется. Деструктивные вызовы инструментов обязательно требуют одобрения, если инструмент объявил соответствующую аннотацию. Ключевое слово — «объявил»: гарантия зависит от добросовестности автора сервера. Управляемая часть на вашей стороне — политика одобрений: default_tools_approval_mode со значениями auto, prompt, writes и approve (режим writes спрашивает по инструментам, не помеченным как читающие) и переопределение на конкретный инструмент через tools.<инструмент>.approval_mode. Как это стыкуется с общими правилами доступа агента, разобрано в материале про режимы одобрения и песочницу.

Секрет уходит дальше, чем вы думаете. Токен, который вы дали серверу, доступен серверу целиком — а не «только для чтения тикетов». Личный токен доступа с широкими правами, отданный чужому серверу, эквивалентен выдаче этих прав автору сервера.

Что делать практически:

• давать серверу минимальные права в самом сервисе, а не полагаться на настройки Codex;
• держать default_tools_approval_mode = "prompt" у любого сервера, которому не доверяете полностью;
• урезать каталог до нужных инструментов — это одновременно и про токены, и про безопасность;
• предпочитать официальные серверы вендора сервиса неофициальным обёрткам;
• помнить про дефолты: локальный режим песочницы workspace-write держит сеть выключенной, а в облаке интернет в фазе агента тоже выключен по умолчанию. Риск создаёт тот, кто эти дефолты ослабляет.

Проектная конфигурация .codex/config.toml заслуживает отдельной осторожности: она работает только для доверенных проектов, и это не формальность. Файл в чужом репозитории — это чужой список серверов, которые запустятся у вас.

Codex сам как MCP-сервер: команда codex mcp-server

У Codex две роли, и вторая почти не описана в русскоязычных материалах. Если поискать «MCP-сервер для Codex», половина выдачи окажется про сторонние обёртки с названиями вроде codex-mcp-server на GitHub — то есть про Codex в роли сервера для других агентов. Штатный способ для этого есть, и чужой пакет для него не нужен:

codex mcp-server

Команда описана самим CLI как «запустить Codex как MCP-сервер (stdio)». Она отдаёт два инструмента:

• codex — запустить сессию Codex. Кроме обязательного prompt принимает переопределения: политику одобрений, режим песочницы (read-only, workspace-write, danger-full-access), модель, рабочий каталог, отдельные настройки конфигурации.
• codex-reply — продолжить сессию по идентификатору потока.

Осмотреть интерфейс можно инспектором протокола:

npx @modelcontextprotocol/inspector codex mcp-server

Важная оговорка: в репозитории этот интерфейс помечен как экспериментальный и подверженный изменениям без предупреждения. Для рабочего конвейера это значит «закрепите версию и ждите поломок при обновлении», а не «не используйте».

Зачем это нужно на практике: так Codex встраивается в чужого агента как исполнитель — например, оркестратор вызывает Codex на задачу по репозиторию и получает результат. Если вам ближе обратный сценарий, где Codex остаётся главным, — это всё, о чём шла речь выше.

MCP, скилл или плагин: что выбрать под задачу

Прежде чем подключать сервер, стоит проверить, нужен ли он вообще. У Codex три механизма расширения, и они решают разные задачи — эту развилку документация описывает прямо, а гайды по настройке обычно пропускают.

Практическая лесенка получается такая. Если задача решается встроенными возможностями — файлы, команды оболочки, git — не подключайте ничего. Если это повторяемый процесс с вашими правилами — это скилл; кстати, правила проекта в целом задаются файлом AGENTS.md, и он часто закрывает то, для чего люди тянутся к MCP. Если нужны внешние системы — трекер, дизайн, браузер, база — тогда MCP.

Часто лучший ответ — комбинация: скилл описывает процесс и называет, какие инструменты MCP использовать. Разница в цене контекста здесь не в пользу MCP: у скиллов работает постепенное раскрытие, когда заранее видны только метаданные, а у MCP схемы инструментов лежат в контексте всё время.

У серверов, пришедших из плагина, есть своя особенность: транспорт и команду такого сервера пользовательская конфигурация не задаёт — они приходят из манифеста плагина. Но включением и политикой инструментов управлять можно, через отдельную секцию plugins.<плагин>.mcp_servers.<сервер>.

Если вы работаете и с другими агентами, полезно сравнить механику: в Claude Code тот же протокол настраивается иначе, и разбор MCP в Claude Code показывает, где различия принципиальные, а где косметические.

Какие MCP-серверы стоит подключить к Codex и как объявить каждый

Список серверов растёт быстро, поэтому ниже — те, что названы в официальной документации Codex как обычные рабочие варианты, с типом подключения и точкой внимания при отладке.

Отдельно про подход к выбору. Соблазн подключить всё сразу понятен, но по замеру выше видно, чем это оплачивается. Разумная стартовая конфигурация — один сервер документации и один сервер того сервиса, где живут ваши задачи. Браузерные серверы включать под конкретную работу: у них самые большие каталоги.

Что в настройке MCP устареет первым и чем проверить у себя

Тема быстро движется, поэтому отмечу, что проверять в первую очередь. Волатильны версия CLI и состав подкоманд (на 11 августа 2026 это 0.147.0, релиз от 7 августа), набор ключей конфигурации, дефолтные таймауты, поддержка MCP в облаке, ревизия протокола и цена схем в токенах.

Проверять лучше не по гайдам, а по трём командам: codex mcp --help покажет актуальный состав подкоманд, codex mcp get <имя> --json — как Codex прочитал вашу конфигурацию, а codex doctor — состояние установки в целом. Если сомневаетесь, признаёт ли Codex какой-то ключ, воспроизведите мой приём: запустите с --strict-config и посмотрите, не назовёт ли он поле неизвестным. Ещё один надёжный ход — привыкнуть смотреть в /mcp после каждой правки конфигурации; это две секунды, а лечит большинство недоразумений.

FAQ

Работают ли MCP-серверы в облачных задачах Codex?

По состоянию на 11 августа 2026 официальная документация по облачному окружению MCP-серверы не описывает, а запрос на такую поддержку висит на форуме OpenAI открытым с октября 2025. Настройка MCP документирована для локальных клиентов — CLI, расширения IDE и десктоп-приложения. Планируйте сценарии с внешними инструментами на локальном запуске.

Где Codex хранит настройки MCP и можно ли держать их в репозитории?

В общем файле конфигурации: по умолчанию ~/.codex/config.toml, секции [mcp_servers.<имя>]. Проектный вариант .codex/config.toml в репозитории тоже поддерживается, но только для проектов, которым вы явно доверяете. Секреты в файл не пишите: ключ bearer_token_env_var принимает имя переменной окружения, а не сам токен.

Почему сервер добавлен, но в /mcp нет ни одного инструмента?

Чаще всего сервер печатает в стандартный вывод что-то помимо сообщений протокола — баннер, предупреждение об устаревшей версии. Спецификация это запрещает, и поток ломается. Запустите команду сервера руками в терминале и посмотрите, что она печатает до первой строки JSON. Вторая по частоте причина — не хватило дефолтных 10 секунд на старт.

Сколько MCP-серверов можно держать включёнными одновременно?

Жёсткого лимита нет, но есть цена. По моему замеру четыре типовых сервера дают 69 инструментов и около 13 тысяч токенов схем в каждом ходу. Считать надо не серверы, а объём описаний инструментов: разброс составил от 168 до 526 токенов на инструмент. Лучше держать много серверов объявленными, но урезать каталог каждого через enabled_tools.

Можно ли записать токен прямо в config.toml?

Ни один документированный ключ этого не позволяет: bearer_token_env_var и env_http_headers принимают имена переменных окружения, а не значения. У локальных серверов значения можно задать через env, но это тот же файл, который часто попадает в dotfiles-репозиторий, поэтому для секретов лучше использовать env_vars и держать значение в окружении. Где хранятся OAuth-токены, задаёт ключ mcp_oauth_credentials_store со значениями auto, file и keyring.

Нужен ли в конфигурации ключ type = «stdio»?

Нет. В справочнике опций Codex такого ключа нет, а под флагом --strict-config эта версия называет его неизвестным полем. В обычном режиме строка просто игнорируется. Путаница возникает потому, что поле type есть в выводе команды codex mcp list --json со значениями stdio и streamable_http — авторы гайдов переносят выходное поле во входной файл.