Guía de Codex Desktop MCP: conecta datos y servicios externos
Objetivos de aprendizaje
Al completar este tutorial, podrás:
- Comprender cómo funciona MCP (Model Context Protocol) en Codex Desktop
- Agregar servidores MCP a Codex Desktop a través del archivo de configuración
- Activar y gestionar servidores MCP en el panel de Configuración de Desktop
- Usar herramientas MCP en conversaciones de Codex Desktop
Tiempo necesario: 10–15 minutos
Dificultad: Principiante
¿Qué versión cubre este tutorial? Este tutorial cubre Codex Desktop —la aplicación de escritorio gráfica de Codex—. Los servidores MCP se configuran mediante el archivo ~/.codex/config.toml, que se comparte con Codex CLI. Si usas la versión de línea de comandos, consulta la Guía de Codex MCP CLI para principiantes.
Requisitos previos
Antes de comenzar, asegúrate de tener lo siguiente:
| Requisito | Detalles |
|---|---|
| Codex Desktop instalado | Abre Codex Desktop y verifica que se inicie correctamente. ¿No está instalado? Sigue primero la Guía de instalación de Codex Desktop |
| Codex iniciado sesión | Inicia sesión con tu cuenta de ChatGPT (Plus, Pro o superior) |
| Familiaridad básica con MCP | Si eres nuevo en MCP, lee la Guía de Codex MCP CLI para principiantes para una introducción |
Cómo funciona MCP en Codex Desktop
Codex Desktop comparte el mismo sistema de configuración MCP que Codex CLI. Todos los servidores MCP se definen en el archivo ~/.codex/config.toml (macOS/Linux) o %USERPROFILE%\.codex\config.toml (Windows).
Cuando agregas un servidor MCP a través de la CLI (codex mcp add), aparece automáticamente en el panel Configuración → Servidores MCP de Codex Desktop. También puedes editar el archivo config.toml directamente.
La diferencia clave con la versión CLI:
- CLI: los servidores MCP están siempre disponibles en cada sesión
- Desktop: los servidores MCP deben estar activados en el panel de Configuración, y en algunos casos pueden necesitar autenticación OAuth
Paso 1: Abre la configuración de Servidores MCP
Abre Codex Desktop y navega a:
- 1Haz clic en tu icono de perfil o en el engranaje de Configuración en la barra lateral
- 2Selecciona Servidores MCP de la lista de configuración
Lo que deberías ver: Una lista de servidores MCP configurados (o una lista vacía si aún no hay ninguno). Cada servidor muestra su nombre, estado y un interruptor de activación/desactivación.
Paso 2: Encuentra un servidor MCP
Los servidores MCP están disponibles en varios lugares. En Cataito seleccionamos más de 55 servidores MCP listos para conectar. Para este tutorial usaremos el **servidor MCP de GitHub** — uno de los más populares, que permite a Codex leer repositorios, Issues y Pull Requests.
Explora la colección completa en el directorio MCP de Cataito.
Paso 3: Agrega el servidor MCP
Hay dos formas de agregar un servidor MCP a Codex Desktop:
Método A: Usando la CLI (Recomendado)
Si tienes Codex CLI instalado, abre una terminal y agrega el servidor. Aparecerá en Desktop automáticamente:
codex mcp add github -- npx -y @modelcontextprotocol/server-github
Lo que deberías ver: El servidor está registrado. Ahora abre Codex Desktop y ve a Configuración → Servidores MCP — el servidor de GitHub debería aparecer en la lista (puede que necesites reiniciar Codex Desktop).
Método B: Editando config.toml directamente
Abre ~/.codex/config.toml (macOS/Linux) o %USERPROFILE%\.codex\config.toml (Windows) en un editor de texto y agrega la entrada del servidor:
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
Guarda el archivo y reinicia Codex Desktop.
Lo que deberías ver: El servidor de GitHub aparece en Configuración → Servidores MCP después de reiniciar.
Paso 4: Activa el servidor MCP
En el panel Configuración → Servidores MCP:
- 1Encuentra el servidor que acabas de agregar
- 2Asegúrate de que el interruptor esté activado (verde/encendido)
- 3Si el servidor requiere autenticación OAuth, haz clic en el icono de engranaje y sigue el flujo de autenticación
Lo que deberías ver: El estado del servidor muestra "Conectado" o "Listo".
Paso 5: Usa herramientas MCP en una conversación de Desktop
Ahora inicia una nueva conversación en Codex Desktop y usa las herramientas MCP:
- 1Haz clic en Nueva conversación en la barra lateral
- 2Escribe un prompt que utilice el servidor MCP, por ejemplo:
Lista los Issues abiertos en el repositorio facebook/react
Lo que deberías ver: Codex Desktop llama automáticamente a las herramientas del servidor MCP de GitHub, obtiene los datos y muestra los resultados en la conversación. También puedes usar el comando /mcp en la conversación para ver qué herramientas MCP están disponibles.
Solución de problemas
| Problema | Causa | Solución |
|---|---|---|
| El servidor MCP aparece en Configuración pero no en la conversación | Bug de Desktop: los servidores con ámbito de proyecto pueden no cargarse en la GUI | Configura el servidor de forma global (no con ámbito de proyecto), luego reinicia Codex Desktop |
| El servidor desaparece después de reiniciar | Desktop puede sobrescribir config.toml | Vuelve a agregar el servidor con codex mcp add, o verifica si ~/.codex/config.toml está corrupto |
| La autenticación OAuth no se muestra | La configuración MCP de Desktop no muestra el estado OAuth por servidor | Autentica primero a través de la CLI: codex mcp login <nombre-servidor>, luego reinicia Desktop |
| Las herramientas MCP no están disponibles en la conversación | El servidor puede estar desactivado en Configuración | Ve a Configuración → Servidores MCP y verifica que el interruptor esté activado |
npx: command not found | Node.js no instalado | Instala Node.js LTS desde nodejs.org, luego reinicia Codex Desktop |
Preguntas frecuentes
¿Necesito Codex CLI instalado para usar MCP en Desktop? No. Puedes editar config.toml directamente, pero usar codex mcp add es la forma recomendada porque maneja correctamente la sintaxis de configuración.
¿Puedo usar los mismos servidores MCP en Desktop y CLI? Sí — comparten el mismo archivo ~/.codex/config.toml. Los servidores agregados a través de CLI aparecen en Desktop, y viceversa.
¿La versión Desktop admite todos los servidores MCP? La mayoría de los servidores MCP basados en stdio funcionan. Los servidores Streamable HTTP pueden tener problemas de compatibilidad con la versión Desktop.
¿Puedo usar MCP con un plan gratuito de ChatGPT? El soporte MCP requiere un plan de pago (Plus, Pro o superior).
Próximos pasos
- Explora el directorio MCP en Cataito — más de 55 servidores MCP seleccionados
- Lee la Guía de Codex MCP CLI para principiantes para funciones MCP avanzadas específicas de CLI
- Sigue la Guía de instalación de Codex Desktop para la instalación y configuración de escritorio
