MCP | Ampliar ChatGPT y Codex | Documentación de ChatGPT

Model Context Protocol (MCP) conecta los modelos con herramientas y contexto. Úsalo para dar a ChatGPT o Codex acceso a documentación de terceros, o para permitirle interactuar con herramientas para desarrolladores, como tu navegador o Figma.

ChatGPT web puede utilizar herramientas remotas respaldadas por MCP que proporcionan los plugins. Después de instalar un plugin, Chat y Work pueden utilizar los conectores y las herramientas MCP remotas que incluye. Abre la pestaña Plugins para explorar y administrar las herramientas disponibles. Los clientes locales de Codex también pueden conectarse directamente a servidores MCP y compartir su configuración.

La aplicación de escritorio de ChatGPT, Codex CLI y la extensión para IDE admiten servidores MCP 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 servidores MCP 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 servidor MCP 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 servidor MCP

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 servidores MCP 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 servidores MCP, podrás alternar entre esos clientes sin tener que repetir la configuración.

Configurar en la aplicación de escritorio de ChatGPT

Abre Configuración y selecciona Servidores MCP.
Selecciona Agregar servidor.
Introduce un nombre, elige STDIO o Streamable HTTP y proporciona el comando o la URL del servidor.
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.

Configura con la CLI

Añadir un servidor MCP

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

Por ejemplo, para añadir Context7 (un servidor MCP 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 servidores MCP activos.

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 servidor MCP 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 servidores MCP 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 servidor MCP:

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

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:

Configuración de OAuth	Compatibilidad con el emisor	Devolución de llamada utilizada
`callback_url` sin `client_id`	Compatible	La devolución de llamada configurada se usa para registrar el cliente.
`callback_url` sin `client_id`	No compatible	La devolución de llamada configurada se usa para registrar el cliente con el ID de devolución de llamada específico del servidor añadido.
`client_id` y `callback_url`	Compatible	La devolución de llamada configurada se reutiliza; la respuesta de autorización debe contener el valor `iss` correspondiente.
`client_id` y un `callback_url` que termina con el ID de devolución de llamada correcto	No compatible	La devolución de llamada configurada se reutiliza sin cambios.
`client_id` y un `callback_url` al que le falta el ID de devolución de llamada correcto	No compatible	Se ignora la devolución de llamada configurada. Codex 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.
`client_id` sin un `callback_url` configurado	Compatible o no compatible	Codex usa la devolución de llamada global o predeterminada con el ID de devolución de llamada específico del servidor añadido.

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 servidor MCP, 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 las devoluciones de llamada http://127.0.0.1 sin puerto, Codex omite el puerto del proceso de escucha de la URL que muestra y almacena, y después inserta el puerto activo del proceso de escucha durante la autorización. Esta sustitución no se aplica a localhost, hosts IPv6, URL HTTPS ni devoluciones de llamada que ya incluyan un puerto. Los servidores de autorización deben aceptar puertos de bucle invertido variables conforme a la sección 7.3 de RFC 8252.

Define mcp_oauth_callback_port para elegir un puerto global fijo para el proceso de escucha o define mcp_servers.<server-name>.oauth.callback_port para sustituirlo en un servidor. Un puerto explícito en la URL de devolución de llamada no configura el proceso de escucha. Para una devolución de llamada directa de bucle invertido, usa http://127.0.0.1 sin puerto o configura el mismo puerto explícito tanto para la URL de devolución de llamada como para el proceso de escucha. Una devolución de llamada mediante proxy puede usar intencionadamente un puerto de URL externo distinto del puerto del proceso de escucha local. Las URL de devolución de llamada locales se vinculan a la interfaz local; las URL de devolución de llamada 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.

Si el servidor MCP anuncia scopes_supported, Codex da preferencia a esos ámbitos anunciados por el servidor durante el inicio de sesión OAuth. De lo contrario, Codex recurre a los ámbitos configurados en config.toml.

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 invertido 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, Codex usa un documento de metadatos alojado en ChatGPT y específico del servidor MCP:

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

Codex obtiene <callback_id> de la URL del servidor MCP y lo incluye en el URI de redirección de bucle invertido, por ejemplo, http://127.0.0.1:<port>/callback/<callback_id>. El documento de metadatos registra el URI de bucle invertido 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.

La compatibilidad con un documento CIMD estable y compartido está en desarrollo y estará disponible próximamente:

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

Codex usará el documento estable con la ruta compartida /callback cuando el servidor de autorización anuncie authorization_response_iss_parameter_supported: true, proporcione un issuer válido en sus metadatos e incluya un iss coincidente en las respuestas de autorización. Los servidores sin respuestas vinculadas al emisor seguirán usando el documento específico de la devolución de llamada.

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

Servidores MCP proporcionados por plugins

Los plugins instalados pueden incluir servidores MCP 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 servidores MCP 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 servidores MCP proporcionados por plugins siguen las mismas reglas de selección de devoluciones de llamada que los demás servidores MCP. 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 invertido 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 servidores MCP útiles

La lista de servidores MCP 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).

Búsquedas recientes

Búsquedas sugeridas

Navegación de la documentación

Model Context Protocol