Model Context Protocol

Настольное приложение ChatGPT, Codex CLI и расширение IDE поддерживают серверы MCP и совместно используют конфигурацию MCP для одного и того же хоста Codex.

Перечисленные ниже поддерживаемые возможности серверов относятся к серверам MCP, настроенным на хосте Codex. Инструменты размещённых плагинов могут иметь другие возможности.

Поддерживаемые возможности MCP

• Серверы STDIO: серверы, работающие как локальный процесс (запускаемый командой).
  • Переменные окружения
• Потоковые HTTP-серверы: серверы, к которым вы обращаетесь по адресу.
  • Аутентификация с помощью токена Bearer
  • Аутентификация OAuth, включая Client ID Metadata Documents (CIMD) и Dynamic Client Registration (DCR)
  • Аутентификация сеанса ChatGPT для доверенных серверов первой стороны
• Инструкции сервера: Codex считывает поле MCP instructions, возвращенное при инициализации, и использует его вместе с инструментами сервера как общие инструкции для всего сервера.

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

Подключение Codex к серверу MCP

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

Настольное приложение ChatGPT, Codex CLI и расширение IDE совместно используют эту конфигурацию. Настроив серверы MCP, вы сможете переключаться между этими клиентами без повторной настройки.

Настройка в настольном приложении ChatGPT

1. Откройте Настройки, затем выберите Серверы MCP.
2. Выберите Добавить сервер.
3. Введите имя, выберите STDIO или Streamable HTTP и укажите команду сервера или URL.
4. Сохраните сервер, затем выберите Перезапустить.

В списке серверов указано, какие серверы включены и для каких требуется OAuth. Выберите Аутентифицироваться, если для сервера OAuth необходимо войти в систему. В поле ввода сообщения введите /mcp, чтобы просмотреть подключённые серверы.

Использование инструментов на базе MCP в веб-версии ChatGPT

В размещённом в облаке чате ChatGPT Work установите плагин, чтобы использовать входящие в его состав коннекторы и удалённые инструменты MCP. После установки Chat и Work смогут использовать эти инструменты. Администраторы рабочего пространства могут управлять доступностью плагинов и инструментов.

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

Настройка с помощью CLI

Добавление сервера MCP

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

Например, чтобы добавить Context7 (бесплатный сервер MCP с документацией для разработчиков), выполните следующую команду:

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

Другие команды CLI

Выполните codex mcp list, чтобы просмотреть настроенные серверы. Чтобы увидеть все доступные команды MCP, выполните codex mcp --help. Для сервера, поддерживающего OAuth, выполните codex mcp login <server-name>.

Терминальный интерфейс (TUI)

В TUI codex используйте /mcp, чтобы просмотреть активные серверы MCP.

Настройка в расширении IDE

1. Откройте меню со значком шестерёнки, затем выберите Серверы MCP.
2. Выберите Добавить сервер.
3. Введите имя, выберите STDIO или Streamable HTTP и укажите команду сервера или URL.
4. Сохраните сервер, затем выберите Перезапустить расширение.

В списке серверов MCP указано, какие серверы включены и каким из них требуется OAuth. Выберите Аутентифицироваться, когда сервер OAuth потребует входа.

Настройка с помощью config.toml

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

Настройте каждый сервер MCP с помощью таблицы [mcp_servers.<server-name>] в файле конфигурации.

Серверы STDIO

• command (обязательно): команда, запускающая сервер.
• args (необязательно): аргументы, передаваемые серверу.
• env (необязательно): переменные окружения, задаваемые для сервера.
• env_vars (необязательно): переменные окружения, которые разрешено передавать.
• cwd (необязательно): рабочий каталог, из которого запускается сервер.
• experimental_environment (необязательно): задайте remote, чтобы запускать сервер stdio через удалённую среду выполнения, если она доступна.

env_vars может содержать простые имена переменных или объекты с указанием источника:

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

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

Серверы Streamable HTTP

• url (обязательно): адрес сервера.
• auth (необязательно): способ аутентификации, который следует попробовать после настроенных токенов-носителей и заголовков авторизации. Используйте oauth (значение по умолчанию) для сохранённых учётных данных MCP OAuth. Используйте chatgpt, чтобы задействовать текущий сеанс ChatGPT для доверенного источника ChatGPT первой стороны, используя сохранённые данные OAuth как резервный вариант.
• bearer_token_env_var (необязательно): имя переменной окружения с токеном-носителем, отправляемым в Authorization.
• http_headers (необязательно): сопоставление имён заголовков со статическими значениями.
• env_http_headers (необязательно): сопоставление имён заголовков с именами переменных окружения (значения извлекаются из окружения).
• http_headers_helper (необязательно): локальная команда, которая выводит объект JSON с именами заголовков и строковыми значениями, например {"X-Auth": "temporary-token"}. Поддерживается для подключений HTTP MCP из локального окружения, но не для серверов stdio или подключений через удалённое окружение выполнения.

Codex кэширует вспомогательные заголовки для подключения. Если запрос POST к тому же источнику возвращает 401 или 403, Codex один раз обновляет заголовки и повторяет запрос, только если вспомогательная команда вернула изменённые значения. Явно заданные токены-носители и учётные данные OAuth имеют приоритет перед заголовком Authorization, предоставленным вспомогательной командой. Ответ OAuth 403, сообщающий о недостаточных разрешениях, не запускает обновление вспомогательных заголовков.

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

Другие параметры конфигурации

• startup_timeout_sec (необязательно): время ожидания запуска сервера (в секундах). По умолчанию: 10.
• tool_timeout_sec (необязательно): время ожидания выполнения инструмента сервером (в секундах). По умолчанию: 60.
• enabled (необязательно): установите значение false, чтобы отключить сервер, не удаляя его.
• required (необязательно): установите значение true, чтобы запуск завершался ошибкой, если этот включённый сервер не удаётся инициализировать.
• enabled_tools (необязательно): список разрешённых инструментов.
• disabled_tools (необязательно): список запрещённых инструментов (применяется после enabled_tools).
• default_tools_approval_mode (необязательно): поведение по умолчанию при подтверждении использования инструментов этого сервера. Поддерживаемые значения: auto, prompt, writes и approve. В режиме writes запрашивается подтверждение для инструментов, не помеченных как доступные только для чтения.
• tools.<tool>.approval_mode (необязательно): переопределение поведения подтверждения для отдельного инструмента.
• tools.<tool>.output_token_limit (необязательно): положительный бюджет токенов для вывода одного инструмента до применения стандартного 20%-ного запаса на сериализацию. Переопределяет установленный моделью бюджет усечения вывода по умолчанию для этого инструмента.

Параметр верхнего уровня mcp_optional_startup_grace_ms определяет, как долго Codex ожидает необязательные серверы MCP при создании исходного каталога инструментов. Его значение по умолчанию — 1000 миллисекунд. Установите значение 0, чтобы для каждого сервера ожидать в течение его startup_timeout_sec. Для обязательных серверов по-прежнему используются их тайм-ауты запуска.

Регистрация клиента OAuth и обратные вызовы

Если сервер авторизации требует предварительно зарегистрированного клиента OAuth, укажите его идентификатор клиента при добавлении MCP-сервера:

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

Codex отображает полный URL обратного вызова, который необходимо зарегистрировать у вашего провайдера:

OAuth callback URL: http://127.0.0.1/callback

Codex сохраняет обратный вызов вместе с идентификатором клиента в config.toml для последующих входов:

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

Недавно добавленные предварительно зарегистрированные клиенты используют стабильный обратный вызов, только если сервер авторизации объявляет поддержку authorization_response_iss_parameter_supported: true и предоставляет в метаданных issuer. Если поддержка издателя не объявлена, Codex добавляет зависящий от сервера идентификатор обратного вызова, например http://127.0.0.1/callback/XuuuHAzzHOni. Существующие клиенты без сохранённого обратного вызова продолжают использовать перенаправление с собственным идентификатором обратного вызова.

Во время входа выбор обратного вызова зависит от конфигурации OAuth и метаданных сервера авторизации:

Резервный вариант не изменяет сохранённый URL обратного вызова. Codex вычисляет идентификатор обратного вызова из URL MCP-сервера, включая путь и строку запроса. Одинаковые правила выбора применяются при автоматическом и явном входе.

Задайте mcp_oauth_callback_url, если вам нужен собственный путь обратного вызова или URL удалённой точки входа Devbox. Недавно добавленные предварительно зарегистрированные клиенты используют этот URL без изменений, если их провайдер поддерживает идентификацию издателя. В противном случае они используют настроенный URL с добавлением зависящего от сервера идентификатора обратного вызова. Всегда регистрируйте точный обратный вызов, отображаемый командой codex mcp add.

Для обратных вызовов http://127.0.0.1 без порта Codex не включает порт прослушивания в отображаемый и сохраняемый URL, а затем подставляет активный порт прослушивания во время авторизации. Эта подстановка не применяется к localhost, хостам IPv6, URL HTTPS и обратным вызовам, в которых порт уже указан. Серверы авторизации должны принимать переменные порты loopback-интерфейса согласно разделу 7.3 RFC 8252.

Задайте mcp_oauth_callback_port, чтобы выбрать фиксированный глобальный порт прослушивания, или задайте mcp_servers.<server-name>.oauth.callback_port, чтобы переопределить его для одного сервера. Явно указанный порт в URL обратного вызова не настраивает прослушиватель. Для прямого обратного вызова через loopback-интерфейс используйте http://127.0.0.1 без порта или настройте один и тот же явно указанный порт как для URL обратного вызова, так и для прослушивателя. Обратный вызов через прокси может намеренно использовать порт внешнего URL, отличный от порта локального прослушивателя. Локальные URL обратного вызова привязываются к локальному интерфейсу, а нелокальные — к 0.0.0.0.

Codex проверяет любое возвращённое значение iss перед обменом кода авторизации. При несовпадении iss ответ всегда отклоняется. Если объявлена поддержка издателя, ответ также отклоняется при отсутствии iss. Ни при одной из этих ошибок код не обменивается и другой обратный вызов не используется. Некорректный URL обратного вызова или объявленная поддержка издателя при отсутствии издателя в метаданных также приводят к безусловной ошибке. См. раздел Аутентификация пользователей.

Если сервер MCP объявляет scopes_supported, Codex отдаёт предпочтение этим областям доступа, объявленным сервером, при входе через OAuth. В противном случае Codex использует области доступа, настроенные в config.toml.

Регистрация клиента OAuth

Codex поддерживает OAuth Client ID Metadata Documents (CIMD) и Dynamic Client Registration (DCR). По умолчанию Codex автоматически выбирает CIMD, если сервер авторизации объявляет client_id_metadata_document_supported: true, включает none в token_endpoint_auth_methods_supported, а обратный вызов использует поддерживаемый URL интерфейса обратной петли. В противном случае Codex использует DCR, если он доступен. Настроенный ID клиента OAuth всегда имеет приоритет и исключает регистрацию клиента.

Для CIMD Codex использует размещённый в ChatGPT документ метаданных, относящийся к конкретному MCP- серверу:

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex формирует <callback_id> на основе URL MCP-сервера и включает его в URI перенаправления на loopback-адрес, например http://127.0.0.1:<port>/callback/<callback_id>. В документе метаданных регистрируется соответствующий loopback URI без порта. Серверы авторизации должны принимать порт, выбранный при входе, при этом требуя точного совпадения хоста и пути, как предписано RFC 8252. Для нестандартных хостов, путей или параметров запроса callback требуются DCR либо настроенный OAuth client ID.

Поддержка стабильного общего документа CIMD находится в разработке и скоро появится:

https://chatgpt.com/oauth/codex/client.json

Codex будет использовать стабильный документ с общим путём /callback, если сервер авторизации объявляет authorization_response_iss_parameter_supported: true, предоставляет допустимый issuer в своих метаданных и включает соответствующий iss в ответы авторизации. Серверы без ответов, привязанных к издателю, продолжат использовать документ для конкретного callback.

Чтобы выбрать способ регистрации для одного входа через CLI, используйте --oauth-client-registration:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

По умолчанию используется auto. Выбор способа регистрации применяется только к текущему входу и не сохраняется в config.toml.

Примеры config.toml

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

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

# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

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

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after 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"
output_token_limit = 30000

Серверы MCP, предоставляемые плагинами

Установленные плагины могут включать серверы MCP в свой манифест. Эти серверы запускаются из плагина, поэтому пользовательская конфигурация не задаёт для них команду транспорта. При этом в пользовательской конфигурации по-прежнему можно управлять включением и отключением, а также политикой инструментов в разделе plugins.<plugin>.mcp_servers.<server>.

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

HTTP MCP-серверы, предоставляемые плагинами, также могут объявлять настройки OAuth в .mcp.json. В манифестах плагинов используются имена полей в camelCase: clientId, callbackUrl и callbackPort:

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

MCP-серверы, предоставляемые плагинами, следуют тем же правилам выбора обратного вызова, что и другие MCP-серверы. Если плагин предоставляет clientId, его провайдер не поддерживает обратные вызовы, привязанные к издателю, а в callbackUrl отсутствует зависящий от сервера идентификатор обратного вызова, Codex игнорирует этот URL при входе и использует mcp_oauth_callback_url или, если он не задан, http://127.0.0.1/callback, добавляя идентификатор обратного вызова. Настроенное значение callbackUrl остаётся без изменений.

Значение oauth.callbackPort плагина переопределяет глобальное mcp_oauth_callback_port; если не задано ни одно из них, Codex выбирает эфемерный порт. Порт, указанный в callbackUrl, не определяет порт прослушивателя. Для прямого обратного вызова через loopback-интерфейс с фиксированным портом настройте оба значения одинаково:

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

При использовании удалённой точки входа или другого прокси порт URL обратного вызова и порт локального прослушивателя могут намеренно различаться, если прокси перенаправляет запросы настроенному прослушивателю.

Примеры полезных серверов MCP

Список серверов MCP продолжает расти. Вот несколько распространённых вариантов:

• OpenAI Docs MCP: поиск и чтение документации OpenAI для разработчиков.
• Context7: подключение к актуальной документации для разработчиков.
• Figma: локальный и удалённый доступ к вашим макетам Figma.
• Playwright: управление браузером и его исследование с помощью Playwright.
• Инструменты разработчика Chrome: управление Chrome и его исследование.
• Sentry: доступ к журналам Sentry.
• GitHub: управление возможностями GitHub, выходящими за рамки поддерживаемых git (например, запросами на слияние и задачами).