Configura MCP en Codex: codex mcp add para un servidor remoto, config.toml (remoto y stdio), OAuth con codex mcp login y cómo saber si las herramientas cargan.

En resumen: Codex lee sus servidores MCP de ~/.codex/config.toml, y la CLI edita ese archivo por ti. Para un servidor remoto basta un comando: codex mcp add unifapi --url https://mcp.unifapi.com. Ejecuta codex mcp list para confirmar que está registrado, y codex mcp login unifapi si el inicio de sesión OAuth no se abrió en el primer uso. La extensión de IDE de Codex lee el mismo archivo, así que un servidor añadido una vez está disponible en la terminal y en VS Code.

Codex, el agente de codificación de OpenAI, admite el Model Context Protocol en la CLI y en la extensión de IDE. La configuración es un único archivo TOML, lo que lo convierte en uno de los clientes más fáciles de configurar y en uno de los más fáciles de configurar sutilmente mal: un servidor añadido en la tabla equivocada, o un servidor stdio declarado como URL, falla en silencio hasta que pides una herramienta. Esta guía usa el servidor MCP de UnifAPI (https://mcp.unifapi.com, datos públicos en vivo de plataformas sociales y del stack de SEO) como ejemplo práctico, y los pasos son los mismos para cualquier servidor remoto.

Qué necesitas

La CLI de Codex (npm install -g @openai/codex o brew install codex) o la extensión de Codex en VS Code, Cursor o Windsurf. Ambas leen ~/.codex/config.toml.
Una sesión iniciada en Codex (codex login). MCP funciona tanto con el inicio de sesión de ChatGPT como con una clave de API.
Para UnifAPI: una cuenta de UnifAPI cuando se abra la ventana de OAuth, y créditos del espacio de trabajo antes de la primera llamada facturable. Explorar el catálogo es gratis.

Añade un servidor remoto con codex mcp add

Un servidor remoto (streamable HTTP) es una URL. Regístralo:

codex mcp add unifapi --url https://mcp.unifapi.com

Comprueba que se ha escrito:

codex mcp list
codex mcp get unifapi

codex mcp list imprime todos los servidores configurados con su transporte y su estado de autenticación. La primera vez que Codex inicia una sesión con un servidor protegido por OAuth, abre el inicio de sesión en tu navegador. Si eso no ocurrió, o estás en una máquina sin navegador, lánzalo tú mismo:

codex mcp login unifapi
# headless: print the URL instead of opening a browser
codex mcp login unifapi --no-browser

El inicio de sesión OAuth solo se ofrece para servidores streamable HTTP; un servidor stdio no tiene paso de inicio de sesión. El token se guarda en el llavero del sistema (o en el archivo de credenciales al que Codex recurre como alternativa) y se reutiliza entre sesiones. codex mcp logout unifapi lo borra, y codex mcp remove unifapi elimina el servidor.

El config.toml que hay detrás

Todo lo que escribió la CLI es TOML plano bajo [mcp_servers.<name>]. Para UnifAPI la entrada es una línea:

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

Dos campos opcionales importan para otros servidores remotos:

[mcp_servers.example]
url = "https://mcp.example.com"
# Read a static bearer token from this environment variable instead of OAuth
bearer_token_env_var = "EXAMPLE_TOKEN"
# Extra headers, literal or sourced from the environment
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Tenant" = "EXAMPLE_TENANT" }

UnifAPI acepta bearer_token_env_var con una clave de API del espacio de trabajo, pero OAuth es la vía recomendada: nada que pegar en un dotfile, y el token es de solo lectura.

Un servidor stdio local usa command y args en lugar de url. Las dos formas son excluyentes; una tabla que las mezcla se rechaza:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"]
env = { "NODE_OPTIONS" = "--max-old-space-size=512" }

Servidores por proyecto

Codex fusiona un .codex/config.toml de nivel de proyecto (en la raíz del repositorio, cuando el proyecto es de confianza) sobre la configuración de tu home. Pon ahí un servidor cuando solo lo necesite un repositorio, e incluye el archivo en el repositorio para que tus compañeros tengan las mismas herramientas. codex mcp login resuelve los nombres a partir de la configuración fusionada, así que un servidor OAuth con ámbito de proyecto inicia sesión de la misma manera.

Confirma que las herramientas cargan

Inicia una sesión en un proyecto y pide algo que solo el servidor pueda responder:

Usa el servidor MCP unifapi para listar las operaciones disponibles para Reddit.

Deberías ver una llamada a la herramienta list_operations antes de la respuesta. En la extensión de IDE, los servidores MCP y sus herramientas aparecen en el panel de ajustes de la extensión; un servidor con estado en rojo ahí suele significar que falta el token OAuth (codex mcp login) o que la URL está mal (codex mcp get).

Según tu modo de aprobación (codex --ask-for-approval, o el modo que elegiste en el IDE), Codex puede preguntar antes de cada llamada a herramienta. Para un servidor de solo lectura como UnifAPI es seguro permitir las llamadas durante la sesión; lo único que una llamada puede gastar son créditos del espacio de trabajo, y get_operation muestra el precio por registro antes de que call_api se ejecute.

Una primera tarea que vale los créditos

El servidor MCP de UnifAPI expone un catálogo amplio a través de tres herramientas: list_operations para descubrir, get_operation para el esquema y un ejemplo de llamada, y call_api para ejecutar una. Codex se desenvuelve bien con esta forma porque es el mismo bucle que usa con una CLI: buscar el comando, leer su ayuda, ejecutarlo. Un primer prompt acotado:

Con las herramientas MCP de unifapi, extrae las 20 publicaciones públicas más recientes de la cuenta de X que encuentres para "OpenAI Developers" y dame una tabla con publicación, likes, reposts y el tema en una línea. Llama a list_operations y get_operation antes de call_api.

La facturación es por registro de datos públicos en créditos del espacio de trabajo ($0,001 cada uno; un crédito para la mayoría de los registros, mínimos mayores publicados en el catálogo). Los tokens del modelo se quedan en tu plan de OpenAI. Un espacio de trabajo nuevo no tiene créditos hasta su primera recarga, que incluye un bono único, así que recarga una vez en la consola de UnifAPI antes del primer call_api.

Para trabajo con forma de tarea, los agentes por plataforma y el agente de SEO le dan a Codex un prompt listo y la lista de operaciones que va a necesitar.

Solución de problemas

Síntoma	Qué hacer
`codex mcp list` muestra el servidor pero las herramientas nunca aparecen	Inicia una sesión nueva; los servidores se cargan al empezar la sesión. En el IDE, recarga la ventana
"OAuth login is only supported for streamable HTTP servers"	La tabla tiene `command` en lugar de `url`; los servidores stdio no tienen paso de inicio de sesión
El inicio de sesión en el navegador nunca se completa	Ejecuta `codex mcp login unifapi --no-browser`, abre la URL impresa en cualquier navegador y pega el callback de vuelta en la terminal
`call_api` devuelve `insufficient_credits`	El espacio de trabajo aún no tiene créditos; recarga una vez en la consola y repite el mismo prompt
El servidor desaparece en un repositorio	Un `.codex/config.toml` del proyecto está sobrescribiendo tu configuración de home; `codex mcp get <name>` muestra de qué archivo salió la entrada
Las llamadas a herramientas se rechazan	Tu modo de aprobación las está bloqueando; apruébalas para la sesión o relaja el modo para este proyecto

Fuentes consultadas

Escrito el 14 de octubre de 2026 frente a la referencia de configuración de MCP de la CLI de Codex y los subcomandos de codex mcp de la versión actual (add, list, get, login, logout, remove), además de la documentación para desarrolladores de OpenAI sobre MCP en Codex. Los nombres de campo de config.toml están tomados del propio esquema de la CLI.

Qué leer a continuación

Configuración de MCP - las instrucciones del conector alojado para todos los clientes.

Cómo añadir un servidor MCP a Claude - conectores, claude_desktop_config.json y claude mcp add.

Configuración de MCP en Cursor - mcp.json y enlaces de instalación con un clic.

Diseño de herramientas del catálogo MCP - por qué el servidor expone tres herramientas en lugar de una por endpoint.