Protocolo de contexto de modelo

La app de escritorio de ChatGPT, la CLI de Codex y la extensión para IDE admiten servidores MCP y comparten la configuración de MCP cuando usan el mismo host de Codex.

Las funciones que se describen a continuación se aplican a los servidores MCP configurados en un host de Codex. Las herramientas de los complementos alojados pueden tener otras capacidades.

Funciones de MCP compatibles

• Servidores STDIO: se ejecutan como procesos locales que se inician con un comando.
  • Variables de entorno
• Servidores Streamable HTTP: se accede a ellos mediante una dirección.
  • Autenticación con token de portador
  • Autenticación OAuth, incluidos los documentos de metadatos de ID de cliente (CIMD) y el registro dinámico de clientes (DCR)
  • Autenticación con la sesión de ChatGPT para servidores propios de confianza
• Instrucciones del servidor: Codex lee el campo instructions de MCP que recibe durante la inicialización y usa esas instrucciones como guía para todo el servidor, junto con sus herramientas.

Si desarrollas o mantienes un servidor MCP para Codex, usa instructions para describir los flujos de trabajo que combinan herramientas, las restricciones y los límites de solicitudes que se aplican a todo el servidor. Asegúrate de que los primeros 512 caracteres se entiendan por sí solos para que Codex disponga de las indicaciones más importantes cuando decida cómo usar el servidor.

Conectar Codex a un servidor MCP

Codex guarda la configuración de MCP en config.toml junto con los demás ajustes de Codex. La ruta predeterminada es ~/.codex/config.toml, pero también puedes configurar servidores MCP para un proyecto específico con .codex/config.toml (solo en proyectos de confianza).

La app de escritorio de ChatGPT, la CLI de Codex y la extensión para IDE comparten esta configuración. Una vez que configures tus servidores MCP, puedes cambiar de cliente sin tener que configurarlos de nuevo.

Configurar los servidores en la app de escritorio de ChatGPT

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

La lista indica qué servidores están habilitados y cuáles requieren OAuth. Selecciona Autenticar cuando un servidor OAuth requiera que inicies sesión. En el editor, escribe /mcp para ver los servidores conectados.

Usar herramientas basadas en MCP en ChatGPT en la web

Si continúas en otro dispositivo una conversación que usa el acceso a la computadora local con Work Cloud, los complementos no se instalan ni se concede acceso a las cuentas conectadas.

Cuando usas el acceso a la computadora local con Work Cloud, el requisito empresarial mcp_servers de TOML en la configuración de seguridad de agentes se aplica a los ejecutores locales. Los contenedores en la nube conservan las políticas de Work Cloud. Es posible que los servidores MCP y los transportes locales no estén disponibles en la nube. Verifica por separado la conectividad y la autenticación.

Si usas hooks empresariales con el acceso a la computadora local con Work Cloud, ten en cuenta lo siguiente:

• Hooks empresariales. Si están habilitados en tu espacio de trabajo, el acceso a la computadora local con Work Cloud admite hooks de MCP definidos por un administrador. Estos hooks se ejecutan en el coordinador de 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 los complementos, incluso cuando las herramientas se ejecutan localmente.
• Auditoría. Antes de depender de estos hooks, prueba la conexión de callback, confirma qué eventos recibe y verifica cómo afectan las fallas a la tarea. Los hooks de MCP no proporcionan un registro de auditoría completo de la API de Cumplimiento.
• Limitaciones: la orquestación en la nube no admite hooks de comandos ni hooks de la configuración local o de los complementos, 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 del modo Work y de Codex que se ejecutan exclusivamente de forma local. Los administradores pueden seguir configurando los hooks administrados compatibles en la configuración de seguridad de agentes para esos flujos de trabajo.

Consulta Hooks y la referencia de configuración para saber qué se admite.

En un chat alojado de ChatGPT Work, instala un complemento para usar los conectores y las herramientas MCP remotas que incluye. Después de la instalación, los modos Chat y Work pueden usar esas herramientas. Los administradores del espacio de trabajo pueden controlar qué complementos y herramientas están disponibles.

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

Configurar los servidores con la CLI

Agregar un servidor MCP

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

Por ejemplo, para agregar Context7 (un servidor MCP gratuito de 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. Si el servidor admite OAuth, ejecuta codex mcp login <server-name>. Si usas una terminal sin navegador local, ejecuta codex mcp login <server-name> --no-browser. Abre en un navegador la URL de autorización que muestra el comando e inicia sesión. Pega la URL de redirección completa en la terminal, incluso si el navegador no puede cargar la página de callback.

Interfaz de usuario de terminal (TUI)

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

Configurar los servidores en la extensión para IDE

1. Abre el menú del ícono de engranaje y selecciona Servidores MCP.
2. Selecciona Agregar servidor.
3. Ingresa un nombre, elige STDIO o Streamable HTTP e indica el comando o la URL del servidor.
4. Guarda el servidor y selecciona Reiniciar extensión.

La lista de servidores MCP indica cuáles están habilitados y cuáles requieren OAuth. Selecciona Autenticar cuando un servidor OAuth requiera que inicies sesión.

Configurar los servidores con config.toml

Para ajustar la configuración con más detalle, edita ~/.codex/config.toml o el archivo .codex/config.toml de un proyecto. En la referencia de configuración puedes buscar todas las opciones de MCP compatibles.

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

Servidores STDIO

• command (obligatorio): comando que inicia el servidor.
• args (opcional): argumentos que se pasan al servidor.
• env (opcional): variables de entorno que se establecen para el servidor.
• env_vars (opcional): variables de entorno que se permiten y reenvían.
• cwd (opcional): directorio de trabajo desde el que se inicia el servidor.

env_vars puede contener nombres de variables sin más datos u objetos que indiquen su origen:

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

Las entradas de tipo cadena y las que especifican source = "local" toman sus valores del entorno local de Codex. source = "remote" toma los valores del entorno del ejecutor remoto y requiere MCP stdio remoto.

Servidores Streamable HTTP

• url (obligatorio): dirección del servidor.
• auth (opcional): método de autenticación que se prueba después de los tokens de portador y los encabezados de autorización configurados. Usa oauth (valor predeterminado) para autenticarte con las credenciales OAuth de MCP almacenadas. Con chatgpt, Codex usa la sesión actual de ChatGPT para el origen propio de confianza de ChatGPT y recurre a las credenciales OAuth almacenadas si es necesario.
• bearer_token_env_var (opcional): nombre de la variable de entorno que contiene el token de portador que se enviará en Authorization.
• http_headers (opcional): asignación de nombres de encabezados a valores estáticos.
• env_http_headers (opcional): asignación 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 tipo cadena, como {"X-Auth": "temporary-token"}. Se admite en las conexiones MCP por HTTP que se establecen desde el entorno local. No se admite en servidores stdio ni en conexiones establecidas a través de un entorno de ejecución remoto.

Codex guarda en caché los encabezados que genera el comando auxiliar para la conexión. Si una solicitud POST al mismo origen devuelve 401 o 403, Codex actualiza los encabezados una vez y reintenta la solicitud solo si el comando auxiliar devuelve valores distintos. Los tokens de portador explícitos y las credenciales OAuth tienen prioridad sobre cualquier encabezado Authorization que proporcione el comando auxiliar. Una respuesta OAuth 403 que indique un alcance insuficiente no activa la actualización de encabezados.

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

Otras opciones de configuración

• environment_id selecciona el entorno de un servidor stdio o Streamable HTTP. El valor predeterminado es local. Para conectarte a través de un ejecutor remoto, usa el ID de entorno registrado de ese ejecutor.
• startup_timeout_sec (opcional): tiempo máximo de espera, en segundos, para que se inicie el servidor. Valor predeterminado: 10.
• tool_timeout_sec (opcional): tiempo máximo de espera, en segundos, para que el servidor ejecute una herramienta. Valor predeterminado: 60.
• enabled (opcional): usa false para deshabilitar el servidor sin eliminarlo.
• Configura required = true para que el inicio falle si este servidor está habilitado y no está listo. De forma predeterminada, startup_readiness = "connection" exige una conexión activa. Configura startup_readiness = "catalog" para que un catálogo de herramientas válido almacenado en caché permita completar el inicio mientras el servidor se conecta. Las llamadas a herramientas siguen necesitando una conexión activa.
• enabled_tools (opcional): lista de herramientas permitidas.
• disabled_tools (opcional): lista de herramientas bloqueadas. 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 aprobación para las herramientas que no están marcadas como de solo lectura.
• tools.<tool>.approval_mode (opcional): comportamiento de aprobación que se aplica a una herramienta en lugar del predeterminado.
• tools.<tool>.output_token_limit (opcional): cantidad máxima de tokens para la salida de una herramienta. Debe ser un valor positivo y se aplica antes del margen estándar del 20 % para la serialización. Reemplaza el límite predeterminado del modelo para truncar la salida de esa herramienta.

El ajuste 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. El valor predeterminado es 1000 milisegundos. Usa 0 para que Codex espere el tiempo indicado en startup_timeout_sec de cada servidor. Los servidores obligatorios siguen usando sus propios tiempos máximos de espera para el inicio.

Registro de clientes OAuth y callbacks

Si tu servidor de autorización requiere un cliente OAuth registrado de antemano, indica el ID de cliente al agregar el servidor MCP:

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 que tanto el ID como el secreto del cliente tengan un valor. 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.

Registra la URL de callback exacta que muestra codex mcp add. Cuando el servidor de autorización anuncia que admite la identificación del emisor, la CLI puede mostrar esta URL:

OAuth callback URL: http://127.0.0.1/callback

Para el cliente público de este ejemplo, Codex guarda el callback y 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"

Al agregar un cliente registrado de antemano, este usa un callback estable solo si el servidor de autorización anuncia authorization_response_iss_parameter_supported: true e incluye un issuer en sus metadatos. Si no anuncia la compatibilidad con la identificación del emisor, Codex agrega a la URL un ID de callback específico del servidor, como en http://127.0.0.1/callback/XuuuHAzzHOni. Los clientes existentes sin un callback guardado siguen usando la redirección correspondiente a su ID de callback.

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

El uso de un callback alternativo no modifica la URL de callback almacenada. Codex obtiene el ID de callback a partir de la URL del servidor MCP, incluidas la ruta y la cadena de consulta. Las mismas reglas de selección se aplican tanto al inicio de sesión automático como al explícito.

Configura mcp_oauth_callback_url cuando necesites una ruta de callback personalizada o una URL de entrada a un Devbox remoto. Los clientes registrados de antemano que agregues usan esa URL sin cambios si su proveedor admite la identificación del emisor. En caso contrario, usan la URL configurada con el ID de callback específico del servidor al final. Registra siempre el callback exacto que muestra codex mcp add.

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

Configura mcp_oauth_callback_port para elegir un puerto de escucha global fijo o usa mcp_servers.<server-name>.oauth.callback_port para cambiarlo en un servidor específico. Indicar un puerto explícito en la URL de callback no configura el puerto 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 en la URL de callback y en el proceso de escucha. Si el callback pasa por un proxy, puedes usar intencionalmente un puerto distinto en la URL externa y en el proceso de escucha local. Con una URL de callback local, el proceso escucha en la interfaz local. Con una URL de callback no local, escucha en 0.0.0.0.

Codex valida cualquier iss recibido antes de canjear el código de autorización. Si el iss no coincide, Codex siempre rechaza la respuesta. Si el servidor anuncia la compatibilidad con la identificación del emisor y falta iss, también la rechaza. En ambos casos, Codex no canjea el código ni recurre a otro callback. Una URL de callback mal formada o un servidor que anuncie la identificación del emisor sin incluirlo en sus metadatos también provocan un error que impide continuar. Consulta Autenticar usuarios.

Configura mcp_servers.<server-name>.scopes en config.toml para elegir los alcances de OAuth de un servidor. Para cambiarlos en un solo inicio de sesión, ejecuta codex mcp login <name> --scopes read,write. Si no usas ninguna de estas opciones, Codex solicita los alcances indicados en el desafío de autenticación inicial del servidor (WWW-Authenticate). Si el desafío no indica alcances, Codex usa los que se anuncian en los metadatos del recurso protegido, si están disponibles.

Una lista vacía (scopes = []) permite que la biblioteca de OAuth elija los alcances. La biblioteca también puede agregar offline_access si el servidor de autorización lo admite.

Registro de clientes OAuth

Codex admite los documentos de metadatos de ID de cliente OAuth (CIMD) y el registro dinámico de clientes (DCR). De forma predeterminada, Codex elige CIMD automáticamente cuando el servidor de autorización anuncia client_id_metadata_document_supported: true, incluye none en token_endpoint_auth_methods_supported y el callback usa una URL de loopback compatible. De lo contrario, Codex usa DCR si está disponible. Si se ha configurado un ID de cliente OAuth, este siempre tiene prioridad y Codex omite el registro del cliente.

Para CIMD sin respuestas vinculadas al emisor, la CLI de 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> a partir de la URL del servidor MCP y lo incluye en el URI de redirección de loopback, por ejemplo, http://127.0.0.1:<port>/callback/<callback_id>. El documento de metadatos registra el URI de loopback correspondiente sin puerto. Los servidores de autorización deben aceptar el puerto seleccionado al iniciar sesión y exigir una coincidencia exacta del host y la ruta, tal como establece RFC 8252. Si personalizas el host, la ruta o los parámetros de consulta del callback, necesitas DCR o un ID de cliente OAuth configurado.

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

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

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

Para elegir un método de registro para un solo inicio de sesión en la 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. El método de registro que elijas se aplica solo al inicio de sesión actual y no se guarda 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 incluidos en complementos

Los complementos instalados pueden incluir servidores MCP en su archivo de manifiesto. Estos servidores se inician desde el complemento, por lo que la configuración del usuario no determina su comando de transporte. Desde la configuración del usuario sí puedes habilitarlos o deshabilitarlos y controlar 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 por HTTP incluidos en complementos también pueden declarar ajustes de OAuth en .mcp.json. Los archivos de manifiesto de los complementos 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 incluidos en complementos siguen las mismas reglas de selección de callbacks que los demás servidores MCP. Si un complemento proporciona un clientId, su proveedor no admite callbacks vinculados al emisor y callbackUrl no incluye el ID de callback específico del servidor, Codex ignora esa URL para el inicio de sesión. En su lugar, usa mcp_oauth_callback_url o, si no se ha establecido, http://127.0.0.1/callback. En ambos casos, agrega el ID de callback al final. La callbackUrl configurada se conserva sin cambios.

El valor de oauth.callbackPort de un complemento tiene prioridad sobre el valor global de mcp_oauth_callback_port. Si no se configura ninguno, Codex elige un puerto efímero. El puerto incluido en callbackUrl no determina el puerto de escucha. Para un callback de loopback directo con puerto fijo, configura ambos valores de modo que coincidan:

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

Si usas un punto de entrada remoto u otro proxy, el puerto de la URL de callback puede ser distinto del puerto de escucha local siempre que el proxy reenvíe las solicitudes al puerto de escucha configurado.

Ejemplos de servidores MCP útiles

La lista de servidores MCP sigue creciendo. Estos son algunos de los más comunes:

• MCP de documentación de OpenAI: busca y lee la documentación de OpenAI para desarrolladores.
• Context7: accede a documentación actualizada para desarrolladores.
• Figma local y remoto: accede a tus diseños de Figma.
• Playwright: controla e inspecciona un navegador con Playwright.
• Herramientas para desarrolladores de Chrome: controla e inspecciona Chrome.
• Sentry: accede a los registros de Sentry.
• GitHub: gestiona funciones de GitHub que git no admite, como los Pull Requests y los Issues de GitHub.