MCP-серверы в Codex CLI: добавляем, настраиваем, авторизуем
MCP-серверы выдают Codex новые инструменты — актуальную документацию, вашу базу данных, ваши GitHub-репозитории. В этом разборе мы добавляем локальный stdio-сервер через codex mcp add, переключаемся на удаленный с --url и OAuth, смотрим записи config.toml за обоими и показываем проверки, доказывающие, что сервер действительно работает.
Коротко
- Codex читает MCP-серверы из ~/.codex/config.toml (глобально) или .codex/config.toml (проект). Каждая запись — таблица [mcp_servers.<name>] с command/args для локальных stdio-серверов или url для удаленных.
- codex mcp add context7 -- npx -y @upstash/context7-mcp ставит stdio-сервер без правки файла; codex mcp add <name> --url https://mcp.example.com/mcp регистрирует удаленный.
- Удаленные серверы авторизуются в браузере при первом подключении (Codex печатает Detected OAuth support и открывает экран согласия) или позже через codex mcp login <name>.
- Проверяйте через /mcp внутри TUI или codex mcp list в шелле. Codex 0.160.1 дополнительно сохраняет SYSTEMROOT, TEMP и TMP при запуске удаленных stdio-серверов с удаленными переменными окружения.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
Канал: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
Канал: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
Канал: Snyk9:14
Connect Codex to an MCP server — official documentation
Официальная документация: developers.openai.com/codex
Каждая команда, путь к файлу и ключ конфигурации на этой странице сверены с официальной документацией Codex MCP; видео выше — визуальные и фактические источники, включая экраны согласия OAuth и меню MCP в десктоп-приложении.
Скриншоты принадлежат их авторам и снабжены прямыми ссылками на точные таймкоды. Кадры с лицами не используются.
Добавляем MCP-серверы в Codex, шаг за шагом
Часть 1 — Ваш первый stdio-сервер
- 1
Выберите сервер в официальной документации MCP
Откройте developers.openai.com/codex/mcp — в собственной документации Codex лежит актуальный синтаксис команд, и CLI и IDE-расширение разделяют эту конфигурацию. В документах перечислены готовые серверы, с которых стоит начать: Context7 для живой документации библиотек, Figma, GitHub и другие. MCP-серверов сотни; для первого теста берите что-то read-only вроде Context7.
Официальная страница Connect Codex to an MCP server: синтаксис codex mcp add и готовый к копированию пример с Context7.Смотреть на 0:20 - 2
Установите через codex mcp add
Скопируйте пример и выполните в терминале: codex mcp add context7 -- npx -y @upstash/context7-mcp. Все после двойного тире — команда, запускающая процесс сервера. Codex ответит «Added global MCP server 'context7'» — global значит, что запись легла в конфиг уровня пользователя и доступна в каждом проекте.
Одна команда без правки файлов: CLI подтверждает добавление сервера в глобальный конфиг.Смотреть на 0:45 - 3
Посмотрите, что CLI записал в config.toml
codex mcp add — просто генератор для ~/.codex/config.toml. Откройте файл и найдете [mcp_servers.context7] с command = "npx" и args = ["-y", "@upstash/context7-mcp"]. Записи можно править и руками: добавить таблицу env для API-ключей или выставить startup_timeout_sec (по умолчанию 10) и tool_timeout_sec (по умолчанию 60) для медленных серверов. Ручная правка — ровно тот путь, которым идут видео Snyk и Net Ninja в карточке источников.
- 4
Запустите Codex и проверьте через /mcp
Стартуйте codex в проекте и введите /mcp. Панель MCP Tools перечисляет все настроенные серверы со статусом, точной командой запуска и доступными инструментами — у Context7 это query_docs и resolve-library-id. Чего-то не хватает — запись легла не в тот файл или сервер не стартовал.
Панель /mcp внутри TUI Codex: context7 включен, оба инструмента перечислены поименно.Смотреть на 1:05
Часть 2 — Пользуемся, потом уходим в remote
- 5
Сформулируйте промпт, который реально задействует сервер
Инструменты MCP вызываются по потребности, так что просите то, что без них не обойдется: «Проверь через Context7 актуальную документацию по настройке Tailwind CSS». Codex найдет библиотеку, вытащит доки через MCP-сервер и процитирует источники в ответе. Прокручивающиеся вызовы инструментов — доказательство, что сервер работает от начала до конца.
В ответе Codex процитированы точные URL документации Context7, вытащенные через MCP-сервер.Смотреть на 1:30 - 6
Добавьте удаленный сервер с --url
Многие провайдеры также хостят свой MCP-сервер удаленно — без локального процесса и без npx. Зарегистрируйте: codex mcp add context7 --url https://mcp.context7.com/mcp. Codex автоматически распознает поддержку OAuth, напечатает «Detected OAuth support. Starting OAuth flow...» и откроет браузер для авторизации. В config.toml запись — просто url = "https://mcp.context7.com/mcp" под [mcp_servers.context7].
Весь удаленный сценарий в одном терминале: add с --url, распознавание OAuth, ссылка авторизации и Successfully logged in.Смотреть на 2:22 - 7
Одобрите экран согласия OAuth
Браузер спросит, может ли Codex доступаться к вашему аккаунту от имени провайдера. Просмотрите запрошенные scope, нажмите Allow — терминал подтвердит «Successfully logged in». Для серверов без OAuth-флоу авторизуйтесь отдельно через codex mcp login <name>; серверы с токенами принимают bearer_token_env_var со ссылкой на переменную окружения.
Экран согласия Context7: просмотрите scope, которые запрашивает Codex, и нажмите Allow.Смотреть на 2:02 - 8
Ограничьте сервер одним проектом через .codex/config.toml
Серверы, осмысленные только в одном репозитории — как DBHub, stdio-сервер для вашей базы данных, — живут в конфиге проекта. Создайте в репозитории папку .codex, добавьте config.toml с записью [mcp_servers.dbhub] и передайте строку подключения через аргумент --dsn (подстройте пример Postgres из документации под MySQL или что у вас). Закоммитьте — и коллеги получат тот же сервер; папка должна быть доверенным проектом, чтобы конфиг загрузился.
Проектный .codex/config.toml: DBHub работает по stdio с DSN базы репозитория в args.Смотреть на 3:30
Часть 3 — Настоящие серверы и управление со второго дня
- 9
Опрашивайте базу данных через MCP-инструменты
С настроенным DBHub спросите Codex о базе: «Найди базу Petco и объясни таблицы», затем «Какой продукт самый продаваемый?». Codex вызовет инструменты сервера describe_table и execute_sql, спросит разрешение перед выполнением SQL и ответит реальными цифрами из ваших данных. Это самый быстрый способ отлаживать схемы и проверять данные при работе над бэкендом.
Codex вызвал инструмент execute_sql у dbhub и ответил самым продаваемым товаром и его выручкой.Смотреть на 4:40 - 10
Подключите GitHub через его удаленный MCP-сервер
README github/github-mcp-server описывает настройку для Codex: добавьте запись [mcp_servers.github] с url = "https://api.githubcopilot.com/mcp/" и авторизуйтесь через OAuth либо экспортируйте personal access token как переменную окружения (создайте fine-grained PAT в GitHub Settings, Developer settings, выдав Administration и Contents). Remote-first серверы — этот и Figma MCP — следуют той же схеме, что и шаг 6.
Инструкция по установке MCP-сервера GitHub: запись для Codex CLI плюс заметка об аутентификации OAuth/PAT.Смотреть на 5:22 - 11
Перезапустите и дайте инструментам работу
Перезапустите codex и следите за баннером: «Starting servers (0/3): context7, dbhub, github». Теперь одной инструкции — «форкни репозиторий openai/codex на мой аккаунт» — достаточно: Codex выберет инструмент fork у GitHub, спросит одобрение и выполнит. Никаких настроек под задачу: инструменты просто часть каждой сессии с этого момента.
- 12
Управляйте серверами через codex mcp list и десктоп-приложение
codex mcp list печатает все настроенные серверы прямо из шелла; удаление — убрать блок из config.toml и перезапустить команду для проверки. Десктоп-приложение и IDE-расширение читают тот же ~/.codex/config.toml, поэтому установленные здесь серверы появляются на странице Settings, MCP servers десктоп-приложения с переключателями вкл/выкл.
Настройки MCP servers в десктоп-приложении Codex: context7, dbhub и github с тумблерами плюс рекомендованные серверы.Смотреть на 7:30
Локальный stdio vs удаленные MCP-серверы в Codex
Оба типа живут в одних и тех же таблицах [mcp_servers.*] и видны в одной панели /mcp — разница в том, где работает сервер и как авторизуется. Выбирайте на сервер, а не на проект.
- 1Локальный stdio: Codex сам запускает процесс с command и args — обычно npx или бинарник. Он работает на вашей машине, поэтому достает сервисы localhost вроде базы разработки (именно так DBHub опрашивал MySQL в разборе), но runtime и обновления обеспечиваете вы.
- 2Удаленный: Codex общается с хостинговым url по streamable HTTP. Процесс поддерживать не нужно, авторизация централизована — OAuth по умолчанию либо bearer_token_env_var и http_headers для токеновых схем. Собственный пример документации — [mcp_servers.figma] с url = "https://mcp.figma.com/mcp".
- 3Удаленно исполняемый stdio: экспериментальная середина. experimental_environment = "remote" на stdio-записи переносит ее исполнение на удаленный executor, а env_vars решает, какие переменные отправляются — включая записи с пометкой source = "remote". Именно этот путь укрепил Codex 0.160.1.
- 4Scope: codex mcp add всегда пишет в глобальный ~/.codex/config.toml; серверы конкретного проекта кладут в .codex/config.toml внутри репозитория (только доверенные проекты). Глобально — инструменты, нужные везде; в проект — все, что несет окруженческие креды.
- 5Управление для обоих типов: startup_timeout_sec (по умолчанию 10) и tool_timeout_sec (по умолчанию 60) для медленных серверов, enabled/disabled_tools, чтобы разрешить список вызываемого, и required = true, если сервер обязан подняться, иначе Codex не стартует.
Практичный дефолт: read-only серверы документации вроде Context7 могут быть глобальными; все, что трогает креды или данные — DBHub, GitHub с PAT, — живет в конфиге проекта, где просматривается и отзывается вместе с репозиторием.
Настроено, но не работает: обычные подозреваемые
Большинство MCP-сбоев в Codex — это scope, таймаут или авторизация — именно в таком порядке. Пройдите список, прежде чем лезть в сам сервер.
- 1Сервера нет в /mcp: проверьте, какой файл вы правили. Глобальные записи живут в ~/.codex/config.toml; проектные — в .codex/config.toml и только для доверенных проектов. codex mcp list из шелла покажет, что Codex реально видит.
- 2Сервер падает по таймауту на старте: дефолтный startup_timeout_sec — 10 секунд, а холодная загрузка npx большого пакета легко выйдет за этот лимит. Преустановите пакет или поднимите startup_timeout_sec у записи.
- 3Вызовы инструментов падают с 401/403: креды отсутствуют или устарели. Выполните codex mcp login <name> для OAuth-серверов или задайте bearer_token_env_var и экспортируйте переменную. После починки /mcp снова покажет сервер как enabled.
- 4Удаленный stdio-сервер падает со странными ошибками Windows: до 0.160.1 запуск удаленного stdio MCP-сервера с явно настроенными удаленными переменными окружения мог терять SYSTEMROOT, TEMP и TMP, ломая стартовое окружение Windows-executor. Обновитесь до 0.160.1 или новее.
- 5Сервер стартует, но ответы неверные или пустые: многим хостинговым серверам нужен собственный API-ключ даже при OAuth — Context7, например, требует ключ через env. Посмотрите в документации провайдера точное имя env и добавьте его в таблицу env записи.
Две полезные ручки при отладке: required = true на сервере, от которого вы зависите, чтобы Codex никогда не стартовал молча без него, и enabled = false, чтобы выключить сервер, не удаляя конфиг.