Servidores MCP en Codex CLI: añadir, configurar y autenticar
Los servidores MCP le dan a Codex herramientas nuevas: documentación al día, tu base de datos, tus repos de GitHub. Este recorrido ejecuta codex mcp add para un servidor stdio local, pasa a un servidor remoto con --url y OAuth, inspecciona las entradas de config.toml detrás de ambos y muestra las comprobaciones que prueban que un servidor funciona de verdad.
TL;DR
- Codex lee los servidores MCP de ~/.codex/config.toml (global) o .codex/config.toml (proyecto). Cada entrada es una tabla [mcp_servers.<name>] con command/args para servidores stdio locales o url para los remotos.
- codex mcp add context7 -- npx -y @upstash/context7-mcp instala un servidor stdio sin tocar el archivo; codex mcp add <name> --url https://mcp.example.com/mcp registra uno remoto.
- Los servidores remotos se autentican en el navegador en la primera conexión (Codex imprime Detected OAuth support y abre la pantalla de consentimiento), o después con codex mcp login <name>.
- Verifica con /mcp dentro de la TUI o codex mcp list en la shell. Codex 0.160.1 además conserva SYSTEMROOT, TEMP y TMP al lanzar servidores stdio remotos con variables de entorno remotas.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
Canal: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
Canal: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
Canal: Snyk9:14
Connect Codex to an MCP server — official documentation
Documentación oficial: developers.openai.com/codex
Cada comando, ruta de archivo y clave de configuración de esta página está verificado contra la documentación oficial de MCP de Codex; los videos de arriba son la fuente visual y de hechos, incluidas las pantallas de consentimiento de OAuth y el menú MCP de la app de escritorio.
Las capturas se atribuyen a sus creadores con enlaces profundos a los minutos exactos. No se usan fotogramas con caras.
Añade servidores MCP a Codex, paso a paso
Parte 1 — Tu primer servidor stdio
- 1
Elige un servidor de la documentación oficial de MCP
Abre developers.openai.com/codex/mcp — la documentación propia de Codex mantiene la sintaxis de comandos al día, y la CLI y la extensión de IDE comparten esta configuración. La documentación lista servidores listos para probar primero: Context7 para documentación de librerías en vivo, Figma, GitHub y más. Hay cientos de servidores MCP; para una primera prueba elige algo de solo lectura como Context7.
La página oficial Connect Codex to an MCP server, con la sintaxis de codex mcp add y un ejemplo de Context7 listo para copiar.Ver en 0:20 - 2
Instálalo con codex mcp add
Copia el ejemplo y ejecútalo en tu terminal: codex mcp add context7 -- npx -y @upstash/context7-mcp. Todo lo que va después del doble guion es el comando que lanza el proceso del servidor. Codex responde "Added global MCP server 'context7'" — global significa que entró en tu configuración de usuario y está disponible en todos los proyectos.
Un comando, sin editar archivos: la CLI confirma que el servidor se añadió a la configuración global.Ver en 0:45 - 3
Mira qué escribió la CLI en config.toml
codex mcp add es solo un generador para ~/.codex/config.toml. Abre el archivo y encontrarás [mcp_servers.context7] con command = "npx" y args = ["-y", "@upstash/context7-mcp"]. Las entradas también pueden escribirse a mano: añade una tabla env para claves de API, o define startup_timeout_sec (10 por defecto) y tool_timeout_sec (60 por defecto) para servidores lentos. La edición manual es justo la vía que toman los videos de Snyk y Net Ninja de la tarjeta de fuentes.
- 4
Lanza Codex y verifica con /mcp
Arranca codex en tu proyecto y escribe /mcp. El panel MCP Tools lista cada servidor configurado con su estado, el comando de lanzamiento exacto y las herramientas que expone — Context7 muestra query_docs y resolve-library-id. Cualquier cosa que falte aquí significa que la entrada cayó en el archivo equivocado o que el servidor no arrancó.
El panel /mcp dentro de la TUI de Codex: context7 está activado y sus dos herramientas aparecen por nombre.Ver en 1:05
Parte 2 — Úsalo y pásate a remoto
- 5
Haz un prompt que de verdad use el servidor
Las herramientas MCP se invocan a demanda, así que pide algo que las necesite: "Usa Context7 para consultar la documentación actual de Tailwind CSS". Codex resuelve la librería, trae la documentación a través del servidor MCP y cita las fuentes en su respuesta. Ver desfilar las llamadas a herramientas es tu prueba de que el servidor funciona de principio a fin.
La respuesta de Codex cita las URLs exactas de la documentación de Context7 que trajo a través del servidor MCP.Ver en 1:30 - 6
Añade un servidor remoto con --url
Muchos proveedores también hospedan su servidor MCP en remoto — sin proceso local, sin npx. Registra uno con codex mcp add context7 --url https://mcp.context7.com/mcp. Codex detecta el soporte de OAuth automáticamente, imprime "Detected OAuth support. Starting OAuth flow..." y abre tu navegador para autorizar. En config.toml la entrada es solo url = "https://mcp.context7.com/mcp" bajo [mcp_servers.context7].
El flujo remoto completo en una terminal: el add con --url, la detección de OAuth, la URL de autorización y Successfully logged in.Ver en 2:22 - 7
Aprueba la pantalla de consentimiento de OAuth
El navegador pregunta si Codex puede acceder a tu cuenta en nombre del proveedor. Revisa los scopes solicitados, pulsa Allow y la terminal confirma "Successfully logged in". Para servidores sin flujo de OAuth, autentica aparte con codex mcp login <name>; los servidores con token usan en cambio bearer_token_env_var apuntando a una variable de entorno.
La pantalla de consentimiento de Context7: revisa los scopes que pide Codex y pulsa Allow.Ver en 2:02 - 8
Acota un servidor a un proyecto con .codex/config.toml
Los servidores que solo tienen sentido en un repo — como DBHub, un servidor stdio que habla con tu base de datos — van en la configuración de proyecto. Crea una carpeta .codex en el repo, añade un config.toml con la entrada [mcp_servers.dbhub] y pasa tu cadena de conexión por el argumento --dsn (ajústala del ejemplo de Postgres de la documentación a MySQL o lo que uses). Haz commit y tus compañeros reciben el mismo servidor; la carpeta debe ser un proyecto de confianza para que cargue.
Un .codex/config.toml de proyecto: DBHub corre por stdio con el DSN de la base de datos del repo en los args.Ver en 3:30
Parte 3 — Servidores reales y control del día 2
- 9
Consulta tu base de datos con herramientas MCP
Con DBHub configurado, pregúntale a Codex por la base de datos: "Encuentra la base de datos de Petco y explica las tablas", y luego "¿Cuál es el producto más vendido?". Codex llama a las herramientas describe_table y execute_sql del servidor, pide permiso antes de ejecutar SQL y responde con números reales de tus datos. Es la forma más rápida de depurar esquemas y validar datos mientras trabajas en un backend.
Codex ejecutó la herramienta execute_sql de dbhub y respondió con el producto más vendido y sus ingresos.Ver en 4:40 - 10
Conecta GitHub con su servidor MCP remoto
El README de github/github-mcp-server documenta la configuración para Codex: añade una entrada [mcp_servers.github] con url = "https://api.githubcopilot.com/mcp/" y autentica por OAuth o exportando un token de acceso personal como variable de entorno (crea un PAT fine-grained en GitHub Settings, Developer settings, concediendo Administration y Contents). Los servidores remotos-primero como este y el servidor MCP de Figma siguen el mismo patrón que el paso 6.
La guía de instalación del servidor MCP de GitHub: la entrada para Codex CLI más la nota de autenticación OAuth/PAT.Ver en 5:22 - 11
Relanza y pon las herramientas a trabajar
Reinicia codex y mira el banner: "Starting servers (0/3): context7, dbhub, github". Ahora basta una sola instrucción como "Haz un fork del repo openai/codex a mi cuenta" — Codex elige la herramienta fork de GitHub, pide aprobación y lo hace. Sin configuración por tarea: las herramientas son simplemente parte de cada sesión de aquí en adelante.
- 12
Gestiona servidores con codex mcp list y la app de escritorio
codex mcp list imprime cada servidor configurado desde la shell; eliminar uno supone borrar su bloque de config.toml y volver a ejecutar el comando para confirmar. La app de escritorio y la extensión de IDE leen el mismo ~/.codex/config.toml, así que los servidores instalados aquí aparecen en Settings, MCP servers de la app de escritorio con interruptores de encendido y apagado.
Los ajustes de servidores MCP de la app de escritorio de Codex: context7, dbhub y github con interruptores, más servidores recomendados.Ver en 7:30
Servidores MCP locales stdio vs remotos en Codex
Ambos tipos viven en las mismas tablas [mcp_servers.*] y aparecen en el mismo panel /mcp — la diferencia está en dónde corre el servidor y cómo se autentica. Elige por servidor, no por proyecto.
- 1stdio local: Codex lanza él mismo un proceso con command y args — normalmente npx o un binario. Corre en tu máquina, así que puede alcanzar servicios de localhost como una base de datos de desarrollo (así consultó DBHub MySQL en el recorrido), pero tú provees el runtime y las actualizaciones.
- 2Remoto: Codex habla con una url hospedada por HTTP streamable. Sin proceso que mantener vivo y con la autenticación centralizada — OAuth por defecto, o bearer_token_env_var y http_headers para esquemas con token. El propio ejemplo de la documentación es [mcp_servers.figma] con url = "https://mcp.figma.com/mcp".
- 3stdio ejecutado en remoto: un término medio experimental. Definir experimental_environment = "remote" en una entrada stdio mueve su ejecución a un ejecutor remoto, con env_vars decidiendo qué variables viajan — incluidas las marcadas con source = "remote". Es el camino que Codex 0.160.1 reforzó.
- 4Alcance: codex mcp add siempre escribe en el ~/.codex/config.toml global; los servidores específicos de proyecto van en .codex/config.toml dentro del repo (solo proyectos de confianza). Global para las herramientas que quieres en todas partes, proyecto para todo lo que lleve credenciales específicas del entorno.
- 5Controles que aplican a ambos: startup_timeout_sec (10 por defecto) y tool_timeout_sec (60 por defecto) para servidores lentos, enabled/disabled_tools para permitir en lista blanca lo que Codex puede llamar, y required = true si un servidor debe levantarse sí o sí o Codex debería negarse a arrancar.
Un valor por defecto práctico: los servidores de documentación de solo lectura como Context7 pueden ser globales; cualquier cosa que toque credenciales o datos — DBHub, GitHub con un PAT — pertenece a la configuración de proyecto, donde se puede revisar y revocar junto con el repo.
Configurado pero no funciona: los sospechosos habituales
La mayoría de fallos de MCP en Codex son problemas de alcance, timeout o autenticación — en ese orden. Recorre esta lista antes de tocar el servidor.
- 1El servidor no aparece en /mcp: comprueba qué archivo editaste. Las entradas globales viven en ~/.codex/config.toml; las de proyecto en .codex/config.toml y solo para proyectos de confianza. Ejecutar codex mcp list desde la shell muestra lo que Codex ve de verdad.
- 2El servidor agota el tiempo al arrancar: el startup_timeout_sec por defecto son 10 segundos, y una descarga fría de npx de un paquete grande puede superarlos de sobra. Preinstala el paquete o sube el startup_timeout_sec de la entrada.
- 3Las llamadas a herramientas fallan con 401/403: falta la credencial o está caducada. Ejecuta codex mcp login <name> para servidores OAuth, o define bearer_token_env_var y exporta la variable. Tras arreglarlo, /mcp debería mostrar el servidor activado de nuevo.
- 4Un servidor stdio remoto se cae con errores raros de Windows: antes de 0.160.1, lanzar un servidor MCP stdio remoto con variables de entorno remotas configuradas explícitamente podía perder SYSTEMROOT, TEMP y TMP, rompiendo el entorno de arranque del ejecutor de Windows. Actualiza a 0.160.1 o superior.
- 5El servidor arranca pero las respuestas salen mal o vacías: muchos servidores hospedados necesitan su propia clave de API incluso sobre OAuth — Context7, por ejemplo, quiere una clave de API pasada por env. Consulta la documentación del proveedor para el nombre exacto del env y añádelo a la tabla env de la entrada.
Dos palancas útiles mientras depuras: define required = true en un servidor del que dependas para que Codex nunca arranque en silencio sin él, y enabled = false para apagar uno sin borrar su configuración.