Model Context Protocol

La aplicación de escritorio de ChatGPT, Codex CLI y la extensión para IDE admiten MCP servers y comparten la configuración de MCP para el mismo host de Codex.

Las funciones de servidor admitidas que se indican a continuación se aplican a los MCP servers configurados en un host de Codex. Las herramientas de plugins alojadas pueden tener capacidades diferentes.

Funciones de MCP admitidas

• Servidores STDIO: servidores que se ejecutan como un proceso local (iniciado mediante un comando).
  • Variables de entorno
• Servidores HTTP transmitibles: servidores a los que accedes mediante una dirección.
  • Autenticación mediante token de portador
  • Autenticación OAuth, incluidos Client ID Metadata Documents (CIMD) y Dynamic Client Registration (DCR)
  • Autenticación de sesión de ChatGPT para servidores propios de confianza
• Instrucciones del servidor: Codex lee el campo instructions de MCP devuelto durante la inicialización y lo utiliza como orientación para todo el servidor junto con sus herramientas.

Si desarrollas o mantienes un MCP server para Codex, usa instructions para los flujos de trabajo entre herramientas, las restricciones y los límites de frecuencia que se aplican a todo el servidor. Procura que los primeros 512 caracteres sean autosuficientes para que la orientación más importante esté disponible cuando Codex decida cómo usar el servidor.

Conectar Codex a un MCP server

Codex almacena la configuración de MCP en config.toml junto con otros ajustes de configuración de Codex. De forma predeterminada, se encuentra en ~/.codex/config.toml, pero también puedes limitar los MCP servers a un proyecto con .codex/config.toml (solo proyectos de confianza).

La aplicación de escritorio de ChatGPT, Codex CLI y la extensión para IDE comparten esta configuración. Una vez que configures tus MCP servers, podrás alternar entre esos clientes sin tener que repetir la configuración.

Configurar en la aplicación de escritorio de ChatGPT

1. Abre Configuración y selecciona MCP servers.
2. Selecciona Agregar servidor.
3. Introduce un nombre, elige STDIO o Streamable HTTP y proporciona el comando o la URL del servidor.
4. Guarda el servidor y selecciona Reiniciar.

La lista de servidores muestra cuáles están habilitados y cuáles requieren OAuth. Selecciona Autenticar cuando un servidor OAuth requiera iniciar sesión. En el cuadro de redacción, escribe /mcp para ver los servidores conectados.

Usa herramientas respaldadas por MCP en ChatGPT web

Continuar en otro dispositivo una conversación que utiliza el acceso al equipo local con Work Cloud no instala plugins ni concede acceso a las cuentas conectadas.

En el acceso al equipo local con Work Cloud, el requisito empresarial de TOML mcp_servers de Agent Security se aplica a los ejecutores locales. Los contenedores en la nube conservan las políticas de Work Cloud. Es posible que los MCP servers y los transportes locales no estén disponibles en la nube; comprueba la conectividad y la autenticación por separado.

Para los hooks empresariales en el acceso al equipo local con Work Cloud:

• Hooks empresariales. Cuando están habilitados en tu espacio de trabajo, el acceso al equipo local con Work Cloud admite hooks MCP definidos por los administradores que se ejecutan en el coordinador en la nube (orquestador) para los eventos compatibles del ciclo de vida y de las herramientas. La orquestación en la nube no admite hooks de comandos ni hooks de la configuración local o de plugins, incluso cuando las herramientas se ejecutan localmente.
• Auditoría. Antes de depender de estos hooks, prueba la conexión de callback, confirma los eventos que recibe y comprueba cómo afectan los fallos a la tarea. Los hooks MCP no proporcionan un registro de auditoría completo de Compliance API.
• Limitaciones: La orquestación en la nube no admite hooks de comandos ni hooks de la configuración local o de plugins, incluso cuando las herramientas se ejecutan localmente. Esta función no admite hooks para usuarios particulares. Cuando tanto la orquestación como la ejecución son locales, los hooks compatibles existentes siguen funcionando en los hilos exclusivamente locales de Work y Codex. Los administradores pueden seguir configurando hooks administrados compatibles en Agent Security para esos flujos de trabajo.

Consulta Hooks y la Referencia de configuración para conocer el alcance de la compatibilidad.

En un chat alojado de ChatGPT Work, instala un plugin para usar sus conectores incluidos y sus herramientas MCP remotas. Después de la instalación, Chat y Work pueden usar esas herramientas. Los administradores del espacio de trabajo pueden controlar qué plugins y herramientas están disponibles.

ChatGPT web no lee los archivos de configuración locales de Codex ni muestra el menú de comandos local de Codex. Abre la pestaña Plugins para explorar y administrar las herramientas disponibles.

Configura con la CLI

Añadir un MCP server

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

Por ejemplo, para añadir Context7 (un MCP server gratuito para documentación para desarrolladores), puedes ejecutar el siguiente comando:

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

Otros comandos de la CLI

Ejecuta codex mcp list para ver los servidores configurados. Para ver todos los comandos MCP disponibles, ejecuta codex mcp --help. Para un servidor compatible con OAuth, ejecuta codex mcp login <server-name>.

Interfaz de usuario de terminal (TUI)

En la TUI de codex, usa /mcp para ver tus MCP servers activos.

Configurar en la extensión del IDE

1. Abre el menú del engranaje y selecciona MCP servers.
2. Selecciona Añadir servidor.
3. Introduce un nombre, elige STDIO o HTTP transmisible y proporciona el comando o la URL del servidor.
4. Guarda el servidor y selecciona Reiniciar extensión.

La lista de MCP servers muestra cuáles están habilitados y cuáles requieren OAuth. Selecciona Autenticar cuando un servidor OAuth requiera iniciar sesión.

Configurar con config.toml

Para un control más detallado, edita ~/.codex/config.toml o un archivo .codex/config.toml limitado al proyecto. Consulta la referencia de configuración para acceder a una lista consultable de todas las opciones de MCP admitidas.

Configura cada MCP server con una tabla [mcp_servers.<server-name>] en el archivo de configuración.

Servidores STDIO

• command (obligatorio): el comando que inicia el servidor.
• args (opcional): argumentos que se pasarán al servidor.
• env (opcional): variables de entorno que se establecerán para el servidor.
• env_vars (opcional): variables de entorno que se permitirán y reenviarán.
• cwd (opcional): directorio de trabajo desde el que se iniciará el servidor.
• experimental_environment (opcional): establécelo en remote para iniciar el servidor stdio mediante un entorno de ejecución remoto cuando haya uno disponible.

env_vars puede contener nombres de variables simples u objetos con un origen:

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

Las entradas de cadena y source = "local" se leen del entorno local de Codex. source = "remote" se lee del entorno de ejecución remoto y requiere stdio de MCP remoto.

Servidores Streamable HTTP

• url (obligatorio): la dirección del servidor.
• auth (opcional): autenticación que se intentará después de los tokens de portador y los encabezados de autorización configurados. Usa oauth (el valor predeterminado) para las credenciales OAuth de MCP almacenadas. Usa chatgpt para utilizar la sesión actual de ChatGPT con el origen propio de confianza de ChatGPT y recurrir a OAuth almacenado como alternativa.
• bearer_token_env_var (opcional): nombre de la variable de entorno de un token de portador que se enviará en Authorization.
• http_headers (opcional): mapa de nombres de encabezados a valores estáticos.
• env_http_headers (opcional): mapa de nombres de encabezados a nombres de variables de entorno (los valores se obtienen del entorno).
• http_headers_helper (opcional): comando local que imprime un objeto JSON con nombres de encabezados y valores de cadena, como {"X-Auth": "temporary-token"}. Se admite para conexiones HTTP de MCP realizadas desde el entorno local, pero no para servidores stdio ni conexiones realizadas mediante un entorno de ejecución remoto.

Codex almacena en caché los encabezados auxiliares de la conexión. Cuando una solicitud POST al mismo origen devuelve 401 o 403, actualiza los encabezados una vez y solo vuelve a intentarlo si el comando auxiliar devuelve valores diferentes. Los tokens de portador explícitos y las credenciales OAuth tienen prioridad sobre un encabezado Authorization proporcionado por el comando auxiliar. Una respuesta OAuth 403 que indica un alcance insuficiente no activa una actualización del comando auxiliar.

Si no se resuelve ninguna fuente de credenciales, Codex puede conectarse al servidor sin autenticación. Ejecuta codex mcp login <server-name> por separado para iniciar un proceso de inicio de sesión OAuth de MCP.

Otras opciones de configuración

• startup_timeout_sec (opcional): tiempo de espera (en segundos) para que se inicie el servidor. Valor predeterminado: 10.
• tool_timeout_sec (opcional): tiempo de espera (en segundos) para que el servidor ejecute una herramienta. Valor predeterminado: 60.
• enabled (opcional): establece false para deshabilitar un servidor sin eliminarlo.
• required (opcional): establece true para que el inicio falle si este servidor habilitado no puede inicializarse.
• enabled_tools (opcional): lista de herramientas permitidas.
• disabled_tools (opcional): lista de herramientas denegadas (se aplica después de enabled_tools).
• default_tools_approval_mode (opcional): comportamiento de aprobación predeterminado para las herramientas de este servidor. Los valores admitidos son auto, prompt, writes y approve. El modo writes solicita confirmación para las herramientas que no están marcadas como de solo lectura.
• tools.<tool>.approval_mode (opcional): anulación del comportamiento de aprobación por herramienta.
• tools.<tool>.output_token_limit (opcional): presupuesto positivo de tokens para la salida de una herramienta, antes del margen de serialización estándar del 20 %. Anula el presupuesto predeterminado del modelo para truncar la salida de esa herramienta.

La configuración de nivel superior mcp_optional_startup_grace_ms controla cuánto tiempo espera Codex a los MCP servers opcionales al crear el catálogo inicial de herramientas. Su valor predeterminado es de 1000 milisegundos. Establécela en 0 para esperar el valor de startup_timeout_sec de cada servidor. Los servidores obligatorios siguen usando sus tiempos de espera de inicio.

Registro de clientes OAuth y devoluciones de llamada

Cuando tu servidor de autorización requiera un cliente OAuth registrado previamente, proporciona su ID de cliente al añadir el MCP server:

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

Para un cliente confidencial, pasa también --oauth-client-secret. Lee el secreto desde una variable de entorno:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Esta opción requiere un ID de cliente y un secreto que no estén vacíos. Codex guarda el secreto como mcp_servers.example.oauth.client_secret en config.toml. Mantén ese archivo privado y fuera del control de versiones.

Codex muestra la URL de devolución de llamada completa que debes registrar con tu proveedor:

OAuth callback URL: http://127.0.0.1/callback

Codex guarda la devolución de llamada junto con el ID de cliente en config.toml para futuros inicios de sesión:

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

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

Los clientes registrados previamente que se añadan a partir de ahora solo usarán una devolución de llamada estable cuando el servidor de autorización anuncie authorization_response_iss_parameter_supported: true y proporcione un metadato issuer. Si no se anuncia la compatibilidad con el emisor, Codex añade un ID de devolución de llamada específico del servidor, como http://127.0.0.1/callback/XuuuHAzzHOni. Los clientes existentes sin una devolución de llamada guardada seguirán usando su redirección específica del ID de devolución de llamada.

Durante el inicio de sesión, la selección de la devolución de llamada depende de la configuración de OAuth y de los metadatos del servidor de autorización:

El mecanismo alternativo no modifica la URL de devolución de llamada almacenada. Codex deriva el ID de devolución de llamada de la URL del MCP server, incluidos su ruta y su cadena de consulta. Las mismas reglas de selección se aplican al inicio de sesión automático y al explícito.

Define mcp_oauth_callback_url cuando necesites una ruta de devolución de llamada personalizada o una URL de entrada remota de Devbox. Los clientes registrados previamente que se añadan a partir de ahora usarán esa URL sin cambios cuando su proveedor admita la identificación del emisor. De lo contrario, usarán la URL configurada con el ID de devolución de llamada específico del servidor añadido. Registra siempre la devolución de llamada exacta que muestre codex mcp add.

Para los callbacks de http://127.0.0.1 sin un puerto explícito, Codex omite el puerto de escucha de la URL que muestra y almacena, y luego inserta el puerto de escucha activo durante la autorización. Esta sustitución no se aplica a localhost, hosts IPv6, URL HTTPS ni callbacks que ya incluyan un puerto. Los servidores de autorización deben aceptar puertos de loopback variables según RFC 8252, sección 7.3.

Configura mcp_oauth_callback_port para elegir un puerto de escucha global fijo, o configura mcp_servers.<server-name>.oauth.callback_port para sustituirlo en un servidor concreto. Un puerto explícito en la URL de callback no configura el proceso de escucha. Para un callback de loopback directo, usa http://127.0.0.1 sin un puerto explícito o configura el mismo puerto explícito tanto para la URL de callback como para el proceso de escucha. Un callback a través de un proxy puede usar intencionadamente un puerto en la URL externa distinto del puerto de escucha local. Las URL de callback locales se vinculan a la interfaz local; las URL de callback no locales se vinculan a 0.0.0.0.

Codex valida cualquier iss devuelto antes de intercambiar el código de autorización. Si iss no coincide, la respuesta siempre se rechaza. Cuando se anuncia la compatibilidad con el emisor, la ausencia de iss también provoca el rechazo. En ninguno de estos casos se intercambia el código ni se recurre a otra devolución de llamada. Una URL de devolución de llamada con formato incorrecto o el anuncio de compatibilidad con el emisor sin un emisor en los metadatos también siguen siendo errores definitivos. Consulta Autenticar usuarios.

Configure mcp_servers.<server-name>.scopes en config.toml para elegir los ámbitos de OAuth para un servidor. Para sustituirlos en un único inicio de sesión, ejecuta codex mcp login <name> --scopes read,write. Si no se configura ninguna de las dos opciones, Codex usa los ámbitos de OAuth anunciados cuando están disponibles.

Una lista vacía (scopes = []) sigue permitiendo que la biblioteca de OAuth elija los ámbitos. La biblioteca también puede añadir offline_access cuando el servidor de autorización lo admite.

Registro de clientes OAuth

Codex admite OAuth Client ID Metadata Documents (CIMD) y Dynamic Client Registration (DCR). De forma predeterminada, Codex elige automáticamente CIMD cuando el servidor de autorización anuncia client_id_metadata_document_supported: true, incluye none en token_endpoint_auth_methods_supported y la devolución de llamada utiliza una URL de bucle local compatible. De lo contrario, Codex utiliza DCR cuando está disponible. Un ID de cliente OAuth configurado siempre tiene prioridad y omite el registro del cliente.

Para CIMD sin respuestas vinculadas al emisor, Codex CLI utiliza un documento de metadatos alojado en ChatGPT específico del MCP server:

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

Codex obtiene <callback_id> de la URL del MCP server y lo incluye en el URI de redirección de bucle local, por ejemplo, http://127.0.0.1:<port>/callback/<callback_id>. El documento de metadatos registra el URI de bucle local correspondiente sin puerto. Los servidores de autorización deben aceptar el puerto seleccionado al iniciar sesión y hacer coincidir exactamente el host y la ruta, según lo exige RFC 8252. Los hosts, rutas o parámetros de consulta de devolución de llamada personalizados requieren DCR o un ID de cliente OAuth configurado.

Codex CLI también admite un documento CIMD estable y compartido:

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

Codex CLI utiliza el documento estable con la ruta compartida /callback cuando el servidor de autorización anuncia authorization_response_iss_parameter_supported: true, proporciona un valor válido de issuer en sus metadatos e incluye un valor coincidente de iss en las respuestas de autorización. Los servidores sin respuestas vinculadas al emisor utilizan el documento específico del callback.

Para elegir un método de registro para un inicio de sesión de CLI, usa --oauth-client-registration:

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

El valor predeterminado es auto. Las opciones de registro solo se aplican al inicio de sesión actual y no se almacenan en config.toml.

Ejemplos de 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 proporcionados por plugins

Los plugins instalados pueden incluir MCP servers en su manifiesto. Esos servidores se inician desde el plugin, por lo que la configuración del usuario no establece su comando de transporte. La configuración del usuario puede seguir controlando el estado de activación y la política de herramientas en 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"

Los MCP servers HTTP proporcionados por plugins también pueden declarar opciones de OAuth en .mcp.json. Los manifiestos de plugins usan los nombres de campo en camelCase clientId, callbackUrl y 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"
      }
    }
  }
}

Los MCP servers proporcionados por plugins siguen las mismas reglas de selección de devoluciones de llamada que los demás MCP servers. Si un plugin proporciona un clientId, su proveedor no admite devoluciones de llamada vinculadas al emisor y a callbackUrl le falta el ID de devolución de llamada específico del servidor, Codex ignora esa URL durante el inicio de sesión y usa mcp_oauth_callback_url o, si no está definido, http://127.0.0.1/callback, con el ID de devolución de llamada añadido. El valor callbackUrl configurado permanece sin cambios.

El valor oauth.callbackPort de un plugin sustituye el valor global mcp_oauth_callback_port; si ninguno está definido, Codex elige un puerto efímero. El puerto incluido en callbackUrl no selecciona el puerto del proceso de escucha. Para una devolución de llamada directa de bucle local con un puerto fijo, configura ambos valores para que coincidan:

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

Para una entrada remota u otro proxy, el puerto de la URL de devolución de llamada y el puerto del proceso de escucha local pueden diferir intencionadamente cuando el proxy reenvía al proceso de escucha configurado.

Ejemplos de MCP servers útiles

La lista de MCP servers sigue creciendo. Estos son algunos habituales:

• OpenAI Docs MCP: busca y lee documentación para desarrolladores de OpenAI.
• Context7: conéctate a documentación actualizada para desarrolladores.
• Figma Local y Remoto: accede a tus diseños de Figma.
• Playwright: controla e inspecciona un navegador mediante Playwright.
• Herramientas para desarrolladores de Chrome: controla e inspecciona Chrome.
• Sentry: accede a los registros de Sentry.
• GitHub: administra GitHub más allá de lo que admite git (por ejemplo, solicitudes de incorporación de cambios e incidencias).