Подключение внешних инструментов через MCP: порт расширения для Codex

📚 Навигация по серии: Предыдущая статья [19 · Система памяти (Memories и Chronicle)] рассказывала о том, как научить Codex запоминать контекст между сессиями (накопление памяти). В этой главе мы изменим вектор и настроим интеграции: по умолчанию Codex работает только с локальными файлами и консолью, он не имеет доступа к базам данных, Figma или сторонней документации. Протокол MCP (Model Context Protocol) служит универсальным интерфейсом для подключения внешних инструментов и баз знаний. В следующей главе [21 · Субагенты (Subagents)] мы разберем распределение задач между пулом специализированных агентов с независимым контекстом.

Приведу типичный пример ошибки, которую я совершил при первой настройке MCP.

Я перешел на Codex после активной работы с Claude Code, где у меня выработалась мышечная память: для добавления сервера достаточно ввести claude mcp add --scope user xxx, где флаг --scope определяет область действия. При переходе на Codex я, не задумываясь, ввел аналогичную команду с флагом --scope, но терминал выдал ошибку неизвестного аргумента. Сначала я подумал, что у меня устаревшая версия, обновился — не помогло. Проверил синтаксис, перепробовал разные варианты команды — ошибка сохранялась.

Потеряв около двадцати минут и открыв руководство, я обнаружил: в Codex вообще нет концепции флага --scope. Все настройки серверов MCP прописываются в общем конфигурационном файле config.toml. Область действия определяется исключительно местоположением файла: глобальный ~/.codex/config.toml активирует сервер везде, а локальный .codex/config.toml проекта — только в текущем репозитории. Я пытался применить правила Claude Code к логике Codex, из-за чего совершал ошибки.

Я рассказываю об этом, чтобы уберечь вас от потери времени: сам протокол MCP стандартизирован, но синтаксис его конфигурирования в Codex отличается от Claude Code. В этой статье мы детально разберем настройку серверов в Codex и запустим рабочий пример.

После прочтения этой статьи вы получите:

• Четкое понимание сути MCP и какую именно проблему он решает в Codex
• Разницу между двумя типами серверов (локальные STDIO и удаленные Streamable HTTP)
• Два пути конфигурирования: интерактивный через codex mcp add и ручной через редактирование config.toml
• Параметры контроля доступа к инструментам: enabled, disabled_tools и default_tools_approval_mode
• Простую практику: пошаговое подключение бесплатного сервера документации Context7 с проверкой результатов

⚠️ Все консольные команды, ключи конфигурации и значения по умолчанию приведены согласно официальной документации Codex. Версии пакетов и имена моделей могут меняться, ориентируйтесь на фактические названия в вашей системе.

---

01 Какую проблему Codex решает протокол MCP

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

Вспомните предыдущие главы: вся работа Codex сводилась к чтению локальных файлов, компиляции кода и выполнению консольных команд. Агент изолирован на вашем ПК. Он не видит дизайн-макеты в Figma, не может прочитать свежую документацию по библиотеке из интернета и не может управлять вашим браузером. Для работы с этими инструментами вам приходилось вручную копировать текст или прикреплять скриншоты в чат.

Аналогия: переходник USB-C для современного смартфона. Большинство телефонов имеют единственный порт Type-C. Если вы хотите подключить флеш-накопитель, карту памяти SD или вывести картинку через HDMI на монитор, физически вы не сможете этого сделать. Вам нужен переходник — один штекер вставляется в телефон, а на выходе вы получаете полный набор нужных разъемов. Протокол MCP (Model Context Protocol — открытый стандарт интеграции AI с внешними системами) выступает в роли такого переходника для Codex: одно подключение открывает доступ ко всему стеку нужных программ.

Официальное описание протокола:

Model Context Protocol（MCP） 把模型连到工具和上下文。用它给 Codex 接上第三方文档，或者让它跟你的浏览器、Figma 这类开发者工具交互。

Ключевое слово здесь — стандартизация. MCP не является закрытым проприетарным решением OpenAI, это открытая спецификация. Главный плюс — универсальность интеграции: созданный для определенного инструмента сервер MCP будет одинаково работать в Codex, Claude Code, Cursor и других клиентах. Codex поддерживает стандартный протокол MCP, меняется лишь способ описания настроек (что мы разберем в разделе 03).

Важная системная особенность Codex: агент считывает поле instructions (инструкции), возвращаемое сервером при инициализации. Он использует его как руководство по работе с сервером: там описываются доступные цепочки вызовов, ограничения и лимиты запросов. Иными словами, хорошо спроектированный сервер поставляется с собственной инструкцией по эксплуатации, которую Codex считывает автоматически.

Когда следует настраивать сервер MCP? Правило простое: как только вы ловите себя на постоянном ручном копировании логов или описаний из сторонних утилит в чат Codex. Примеры использования:

• Интеграция с Figma для автоматического переноса стилей макета в верстку напрямую;
• Подключение серверов актуальной документации API для исключения устаревших галлюцинаций модели;
• Управление реальным браузером для автоматического снятия скриншотов рендеринга на мобильных разрешениях.

💡 Резюме одной фразой: по умолчанию Codex работает только с локальными файлами и консолью, ему недоступны макеты дизайна, свежая документация и сторонние API. Протокол MCP выступает в роли универсального хаба, открывая агенту доступ к внешним инструментам и считывая их встроенные инструкции.

На схеме показано: Codex по умолчанию имеет доступ только к файлам и командам CLI. Интерфейс MCP выступает в роли USB-концентратора, связывая агента с базами данных, Figma, GitHub и сторонними API.

---

02 Два формата серверов: локальные процессы и облачные подключения

Серверы MCP разделяются на типы. Понимание их различий определит способ конфигурирования. Главный вопрос: запускается ли сервер локально на вашем ПК или размещен по сетевому адресу?

Аналогия: бытовые приборы в доме. Одни работают напрямую от розетки (локальные), а другие требуют подключения к Wi-Fi для связи с облачным сервером (умный дом). Серверы MCP делятся по тому же принципу: одни запускаются как локальные процессы на вашем компьютере, другие представляют собой удаленные веб-службы.

В спецификации Codex поддерживаются два типа серверов:

Тип сервера	Где запускается	Способ запуска	Область применения
STDIO (локальный процесс)	На вашем компьютере, запускается как фоновый процесс	Задается команда запуска (например, npx ...)	Работа с локальными файлами, браузером или внутренними утилитами
Streamable HTTP (облачный)	По сетевому адресу (URL)	Задается адрес хоста (URL)	Облачные сервисы, удаленная документация, интеграция с Figma (требует авторизации)

Разберем важные нюансы настройки:

Для работы STDIO-сервера критична команда запуска. Этот тип работает по принципу фонового процесса, который запускает сам Codex. Вы указываете системную команду (например, npx -y @upstash/context7-mcp), и Codex запускает этот процесс при старте сессии. Окружение для команды должно быть установлено на вашем ПК (в данном примере требуется Node.js для работы npx). Для STDIO-серверов можно прописывать локальные переменные окружения (env) для передачи служебных ключей.

HTTP-серверы используются для интеграции с облачными службами и поддерживают два типа авторизации:

• Bearer token: в конфигурационном файле указывается имя переменной окружения, хранящей токен авторизации;
• OAuth: для серверов с поддержкой OAuth выполняется консольная авторизация через команду codex mcp login <имя_сервера>.

Облачные серверы (например, Figma) подключаются по сетевому адресу URL с передачей авторизации, не требуя установки локальных пакетов на ваш ПК.

Важная особенность: в отличие от других клиентов (например, Claude Code, поддерживающего устаревший протокол SSE), Codex ориентирован строго на спецификации STDIO и Streamable HTTP. Это упрощает настройку и снижает риск ошибок совместимости.

Схема работы двух вариантов интеграции:

Слева показана локальная работа: Codex запускает фоновый процесс STDIO, который взаимодействует с файловой системой и локальными программами. Справа показана облачная работа: Codex связывается с удаленным HTTP-сервером по сетевому адресу с использованием авторизации.

💡 Резюме одной фразой: для локальных утилит используется тип STDIO (через команду запуска в фоне при наличии окружения), для облачных служб — Streamable HTTP (через указание URL и авторизацию по токену или команде codex mcp login). Другие способы передачи данных в Codex не используются.

---

03 Добавление сервера: параметры командной строки vs ручная запись в config.toml

Рассмотрим способы настройки. Запомните главное системное правило: все параметры серверов MCP сохраняются в файл config.toml.

Официальная формулировка:

Codex stores MCP configuration in config.toml alongside other configuration options. The default is ~/.codex/config.toml, but you can also use .codex/config.toml to scoped MCP servers to a specific project.

Это снимает путаницу с флагом --scope: область действия серверов определяется исключительно тем, в каком каталоге объявлены параметры:

Расположение настроек	Область действия	Логика применения
Глобально в ~/.codex/config.toml	Во всех проектах	«Инструменты моего постоянного окружения»
Локально в .codex/config.toml проекта	Только в текущем каталоге (требует доверия)	«Специфичные серверы для конкретного проекта»

Разработчики подчеркивают: консоль (CLI) и расширения IDE используют общую конфигурацию. Сервер, настроенный через терминал, будет мгновенно доступен в расширении Codex для VS Code без дополнительной настройки.

Требование доверия к проекту является системным ограничением (описано в главах 15 и 16). Локальный файл .codex/config.toml игнорируется в каталогах без подтвержденного доверия. Это исключает автоматический запуск вредоносных серверов при клонировании чужих репозиториев.

Способ 1. Использование команд CLI (быстрая интеграция)

Для добавления STDIO-сервера используется команда codex mcp add. Обратите внимание: команда запуска сервера передается после двойного дефиса --:

codex mcp add <server-name> --env VAR1=VALUE1 -- <stdio 启动命令>

Пример добавления бесплатного сервера документации Context7:

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

Параметр npx -y @upstash/context7-mcp указывает команду запуска в фоне (флаг -y отключает интерактивные вопросы npm). Список всех доступных команд управления серверами выводится через codex mcp --help. Авторизация в облачных серверах после добавления выполняется через codex mcp login <имя_сервера>.

Для проверки списка активных серверов внутри сессии Codex используется斜杠-команда:

/mcp

Способ 2. Ручное редактирование config.toml (тонкая настройка)

Если вам нужно переопределить лимиты времени или ограничить список инструментов, пропишите параметры напрямую в файл настроек. Каждый сервер объявляется в своей секции вида [mcp_servers.<имя_сервера>].

Описание STDIO-сервера (эквивалент примера выше):

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

Параметры транслируются напрямую: command задает исполняемый файл, args — массив аргументов запуска. Также поддерживаются ключи env (переменные среды), cwd (рабочая директория) и env_vars (разрешенные к пересылке системные переменные).

Описание Streamable HTTP-сервера (на примере интеграции с Figma):

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Параметр url содержит сетевой адрес сервера, а bearer_token_env_var указывает системную переменную, хранящую токен доступа. Сам токен не записывается в конфигурационный файл в целях безопасности (защита от коммита секретов в Git).

Настройки MCP являются частью общего конфигурационного файла config.toml (секция mcp_servers), разбор которого представлен в главе 18. Команда codex mcp add просто автоматизирует запись этих секций в файл.

💡 Резюме одной фразой: в Codex отсутствует параметр --scope. Область действия серверов MCP определяется расположением файла конфигурации (в ~/.codex/config.toml глобально или в .codex/config.toml локально при наличии доверия к папке). Добавление выполняется командой codex mcp add (команда запуска указывается после --) или ручным описанием разделов [mcp_servers]. CLI и IDE делят одну конфигурацию.

---

04 Контроль доступа к серверу: ограничение инструментов и настройки авторизации

Добавление сервера не означает предоставление ему неограниченных прав. В файле config.toml доступен набор параметров для контроля доступа серверов к системе: лимиты времени, доступные инструменты и правила запросов подтверждения.

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

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

Параметр	Назначение	Значение по умолчанию / Варианты
enabled	Временное отключение сервера без удаления конфигурации	Логический флаг (установите false)
enabled_tools	Белый список (разрешены только эти инструменты)	По умолчанию разрешено всё
disabled_tools	Черный список (накладывается поверх белого списка)	—
default_tools_approval_mode	Правило согласования вызовов инструментов	auto / prompt / approve
startup_timeout_sec	Лимит времени на запуск сервера (в секундах)	10 по умолчанию
tool_timeout_sec	Лимит времени выполнения инструмента (в секундах)	60 по умолчанию

Важные нюансы настройки:

Черный список применяется поверх белого. Согласно документации, ограничения disabled_tools накладываются после анализа enabled_tools. Это позволяет сначала открыть группу инструментов, а затем точечно заблокировать небезопасные. Пример с Chrome DevTools демонстрирует это: белый список enabled_tools = ["open", "screenshot"] разрешает две операции, но черный список disabled_tools = ["screenshot"] блокирует снятие скриншотов, оставляя активным только запуск браузера.

Три режима согласования default_tools_approval_mode регулируют запросы подтверждения вызовов:

• auto: автоматический выбор режима безопасности силами Codex;
• prompt: каждый вызов инструмента требует подтверждения пользователя в чате;
• approve: вызовы разрешены без запросов подтверждения (полное доверие).

Параметры согласования можно переопределять точечно для отдельных инструментов с помощью секции tools.<имя_инструмента>.approval_mode. Например, можно разрешить автоматическое чтение данных, но требовать согласования для вызовов инструментов записи.

Контролируйте лимиты времени. По умолчанию на холодный старт сервера отводится 10 секунд, а на выполнение операции — 60 секунд. Если ваш локальный сервер запускается медленно, Codex оборвет соединение по таймауту. В этом случае увеличьте значения лимитов:

[mcp_servers.slow_server]
command = "python"
args = ["-m", "slow_server"]
startup_timeout_sec = 30   # Увеличиваем время ожидания запуска
tool_timeout_sec = 120     # Увеличиваем лимит времени выполнения

Пример тонкой настройки безопасности сервера в конфигурационном файле:

[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
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"                # Для открытия страниц подтверждение не требуется

💡 Резюме одной фразой: файл config.toml позволяет гибко контролировать безопасность: параметр enabled отключает сервер, списки enabled_tools и disabled_tools настраивают доступ к утилитам (белый список имеет приоритет), ключ default_tools_approval_mode задает уровень согласования (auto/prompt/approve с возможностью точечного переопределения для конкретного инструмента). Лимиты запуска по умолчанию составляют 10 и 60 секунд.

---

05 Безопасность при подключении сторонних серверов

Этот короткий раздел критически важен для понимания общих рисков системы безопасности (продолжение темы главы 16).

Серверы MCP разрабатываются сторонними авторами, OpenAI не проводит аудит их безопасности. Подключение STDIO-сервера означает запуск стороннего исполняемого файла на вашем компьютере от имени вашей учетной записи. Подключение HTTP-сервера открывает агенту доступ к внешним сетевым данным. Обе операции требуют осознанного подхода.

Аналогия: установка сторонних зависимостей npm в рабочий проект. Вы не будете устанавливать малоизвестный пакет без проверок и истории обновлений напрямую в боевой код. Тот же подход применим к серверам MCP: проверяйте их авторов и исходный код перед установкой, особенно для серверов, работающих с сетевым парсингом.

Почему серверы парсинга опаснее? Они являются основным вектором атак класса внедрения промптов (prompt injection). Сторонний сайт или документ может содержать невидимый для человека текст с инструкциями для AI. При чтении этой страницы через MCP-сервер Codex воспримет эти инструкции как команды пользователя и может выполнить небезопасные действия. Именно для защиты от таких атак служат белые списки инструментов и режимы согласования вызовов. Блокировка опасных операций и перевод вызовов в режим согласования prompt снижают риски.

Базовые правила оценки безопасности серверов:

Сценарий	Решение
Серверы, рекомендованные в документации (OpenAI Docs, Context7, Figma, Playwright)	✅ Безопасно
Официальные серверы крупных платформ (GitHub, Sentry)	✅ Безопасно
Малоизвестные серверы сторонних авторов на GitHub	⚠️ Изучите исходный код перед подключением
Активация автосогласования default_tools_approval_mode = "approve"	⚠️ Применяйте только для полностью доверенных серверов
Предоставление серверу прав записи в рабочие базы данных	❌ Ограничивайте доступ режимом «только чтение»

Правило минимизации привилегий: всегда ограничивайте доступ серверов режимом «только чтение» при наличии выбора. Это лучший способ защиты данных. Системные барьеры песочницы Codex защищают файлы ОС, но они не заменяют вашу личную бдительность при настройке серверов.

💡 Резюме одной фразой: серверы MCP являются сторонним кодом, OpenAI не проводит их аудит. Доверяйте только проверенным источникам, с осторожностью относитесь к серверам сетевого парсинга из-за угроз внедрения промптов, настраивайте режим prompt по умолчанию и ограничивайте доступ режимом только чтения.

---

06 Практика: подключение и проверка сервера документации Context7

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

Предварительные требования: сервер запускается через утилиту npx, поэтому на вашем компьютере должен быть установлен Node.js (проверьте работу команды node -v в консоли). Сервер выполняет запросы к документации в сети, при сбоях проверьте доступность сети. Команда запуска указана согласно актуальной спецификации.

Шаг 1. Добавляем сервер в конфигурацию (команда запускается в терминале, а не в чате Codex)

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

Ожидаемый результат: терминал подтвердит успешное добавление сервера context7. Эта команда автоматически прописала секцию [mcp_servers.context7] в глобальный файл ~/.codex/config.toml (вы можете открыть его текстовым редактором для проверки).

Шаг 2. Запускаем сессию и проверяем активность интеграции

codex

Внутри чата введите команду просмотра серверов:

/mcp

Ожидаемый результат: в списке доступных интеграций отобразится сервер context7. Это подтверждает корректность настройки. При отсутствии сервера проверьте установку Node.js и доступ к сети.

Шаг 3. Запрос на поиск свежих данных

Отправьте текстовый запрос с явным указанием использовать подключенный сервер (это заставит Codex обратиться к MCP вместо генерации ответа по памяти):

用 Context7 查一下某个库（比如 React Router）最新版的路由配置该怎么写，把官方文档里的写法贴给我。

Ожидаемый результат: Codex вызовет инструменты сервера Context7 для поиска данных. При первом обращении система приостановит выполнение и выведет запрос на согласование доступа к инструменту (согласно настройкам безопасности). Подтвердите доступ. Codex выведет актуальную структуру кода со ссылкой на источник.

Шаг 4. Отключение сервера (опционально)

Для удаления сервера вы можете использовать консольные команды (список команд выводится через codex mcp --help) или вручную стереть секцию [mcp_servers.context7] из глобального файла ~/.codex/config.toml (также можно временно отключить сервер, прописав в его секцию флаг enabled = false).

Мы прошли базовую цепочку работы: добавление интеграции → контроль статуса в сессии → вызов с согласованием → удаление. Любые другие серверы настраиваются по этой логике.

💡 Резюме одной фразой: подключите сервер Context7 для тренировки («добавление через CLI → проверка статуса по команде /mcp → тестовый запрос с подтверждением вызова → отключение в config.toml»). Это даст практический опыт работы с протоколом.

---

07 Итоги

Мы разобрали интеграцию Codex с внешними инструментами с помощью открытого стандарта Model Context Protocol (MCP).

Повторим ключевые выводы:

Задача	Инструмент	Ключевой нюанс
Назначение MCP	Открытый стандарт интеграции	По умолчанию Codex изолирован; MCP подключает сторонние базы знаний и считывает инструкции instructions
Локальные утилиты	Сервер STDIO	Запускается через команду CLI при наличии нужного окружения на ПК
Облачные сервисы	Сервер Streamable HTTP	Подключается по URL; авторизация по токену или команде codex mcp login
Область действия	Путь к файлу настроек	Флаг --scope не поддерживается; область действия зависит от каталога размещения config.toml
Добавление сервера	Команда CLI или config.toml	Параметры пишутся после -- в консоли; CLI и IDE используют один файл настроек
Контроль безопасности	Параметры в config.toml	Флаг enabled, списки разрешений, уровень согласования и лимиты времени
Доверие к серверам	Оценка рисков	Аудит стороннего кода не проводится; защищайтесь от внедрения промптов, ставьте режим prompt и доступ read-only

Теперь вы умеете: определять круг задач для протокола MCP, настраивать серверы STDIO и HTTP, распределять область их действия через каталоги config.toml вместо флага --scope. Вы умеете добавлять интеграции через codex mcp add и редактировать их параметры вручную, проверять статус серверов через /mcp и контролировать безопасность с помощью белых/черных списков и уровней согласования. Использование MCP превращает Codex из изолированного редактора в полноценного агента управления вашей рабочей инфраструктурой.

Запомните главное: в Codex нет флага --scope, все настройки завязаны на файлы config.toml, а команда запуска сервера в CLI пишется после символов --. Это убережет вас от ошибок при конфигурировании.

---

В следующей статье — [21 · Субагенты (Subagents)]. Серверы MCP расширяют возможности Codex, но при больших объемах работы контекст диалога с одной моделью быстро перегружается. В следующей главе мы разберем метод распределения задач: вместо одного агента мы запустим пул специализированных субагентов с изолированным контекстом. Главный агент распределяет задачи, а субагенты выполняют их параллельно без засорения общей сессии. Разделение задач на сборку, тесты и поиск информации между независимыми субагентами существенно ускоряет разработку.

---

Рекомендуемое чтение

• Четыре типовых рабочих сценария: исследование, багфиксинг, рефакторинг и тесты
• Выбор моделей: какую модель использовать под конкретную задачу
• Инструкция AGENTS.md: автоматизация правил на старте сессии