Cómo conectar tu primer servidor MCP en Codex (2026)
Codex es un cliente MCP - no tiene modo servidor. La forma más rápida de añadir un servidor: codex mcp add <name> -- <command> desde la CLI, o Settings → MCP servers → Add server en la app de Desktop / el menú de engranaje en la extensión del IDE. La configuración vive en ~/.codex/config.toml, dentro de [mcp_servers.<name>]. Te llevaré por los tres métodos usando el ejemplo neutral context7, sacado directo de la propia documentación de OpenAI - no es un producto que yo esté promocionando.
- Los comandos, las flags y la sintaxis de config.toml de abajo se contrastaron con la documentación oficial en learn.chatgpt.com/codex/extend/mcp al momento de escribir (08/2026); la CLI de Codex evoluciona más rápido que la documentación, así que ejecuta codex mcp add --help para comprobar tu versión instalada antes de depender de cualquiera de estos.
Qué significa "conectar un servidor MCP" en Codex
MCP (Model Context Protocol) es un estándar abierto que permite a un agente llamar a herramientas/datos externos mediante una única interfaz compartida, en lugar de una integración puntual por herramienta. En Codex, "conectar un servidor MCP" significa decirle a Codex qué comando (o URL) inicia el servidor, además de cualquier variable de entorno o token que necesite para ejecutarse.
Lo primero que hay que recordar: Codex actúa solo como cliente MCP - llama a servidores externos, no se convierte en un servidor MCP al que otras herramientas llaman. Ninguna documentación confirma un modo servidor para Codex. Si el concepto de MCP todavía te resulta nuevo (no algo específico de Codex), empieza por qué es MCP y cómo funciona y vuelve aquí.
Tres formas de añadir un servidor
Codex te ofrece tres caminos para añadir un servidor, ninguno más "correcto" que otro - elige según tu flujo de trabajo:
| Método | Qué haces | Ideal cuando |
|---|---|---|
CLI - codex mcp add | Un comando en la terminal | Servidores STDIO, rápido, sin cambiar de contexto |
| App de Desktop | Settings → MCP servers → Add server | STDIO y HTTP remoto, sin editar TOML a mano |
| Extensión del IDE | Menú de engranaje → MCP servers → Add server | Trabajando dentro de VS Code/un IDE, sin terminal aparte |
Los tres escriben en el mismo lugar: config.toml. La referencia completa está en la documentación oficial de MCP en Codex. Las secciones siguientes cubren en profundidad los métodos por CLI y por edición directa - los dos más rápidos si ya te manejas con soltura en una terminal.
Método 1 - añadir un servidor desde la CLI (STDIO)
El comando principal tiene una sola forma:
codex mcp add <server-name> -- <server-launch-command>Un ejemplo real, sacado directo de la propia documentación de OpenAI - context7 (búsqueda de documentación de bibliotecas/frameworks con reconocimiento de versión), ejecutado con npx:
codex mcp add context7 -- npx -y @upstash/context7-mcpUso este ejemplo en lugar del servidor de un proveedor comercial porque es neutral - nadie está colando su propio producto como tu ejemplo de primera ejecución. La mayoría de las guías de Codex-MCP de terceros usan su propio servidor como demo, lo cual funciona, pero también significa que estás probando el camino ideal de su producto, no necesariamente una base limpia. Si un servidor necesita variables de entorno (claves de API, tokens…), añádelas con la flag --env, repetida una vez por variable:
codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-serverDespués de añadirlo, verifica de dos maneras:
codex mcp list- lista los servidores configurados.- Escribe
/mcpdentro de una sesión TUI de Codex - muestra qué servidores están activos en esa sesión.
Si el servidor no aparece, casi siempre es un -- mal escrito (el doble guion que separa las flags del propio codex mcp add del comando real del servidor) - revisa eso antes de dar por hecho que el servidor en sí está roto.
Método 2 - editar el config.toml directamente
Para un control más explícito, o si quieres versionar la configuración de MCP junto con un proyecto, edita el archivo directamente. Un servidor STDIO se ve así:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.context7.env]
API_KEY = "your-value-here"Un servidor Streamable HTTP (remoto) usa un conjunto distinto de claves - url en lugar de command/args, por ejemplo un servidor de Figma:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }bearer_token_env_var apunta al nombre de una variable de entorno que guarda el token real - esa variable la defines en tu máquina, no escribes el token directo en el archivo. ~/.codex/config.toml es el archivo global, que se aplica a todos los proyectos. Para los proyectos marcados como de confianza, Codex también lee un archivo .codex/config.toml dentro del propio directorio del proyecto - útil si quieres la configuración de MCP por repositorio incluida en el control de versiones.
Añadir un servidor remoto (Streamable HTTP)
La ruta confirmada para servidores HTTP hoy son las Settings de Desktop o el menú de engranaje de la extensión del IDE: escribe un nombre, elige STDIO o HTTP, pega la URL. Esta ruta está claramente documentada.
Aquí conviene ir con cautela: algunas guías de terceros (no la documentación oficial) muestran una sintaxis como codex mcp add <name> --url <url> para añadir un servidor HTTP directo desde la CLI. La documentación oficial de OpenAI, al momento de escribir, no confirma esta flag --url en la sección de sintaxis de la CLI. No des por hecho que existe - ejecuta codex mcp add --help para comprobar si la versión exacta de la CLI que tienes instalada la admite antes de confiar en ella. En el peor de los casos, editar el config.toml a mano (Método 2, arriba) funciona sin importar lo que admita tu versión instalada de la CLI, ya que no depende de que exista una flag concreta.
Algunas claves de ajuste fino sirven tanto para STDIO como para HTTP, declaradas dentro del mismo bloque [mcp_servers.<name>]: startup_timeout_sec, tool_timeout_sec, enabled (activa/desactiva el servidor) y enabled_tools/disabled_tools (lista de permitidos/bloqueados de qué herramientas puede exponer ese servidor).
Codex vs. Claude Code - la configuración de MCP no es la misma
Este sitio cubre tanto Claude Code como Codex, así que vale decirlo sin rodeos: no traslades los hábitos de una herramienta directamente a la otra.
| Aspecto | Codex | Claude Code |
|---|---|---|
| Formato de configuración | TOML - config.toml | JSON - .mcp.json |
| Comando para añadir (STDIO) | codex mcp add <name> -- <command> | claude mcp add <name> -- <command> |
| Comando para añadir (HTTP) | Ninguna flag de CLI confirmada - usa las settings de Desktop/IDE | claude mcp add --transport http <name> <url> -H "Authorization: Bearer TOKEN" |
| Alcance | Global (~/.codex/config.toml) más un archivo opcional por proyecto, sin flag de alcance explícita | Flag -s explícita: local (por defecto) / project / user |
¿Quieres ver el mismo servidor real (GitHub) configurado del otro lado? Lee cómo conectar el servidor MCP de GitHub a Claude Code - un ejemplo concreto entre herramientas, no teoría.
Comprueba que funcionó
La comprobación más rápida: escribe /mcp en la TUI para ver qué servidores están activos en la sesión actual. Los modos de fallo más comunes:
- Falta una variable de entorno - el servidor necesita
API_KEYpero olvidaste el--envo el bloque.enven el TOML. command/argsincorrectos - un nombre de paquete mal escrito, o un-yausente al ejecutar connpx.- Token HTTP sin definir - la variable que indica
bearer_token_env_varnunca se definió en tu máquina, así que el servidor falla la autenticación aunque la sintaxis sea correcta.
Una línea para dejar claro el límite: un servidor MCP le da a Codex nuevas herramientas para llamar (leer un archivo de Figma, consultar una base de datos…). La capa de skills de AgentKit (agentkit.best, kit de pago - distinto del AgentKit de OpenAI) es una capa aparte por encima, que empaqueta flujos de trabajo listos - no es lo mismo que conectar un servidor MCP, y no necesitas una para usar la otra.
Preguntas frecuentes (FAQ)
¿Codex es un servidor MCP o solo un cliente?
Solo un cliente. Codex llama a servidores MCP externos para obtener más herramientas/datos; ninguna documentación confirma que el propio Codex funcione como un servidor MCP al que otras herramientas llaman.
¿Cuál es el comando exacto para añadir un servidor MCP?
codex mcp add <server-name> -- <launch-command>, por ejemplo codex mcp add context7 -- npx -y @upstash/context7-mcp. Añade variables de entorno con --env KEY=VALUE, repetido por variable.
¿Dónde guarda Codex la configuración de MCP?
En ~/.codex/config.toml (global, se aplica a todos los proyectos), dentro de [mcp_servers.<name>]. Para proyectos de confianza, Codex también lee un archivo .codex/config.toml dentro del directorio del proyecto.
¿Cuál es la diferencia entre STDIO y Streamable HTTP?
STDIO ejecuta el servidor como un proceso local mediante command/args (por ejemplo, iniciado a través de npx). Streamable HTTP llama a un servidor remoto por url, autenticado con bearer_token_env_var o una cabecera personalizada - nada que instalar en local.
¿Puedo añadir un servidor remoto directo desde la CLI?
No confirmado. Algunas guías de terceros muestran una flag --url, pero la documentación oficial de Codex no la incluye al momento de escribir. La ruta confirmada hoy son las Settings de Desktop o el menú de engranaje del IDE; para comprobar si tu CLI la admite, ejecuta codex mcp add --help.
¿La configuración de MCP de Codex es igual que la de Claude Code?
No. Codex usa TOML (config.toml) sin flag de alcance explícita; Claude Code usa JSON (.mcp.json) con una flag -s local/project/user explícita. El mismo estándar MCP por debajo, mecánicas de configuración distintas - no copies la sintaxis de una herramienta directo a la otra.
Conclusión
Elige la CLI para una adición rápida de STDIO, Desktop/IDE cuando necesites un servidor HTTP remoto y aún no tengas claro si tu CLI admite esa flag, y edita el config.toml directamente cuando quieras la configuración por proyecto bajo control de versiones. ¿Quieres extender Codex más allá de MCP? Mira Codex Skills (SKILL.md) - una vía de extensión paralela, no un reemplazo de MCP. ¿Es tu primera vez con Codex en general? Empieza por qué es OpenAI Codex.