Guía de Codex CLI MCP para principiantes: conecta datos y servicios externos
Objetivos de aprendizaje
Al completar este tutorial, podrás:
- Explicar qué es MCP (Model Context Protocol) en términos sencillos
- Encontrar servidores MCP que conecten Codex a datos y servicios externos
- Agregar un servidor MCP a Codex CLI con el comando
codex mcp add - Verificar que el servidor MCP esté conectado y funcionando
- Pedir a Codex que use herramientas MCP en una conversación
Tiempo necesario: 15–20 minutos
Dificultad: Principiante
¿Qué versión cubre este tutorial? Este tutorial cubre Codex CLI —la versión de línea de comandos de Codex—. Los servidores MCP se configuran mediante el comando codex mcp y el archivo ~/.codex/config.toml. Si necesitas la aplicación de escritorio, consulta la Guía de instalación de Codex Desktop.
Requisitos previos
Antes de comenzar, asegúrate de tener lo siguiente:
| Requisito | Detalles |
|---|---|
| Codex CLI instalado | codex --version debe mostrar un número de versión. ¿No está instalado? Sigue primero la Guía de Codex CLI para principiantes |
| Codex iniciado sesión | Ejecuta codex e inicia sesión con tu cuenta de ChatGPT o clave API |
| Node.js (para algunos servidores) | Algunos servidores MCP se ejecutan via npx — descarga la versión LTS desde nodejs.org |
| Un servidor MCP para conectar | Ejemplos en este tutorial: GitHub, o un servidor local simple |
¿Qué es MCP?
MCP (Model Context Protocol, Protocolo de Contexto de Modelo) es un estándar abierto que permite a asistentes de IA como Codex conectarse a datos y servicios externos. Piensa en él como un enchufe universal: en lugar de que cada herramienta construya su propia integración personalizada, todas hablan el mismo protocolo.
Un servidor MCP es un pequeño programa que expone herramientas, datos o servicios al asistente de IA. Por ejemplo:
- Un servidor MCP de GitHub permite a Codex leer Issues, crear Pull Requests y explorar repositorios
- Un servidor MCP de base de datos permite a Codex consultar tu base de datos con lenguaje natural
- Un servidor MCP de búsqueda permite a Codex buscar en la web y devolver resultados en vivo
Cuando agregas un servidor MCP, Codex puede llamar a sus herramientas automáticamente durante una conversación — sin necesidad de copiar y pegar datos manualmente.
Cómo funciona Codex MCP
Codex CLI tiene soporte MCP integrado. Hay dos direcciones:
- 1Codex se conecta a servidores MCP (el enfoque de este tutorial) — agregas servidores con
codex mcp add, y Codex puede usar sus herramientas en conversaciones - 2Otras herramientas se conectan a Codex — el comando
codex mcp-serverexpone Codex a otros clientes MCP (uso avanzado, cubierto brevemente en FAQ)
La configuración se almacena en ~/.codex/config.toml, en la sección [mcp_servers.*]. El comando codex mcp edita este archivo por ti.
Paso 1: Verifica tu configuración MCP
Primero, confirma que tu Codex CLI soporte MCP. Abre una terminal y ejecuta:
codex mcp list
Lo que deberías ver: Un mensaje como "No hay servidores MCP configurados" (o una lista si ya agregaste algunos). Si el comando no es reconocido, actualiza Codex CLI:
npm install -g @openai/codex
Lo que deberías ver: Un número de versión impreso después de que finalice la actualización.
Paso 2: Encuentra un servidor MCP
Los servidores MCP se publican en varios lugares:
- Directorio MCP en Cataito: explora /mcp — más de 55 servidores MCP seleccionados de GitHub, Figma, bases de datos y más
- GitHub: busca
mcp-server— existen miles de servidores comunitarios - npm: muchos servidores se instalan con
npx
Para este tutorial, conectaremos el **servidor MCP de GitHub** — uno de los 55+ servidores MCP seleccionados en Cataito — que permite a Codex leer repositorios, Issues y Pull Requests.
Si prefieres un servicio diferente (Figma, Slack, una base de datos), el mismo comando codex mcp add funciona — solo cambia el nombre del servidor y el comando.
Paso 3: Agrega el servidor MCP (macOS y Linux)
En macOS o Linux, abre una terminal y registra el servidor MCP de GitHub:
codex mcp add github -- npx -y @modelcontextprotocol/server-github
Lo que deberías ver: El comando se completa sin errores, y Codex escribe la entrada del servidor en ~/.codex/config.toml.
Paso 3: Agrega el servidor MCP (Windows)
En Windows, abre PowerShell y registra el servidor MCP de GitHub:
codex mcp add github -- npx -y @modelcontextprotocol/server-github
Lo que deberías ver: El comando se completa sin errores, y Codex escribe la entrada del servidor en tu archivo de configuración (%USERPROFILE%\.codex\config.toml).
Paso 4: Verifica que el servidor esté conectado
Confirma que el servidor se registró correctamente:
codex mcp list
Lo que deberías ver: github aparece en la lista de servidores MCP configurados.
También puedes inspeccionar un solo servidor:
codex mcp get github
Lo que deberías ver: Los detalles del servidor, incluido el comando que Codex usará para iniciarlo.
Paso 5: Usa herramientas MCP en una conversación
Ahora inicia una sesión de Codex y pídele que use las herramientas de GitHub:
codex
Luego escribe un prompt que utilice el servicio conectado, por ejemplo:
Lista los Issues abiertos en el repositorio facebook/react
Lo que deberías ver: Codex llama automáticamente a las herramientas del servidor MCP de GitHub, obtiene los datos y te los resume. No necesitas configurar nada más — las herramientas MCP están disponibles para Codex en cada sesión una vez que el servidor está agregado.
Paso 6: Elimina o desactiva un servidor (Opcional)
Si ya no necesitas un servidor, elimínalo:
codex mcp remove github
Lo que deberías ver: El servidor desaparece de codex mcp list.
Para mantener la entrada pero evitar que Codex la cargue, coméntala en ~/.codex/config.toml agregando un # al inicio de la línea.
Solución de problemas
| Problema | Causa | Solución |
|---|---|---|
codex: command not found | Codex CLI no instalado | Instálalo: npm install -g @openai/codex, luego reinicia tu terminal |
mcp no es un subcomando válido | Codex CLI desactualizado | Actualiza: npm install -g @openai/codex |
Error url is not supported for stdio | La entrada del servidor usa transporte HTTP pero falta el tipo | Edita ~/.codex/config.toml y agrega transport = "streamable_http" a esa sección del servidor, o elimina la entrada y vuelve a agregarla con las banderas correctas |
| El servidor MCP se inicia pero las herramientas fallan | El servidor necesita una clave API o token | Revisa el README del servidor para las variables de entorno requeridas (ej. GITHUB_TOKEN), establécelas y reinicia Codex |
npx: command not found | Node.js no instalado | Instala Node.js LTS desde nodejs.org, luego reinicia tu terminal |
| El servidor agota el tiempo en la primera llamada | La primera ejecución descarga el paquete | Espera un momento y vuelve a intentar el prompt |
Preguntas frecuentes
¿Necesito un plan de pago para usar MCP con Codex? No. El soporte MCP es parte de Codex CLI y funciona tanto con planes de ChatGPT como con autenticación mediante clave API.
¿Puedo usar servidores MCP con un modelo diferente? Sí — las herramientas MCP están disponibles independientemente del modelo que Codex use.
¿Dónde se almacena la configuración MCP? En ~/.codex/config.toml (macOS/Linux) o %USERPROFILE%\.codex\config.toml (Windows), bajo secciones [mcp_servers.*].
¿Puedo agregar un servidor para un solo proyecto? Sí — las versiones recientes de Codex admiten codex mcp add --scoped <nombre> -- <comando> para escribir el servidor en el .codex/config.toml del proyecto en lugar del global.
¿Pueden otras herramientas usar Codex a través de MCP? Sí — ejecuta codex mcp-server para exponer Codex CLI como un servidor MCP a otros clientes MCP (como Claude Code o Cursor). Este es un caso de uso avanzado; consulta la documentación de Codex para más detalles.
Próximos pasos
- Prueba un servidor MCP de base de datos para consultar datos con lenguaje natural
- Explora el directorio oficial de MCP para encontrar servidores que se ajusten a tu flujo de trabajo
- Aprende más comandos de Codex CLI en la Guía de Codex CLI para principiantes
- Usa la Guía de instalación de Codex Desktop si prefieres una interfaz gráfica
