MCP-серверы для Codex CLI: настройка в config.toml по шагам

MCP-серверы дают агенту доступ к внешним инструментам: документации библиотек, трекеру задач, базе данных, браузеру. Codex CLI умеет подключать такие серверы двумя способами, командой и записью в config.toml. Ниже: как настроить MCP-серверы для Codex по шагам, как проверить, что они работают, и почему при подключении через шлюз ничего дополнительного делать не нужно.

Параметры взяты из документации OpenAI по MCP в Codex на 18 октября 2026. Набор опций растёт, поэтому полный список ключей смотрите в справочнике конфигурации Codex.

Что нужно знать заранее

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

Поддерживаются два типа серверов:

• STDIO: процесс, который запускается командой на вашей машине;
• Streamable HTTP: сервер по адресу, с авторизацией по токену в заголовке или через OAuth.

Для общей картины полезно прочитать статью MCP-сервер: что это и зачем агентам↗. Если вы пользуетесь Claude Code, там то же самое описано в материале про MCP в Claude Code↗.

Шаг 1. Убедитесь, что Codex работает со шлюзом

MCP-инструменты не зависят от провайдера моделей: Codex сам вызывает сервер и передаёт модели результат. Но сначала нужен рабочий Codex. Минимальная настройка для Zukko в ~/.codex/config.toml:

model = "gpt-6.1-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Ключ fetch_... из кабинета↗ положите в переменную окружения ZUKKO_API_KEY. Подробнее об установке и альтернативном способе с auth.json написано в документации по Codex↗. По данным документации Zukko, в Codex работают модели GPT и Claude, а модели GLM нет. MCP-инструменты модель вызывает как обычные функции, поэтому выбирайте модель, которая в вашей задаче корректно оформляет вызовы, и проверяйте это на практике.

Шаг 2. Добавьте сервер командой

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

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

Так в документации OpenAI подключён Context7, сервер с документацией для разработчиков. Формат команды: codex mcp add <имя> --env ПЕРЕМЕННАЯ=ЗНАЧЕНИЕ -- <команда запуска>. Переменные окружения для сервера передаются флагом --env.

Посмотреть список настроенных серверов:

codex mcp list

Все доступные подкоманды показывает codex mcp --help. Для серверов с OAuth есть вход: codex mcp login <имя>.

Шаг 3. Или пропишите сервер в config.toml

Для тонкой настройки редактируйте файл напрямую. Каждый сервер описывается таблицей [mcp_servers.<имя>].

Локальный сервер (STDIO):

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

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

command обязателен, args и env необязательны. env_vars перечисляет переменные из вашего окружения, которые можно пробросить серверу, чтобы не писать секреты в файл.

Сервер по HTTP:

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

Здесь url обязателен, токен берётся из переменной окружения, а не из файла. Это пример из документации OpenAI; подставьте адрес и переменные своего сервера.

Шаг 4. Ограничьте инструменты и таймауты

Полезные необязательные поля:

[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

• startup_timeout_sec (по умолчанию 10) и tool_timeout_sec (по умолчанию 60) пригодятся для медленных серверов;
• enabled = false отключает сервер без удаления записи;
• required = true останавливает запуск, если сервер не стартовал;
• enabled_tools и disabled_tools задают список разрешённых и запрещённых инструментов;
• default_tools_approval_mode принимает значения auto, prompt, writes и approve: режим writes запрашивает подтверждение для инструментов, не помеченных как «только чтение».

Для тех, кто работает в доверенном проекте: те же таблицы можно положить в .codex/config.toml внутри репозитория, и команда получит одинаковые серверы.

Шаг 5. Проверьте, что сервер виден

Запустите codex и введите в интерфейсе /mcp: Codex покажет активные MCP-серверы. Затем дайте простую задачу, которая требует инструмента, например «найди в документации библиотеки X пример вызова Y». В ходе работы Codex покажет вызов инструмента и запросит подтверждение, если это предусмотрено режимом.

Если сервер не виден, проверьте по порядку: нет ли опечатки в имени таблицы, запускается ли команда вручную в том же терминале, нет ли enabled = false, хватает ли startup_timeout_sec. Для локального npx важно, чтобы Node.js был в PATH того окружения, откуда запускается Codex.

Сколько токенов стоят MCP-серверы

Описания инструментов (имя, назначение, схема аргументов) отправляются модели вместе с запросом. Чем больше серверов и инструментов, тем больше входных токенов в каждом шаге. Это важно для бюджета агента.

Пример расчёта. Допустим, подключённые серверы дают 25 инструментов по 200 токенов описания: 200 × 25 = 5 000 токенов. Если сессия делает 60 запросов, получается 5 000 × 60 = 300 000 входных токенов. На gpt-6.1-sol (вход $0.27 за 1M, цены на 18 октября 2026) это 0,3 × 0,27 = $0.081 без кэша. Если часть входа берётся из кэша по цене чтения $0.013 за 1M, то при полном попадании в кэш 0,3 × 0,013 = $0.0039. Цифры условные: реальный размер описаний зависит от серверов. Суть в том, что лишние инструменты стоят денег и размывают выбор модели. Оставляйте через enabled_tools только нужные. У GPT-моделей шлюз учитывает чтение кэша, а запись в кэш отдельно не списывается.

Контролировать расход помогает лимит на ключ: Как поставить дневной и месячный лимит↗. Актуальные цены: GET https://api.zukko.pro/v1/models.

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

Нужно ли что-то настраивать в шлюзе для MCP?

Нет. MCP работает на стороне Codex, а шлюз получает обычные запросы к /v1/responses. Нужна только модель, которая умеет вызывать функции.

Чем MCP отличается от skills и плагинов Codex?

MCP это протокол подключения внешних инструментов. Skills это текстовые инструкции с необязательными скриптами, плагины упаковывают навыки и, по документации, могут включать и MCP-серверы. Для начала достаточно прямого подключения сервера, как выше.

Безопасно ли подключать чужие MCP-серверы?

Сервер получает доступ к тому, что вы ему даёте, и может выполнять код на вашей машине (STDIO). Подключайте проверенные серверы, секреты передавайте через переменные окружения, а режим подтверждения prompt или writes оставьте включённым.

Почему сервер есть в конфиге, но инструментов нет?

Чаще всего сервер не успел запуститься (увеличьте startup_timeout_sec) или команда запуска не работает в окружении Codex. Проверьте команду вручную и /mcp в интерфейсе.

Создайте ключ в кабинете Zukko, подключите Codex и добавьте первый MCP-сервер командой codex mcp add.