Как подключить MCP-сервер к Codex

Как подключить MCP-сервер к Codex: выберите один из двух транспортов — локальный STDIO-процесс запускается командой, удалённый Streamable HTTP доступен по адресу. Конфигурация живёт в config.toml, а команда codex mcp add записывает сервер в файл и при наличии OAuth сразу запускает вход.

STDIO и удалённый HTTP: что выбрать

Официальная справка OpenAI по MCP описывает два транспорта. STDIO-серверы работают как локальный процесс, который Codex запускает командой. Streamable HTTP-серверы доступны по адресу. От выбора транспорта зависит набор полей: у STDIO обязательна command, у HTTP — url.

Локальный процесс удобен, когда сервер поставляет разработчик инструмента и запускается на вашей машине. Адресный сервер удобен, когда инструмент размещён у владельца сервиса и требует входа. Официальная справка относит к поддерживаемым возможностям STDIO-серверы, переменные окружения, Streamable HTTP, аутентификацию по bearer-токену, OAuth с CIMD и DCR, вход через сессию ChatGPT для доверенных серверов первой стороны, а также инструкции сервера.

Инструкции сервера Codex читает из поля, возвращённого при инициализации, и использует как общее руководство рядом с инструментами. Авторам серверов справка советует держать первые 512 символов самодостаточными, чтобы ключевые указания были доступны в момент выбора инструмента.

Таблица ниже сводит транспорт, обязательные поля и способ проверки.

Дополнительные поля HTTP-сервера из справки: auth со значениями oauth (по умолчанию) и chatgpt, bearer_token_env_var, http_headers, env_http_headers, http_headers_helper. Поле http_headers_helper поддерживается для HTTP-подключений из локального окружения. Явные bearer-токены и учётные данные OAuth имеют приоритет над заголовком Authorization, который вернул helper.

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

Справка по конфигурации Codex описывает несколько слоёв. Личные значения по умолчанию лежат в ~/.codex/config.toml. Проектные переопределения добавляются файлом .codex/config.toml в репозитории. Проектные слои .codex/ Codex загружает только для доверенного проекта.

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

1. Флаги CLI и переопределения --config.
2. Проектные файлы .codex/config.toml от корня проекта к текущему каталогу, ближайший побеждает, только для доверенных проектов.
3. Профильные файлы, выбранные через --profile profile-name (~/.codex/profile-name.config.toml).
4. Пользовательский ~/.codex/config.toml.
5. Облачные управляемые значения config.toml для рабочего пространства, в которое выполнен вход.
6. Системный /etc/codex/config.toml на Unix.
7. Встроенные значения по умолчанию.

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

MCP-серверы задаются таблицей [mcp_servers.<server-name>]. Тот же файл хранит модель по умолчанию, политику подтверждений, режим песочницы и другие настройки. Расширение IDE открывает файл через шестерёнку и пункт Codex Settings > Open config.toml.

Согласованный пример: команда и TOML

Официальная справка OpenAI приводит пример добавления Context7 — бесплатного MCP-сервера документации для разработчиков. Команда записывает сервер в глобальный config.toml:

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

Общий вид команды с переменными окружения:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio-server-command>

Тот же сервер в файле выглядит так:

[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-сервера из справки: command обязателен, args, env, env_vars, cwd и experimental_environment необязательны. Значение remote в experimental_environment запускает stdio-сервер через удалённое окружение-исполнитель, когда оно доступно. Поле env_vars принимает имена переменных или объекты с источником:

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

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

Отдельный документированный пример — сервер OpenAI Docs MCP. Его автор, OpenAI, публикует адрес https://developers.openai.com/mcp и описывает сервер как доступный только для чтения: поиск и содержимое страниц документации разработчика. Команда добавления:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

В файле тот же сервер задаётся так:

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Автор сервера отмечает, что конфигурация общая для CLI и расширения IDE, поэтому настраивать её достаточно один раз.

Проверка конфигурации через список серверов

Документированный способ проверки — команда codex mcp list. Она показывает настроенные серверы. Полный перечень команд доступен через codex mcp --help.

Документация автора сервера time cockpit приводит пример вывода списка: имя сервера, адрес, столбец переменной bearer-токена, статус и вид аутентификации. В её примере строка выглядит как timecockpit, адрес https://mcp.timecockpit.com, статус enabled, аутентификация OAuth.

Дополнительные команды из той же документации:

В терминальном интерфейсе Codex команда /mcp показывает активные серверы. Документация time cockpit уточняет, что /mcp выводит серверы со статусом аутентификации и списком инструментов, а сам вход не запускает — для этого нужна отдельная команда codex mcp login во второй оболочке. Там же указано, что /mcp verbose даёт подробности.

В приложении ChatGPT для рабочего стола настройка идёт через Settings, затем MCP servers, кнопку Add server: имя, выбор STDIO или Streamable HTTP, команда или адрес, сохранение и Restart. Список серверов показывает, какие включены и какие требуют OAuth. Кнопка Authenticate запускает вход для сервера, который его требует. В расширении IDE путь тот же, отличается кнопка перезапуска — Restart extension.

Признак доступного инструмента и учебный запрос

Признак доступного инструмента — сервер виден в списке со статусом включённого, а его инструменты перечислены в /mcp. Документация time cockpit показывает такой вывод: после строки с адресом и статусом Auth: OAuth (logged in) идёт строка Tools: с именами инструментов, включая ping, get_current_user, get_entities, describe_entity, execute_tcql_query, get_timesheets, create_timesheet.

Учебный запрос для проверки документационного сервера приводит автор OpenAI Docs MCP: попросить найти схему запроса для инструментов Responses API в документации разработчика OpenAI и пересказать обязательные поля. Тот же автор советует добавлять в AGENTS.md строку о том, что сервер документации OpenAI следует использовать всегда, когда работа идёт с API, плагинами, ChatGPT или Codex. Без этой строки агенту нужно указывать на сервер явно.

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

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

OAuth, ключ, процесс и таймауты в области сервера

Поля аутентификации относятся к конкретному серверу. Для HTTP-сервера поле auth задаёт способ входа: значение oauth использует сохранённые учётные данные MCP OAuth, значение chatgpt использует текущую сессию ChatGPT для доверенного сервера первой стороны с откатом на сохранённый OAuth. Поле bearer_token_env_var называет переменную окружения с bearer-токеном для заголовка Authorization.

Если ни один источник учётных данных не разрешился, Codex может подключиться к серверу без аутентификации. Вход запускается отдельно командой codex mcp login <server-name>.

Предварительно зарегистрированный OAuth-клиент задаётся при добавлении сервера:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Для конфиденциального клиента добавляется --oauth-client-secret, значение читается из переменной окружения. Справка указывает, что Codex сохраняет секрет как mcp_servers.example.oauth.client_secret в config.toml, и этот файл держат приватным, вне системы контроля версий.

Таймауты задаются в области сервера. startup_timeout_sec ограничивает время запуска сервера и по умолчанию равен 10 секундам. tool_timeout_sec ограничивает выполнение инструмента и по умолчанию равен 60 секундам. Верхнеуровневая настройка mcp_optional_startup_grace_ms управляет ожиданием необязательных серверов при построении начального каталога инструментов и по умолчанию равна 1000 миллисекундам. Значение 0 заставляет ждать каждый сервер в пределах его startup_timeout_sec; обязательные серверы в любом случае используют свои таймауты запуска.

Поле required = true заставляет запуск завершиться ошибкой, если включённый сервер не инициализировался. Поле enabled = false отключает сервер без удаления. Списки enabled_tools и disabled_tools ограничивают набор инструментов, причём запрещающий список применяется после разрешающего. Режим подтверждений default_tools_approval_mode принимает значения auto, prompt, writes и approve; режим writes запрашивает подтверждение для инструментов, не помеченных как доступные только для чтения. Для отдельного инструмента поведение переопределяется через tools.<tool>.approval_mode.

Пример из справки показывает эти поля вместе:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

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

Документация time cockpit описывает поведение обратного адреса OAuth применительно к своему серверу. Codex привязывает слушатель обратного вызова к 127.0.0.1. Когда метаданные сервера авторизации не сообщают о поддержке параметра iss, Codex добавляет к пути двенадцатисимвольный идентификатор, производный от полного адреса сервера. Поэтому разные адреса получают разные идентификаторы и требуют отдельной регистрации адреса перенаправления. Точное значение печатает команда codex mcp add с ключом --oauth-client-id, и оно сохраняется в oauth.callback_url. Эти детали относятся к конкретному серверу и его провайдеру входа; требования своего сервера берут из документации его автора.

Границы доверия и раздельные настройки клиентов

Проектные слои .codex/ загружаются только для доверенного проекта. Если проект помечен как недоверенный, Codex пропускает проектную конфигурацию, хуки и правила; пользовательские и системные слои продолжают загружаться. Это разделение стоит держать в голове, когда в репозитории появляется файл .codex/config.toml из внешнего источника.

Секреты хранятся в конфигурации и в хранилище учётных данных. Справка советует держать config.toml приватным и вне системы контроля версий, а секрет OAuth-клиента читать из переменной окружения. Документация time cockpit уточняет, что токены хранятся в диспетчере учётных данных Windows, а ~/.codex/.credentials.json служит запасным вариантом; команда codex mcp logout удаляет их.

Настройки MCP-клиентов не смешивают между собой. Официальная справка OpenAI указывает, что приложение ChatGPT для рабочего стола, Codex CLI и расширение IDE разделяют конфигурацию MCP для одного хоста Codex, поэтому настроенный сервер виден во всех трёх. Автор OpenAI Docs MCP приводит для сравнения конфигурации других клиентов: VS Code читает .vscode/mcp.json с ключом servers, Cursor читает mcp.json с ключом mcpServers, Claude Code добавляет удалённый HTTP-сервер командой claude mcp add --transport http. Формат файла и команда у каждого клиента свои.

Веб-версия ChatGPT не читает локальные файлы конфигурации Codex и не показывает локальное командное меню Codex; инструменты там подключаются через вкладку плагинов. Справка также отмечает, что локальные MCP-серверы и транспорты могут быть недоступны в облаке, а связность и аутентификацию проверяют отдельно.

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

1. Определите транспорт: локальный процесс или адрес.
2. Добавьте сервер командой codex mcp add либо таблицей [mcp_servers.<имя>] в нужном слое конфигурации.
3. Проверьте запись через codex mcp list и codex mcp get <name>.
4. Запустите вход, если сервер требует OAuth.
5. Откройте /mcp и убедитесь, что инструменты перечислены.
6. Задайте учебный запрос к данным, которые есть только у сервера.
7. Ограничьте набор инструментов и режим подтверждений под свою задачу.

Частые вопросы

Чем STDIO отличается от удалённого HTTP в Codex?

STDIO-сервер запускается локальной командой, и в конфигурации обязательна command. Streamable HTTP-сервер доступен по адресу, и обязательна url. Оба варианта задаются таблицей [mcp_servers.<имя>] и видны в codex mcp list.

Где хранится конфигурация MCP-серверов?

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

Как проверить, что сервер подключился?

Запустите codex mcp list и посмотрите статус сервера, затем codex mcp get <name> для подробностей. В терминальном интерфейсе команда /mcp показывает активные серверы и их инструменты. Признак готовности — имена инструментов в выводе.

Что делать, если сервер требует OAuth?

Запустите codex mcp login <server-name>. Для предварительно зарегистрированного клиента укажите --oauth-client-id при добавлении сервера, а секрет читайте из переменной окружения. Точный адрес обратного вызова печатает команда добавления, и его регистрируют у провайдера входа.

Почему инструмент не вызывается в ответе?

Проверьте, что сервер включён и его инструменты видны в /mcp. Для сервера документации OpenAI автор советует добавить в AGENTS.md строку о его обязательном использовании, иначе агенту нужно указывать на сервер явно. Если инструмент не появился, проверьте, что владелец опубликовал последнюю версию, а подключение активно.