Документация ChatGPT
Русский
Связаться goolvyouyou@gmail.com

Model Context Protocol

Предоставьте Codex доступ к сторонним инструментам и контексту

Model Context Protocol (MCP) связывает модели с инструментами и контекстом. Используйте его, чтобы предоставить ChatGPT или Codex доступ к сторонней документации либо позволить им взаимодействовать с инструментами разработчика, например с вашим браузером или Figma.

Веб-версия ChatGPT может использовать удалённые инструменты на основе MCP, предоставляемые плагинами. После установки плагина режимы Chat и Work могут использовать входящие в него коннекторы и удалённые инструменты MCP. Откройте вкладку Plugins, чтобы просматривать доступные инструменты и управлять ими. Локальные клиенты Codex также могут напрямую подключаться к MCP servers и совместно использовать их конфигурацию.

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

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

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

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

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

Подключение Codex к MCP server

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

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

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

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

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

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

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

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

Codex кэширует вспомогательные заголовки для подключения. Если запрос POST к тому же источнику возвращает 401 или 403, Codex один раз обновляет заголовки и повторяет запрос, только если вспомогательная команда вернула изменённые значения. Явно заданные bearer-токены и учётные данные 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 servers при создании исходного каталога инструментов. Его значение по умолчанию — 1000 миллисекунд. Установите значение 0, чтобы для каждого сервера ожидать в течение его startup_timeout_sec. Для обязательных серверов по-прежнему используются их тайм-ауты запуска.

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

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

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 и метаданных сервера авторизации:

Конфигурация OAuth Поддержка издателя Используемый обратный вызов
callback_url без client_id Поддерживается Настроенный обратный вызов используется для регистрации клиента.
callback_url без client_id Не поддерживается Настроенный обратный вызов используется для регистрации клиента с добавлением зависящего от сервера идентификатора обратного вызова.
client_id и callback_url Поддерживается Настроенный обратный вызов используется повторно; ответ авторизации должен содержать соответствующее значение iss.
client_id и callback_url, оканчивающийся правильным идентификатором обратного вызова Не поддерживается Настроенный обратный вызов используется повторно без изменений.
client_id и callback_url без правильного идентификатора обратного вызова Не поддерживается Настроенный обратный вызов игнорируется. Codex использует mcp_oauth_callback_url или, если он не задан, http://127.0.0.1/callback, добавляя идентификатор обратного вызова.
client_id без настроенного callback_url Поддерживается или не поддерживается Codex использует глобальный или стандартный обратный вызов, добавляя зависящий от сервера идентификатор обратного вызова.

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

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

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

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

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

Если MCP server объявляет 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 CLI использует размещённый в ChatGPT документ метаданных, предназначенный для конкретного MCP server:

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

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

Codex CLI также поддерживает стабильный общий документ CIMD:

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

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

Чтобы выбрать способ регистрации для одного входа через 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 servers, предоставляемые плагинами

Установленные плагины могут включать MCP servers в свой манифест. Эти серверы запускаются из плагина, поэтому пользовательская конфигурация не задаёт для них команду транспорта. При этом в пользовательской конфигурации по-прежнему можно управлять включением и отключением, а также политикой инструментов в разделе 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 servers, предоставляемые плагинами, также могут объявлять настройки 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 servers, предоставляемые плагинами, следуют тем же правилам выбора обратного вызова, что и другие MCP servers. Если плагин предоставляет 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 servers

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

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