Codex lee los servidores MCP desde config.toml, y puedes añadirlos con un único comando codex mcp add. Este artículo muestra los ajustes exactos para servidores locales y remotos, el inicio de sesión con OAuth, los tiempos de espera y los filtros de herramientas, además de soluciones a los errores que hacen perder una tarde.
Codex es un agente de programación muy capaz por sí solo, pero solo ve lo que tú le das: tus archivos, tu shell y lo que el modelo ya sabe. Los servidores MCP cambian eso. Si añades uno, Codex puede consultar una base de datos, leer un gestor de incidencias, buscar en la documentación de una biblioteca o generar una imagen desde el mismo prompt en el que le pides código. El problema es que la configuración vive en un archivo TOML y en unos cuantos flags de la CLI, y un solo ajuste incorrecto hace que el servidor nunca aparezca, sin ningún aviso.
Este artículo te da la configuración MCP de Codex exacta para servidores locales y remotos, los comandos que la escriben por ti y soluciones a los errores que más se repiten. Los ajustes y valores por defecto que aparecen abajo coinciden con la documentación de OpenAI Codex a fecha de octubre de 2026.
MCP, el Model Context Protocol, es un estándar abierto que permite a un cliente de IA llamar a herramientas expuestas por un programa separado. Ese programa es el servidor. Codex es el cliente. Cada servidor publica una lista de herramientas con nombres, descripciones y esquemas de entrada, y Codex decide durante una tarea cuándo merece la pena llamar a una de ellas.
Sin servidores, Codex edita archivos y ejecuta comandos de shell. Con ellos, la misma sesión puede consultar tu base de datos de staging, traer una especificación de diseño o preguntarle a un índice de documentación cómo se comporta una biblioteca en su última versión, en lugar de adivinarlo a partir de sus datos de entrenamiento.
Codex admite dos tipos de servidor, y cada ajuste que escribes pertenece a uno de ellos.
| Tipo | Dónde se ejecuta | Ajuste obligatorio | Ejemplo típico |
|---|---|---|---|
| stdio | Un proceso que Codex inicia en tu equipo | command | Un servidor lanzado con npx o node |
| Streamable HTTP | Un servicio remoto al que se accede por URL | url | Un gestor de incidencias o un host de código alojado |
Los servidores stdio locales se inician cuando arranca Codex y se detienen cuando se cierra. Los servidores remotos ya están en funcionamiento en otro lugar, así que Codex solo necesita la dirección y, normalmente, una credencial.
💡 Consejo: Empieza con uno o dos servidores. Cada herramienta que expones se suma a lo que el modelo lee antes de actuar, y una lista de herramientas saturada hace que sus decisiones sean menos precisas.
Codex guarda las entradas de MCP en el mismo config.toml que usa para el resto de ajustes. No hay un archivo MCP aparte que buscar.
La ubicación por defecto es ~/.codex/config.toml. En Windows, eso corresponde a una carpeta .codex dentro de tu perfil de usuario. Los servidores definidos aquí están disponibles en todos los proyectos que abras. La aplicación de escritorio de ChatGPT, la CLI de Codex y la extensión para el IDE leen este mismo archivo, así que un servidor que añades una vez aparece en las tres.
También puedes colocar un .codex/config.toml dentro de un repositorio para limitar los servidores a ese proyecto. Codex solo lo lee en proyectos de confianza, lo que evita que un repositorio recién clonado ejecute comandos en tu equipo sin que te des cuenta. Los archivos de proyecto encajan con servidores que solo tienen sentido en una base de código, como una base de datos apuntando al esquema de desarrollo de esa aplicación, y permiten que el equipo comparta la configuración a través del control de versiones.
💡 Consejo: No subas nunca tokens al repositorio. Haz referencia a las variables de entorno por su nombre, como se muestra abajo, y guarda los valores en el perfil de tu shell o en un gestor de secretos.
La ruta más rápida es codex mcp add. Escribe la entrada TOML por ti, lo que evita errores tipográficos en los nombres de tabla y en las comillas. Úsalo primero y luego abre el archivo para afinar los detalles.
Todo lo que va después de los dos guiones es el comando que ejecutará Codex:
codex mcp add context7 -- npx -y @upstash/context7-mcp
Eso registra un servidor llamado context7, lanzado mediante npx. Para pasar variables de entorno, coloca los flags --env antes de los dos guiones:
codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- node pg-mcp-server.js
Elige nombres cortos, en minúsculas y sin espacios. El nombre se convierte en el nombre de la tabla TOML y identifica al servidor en todos los listados.
Los servidores remotos usan --url en lugar de un comando al final:
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
--bearer-token-env-var indica la variable de entorno que contiene el token. El token en sí nunca se escribe en disco, solo el nombre de la variable, lo que es mejor que pegar un secreto en una cabecera. Exporta la variable en el shell desde el que lanzas Codex:
export GITHUB_PAT_TOKEN="paste-your-token-here"
Algunos servidores alojados prescinden de tokens estáticos y usan OAuth. Añade el servidor con su URL y luego autentícate:
codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear
login inicia el flujo de OAuth, normalmente en tu navegador, y guarda las credenciales resultantes. Cuando un servidor documenta permisos concretos, añade --scopes seguido de una lista separada por comas. Para eliminar las credenciales guardadas, ejecuta codex mcp logout linear.
La CLI es rápida, pero los tiempos de espera, los filtros de herramientas y las variables reenviadas viven en el propio archivo. Cada entrada es una tabla llamada mcp_servers.<name>, con un guion bajo y un plural.
Esto es lo que produce el comando context7 de antes:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
Estos son los ajustes que acepta un servidor stdio:
| Ajuste | Obligatorio | Qué hace |
|---|---|---|
command | Sí | El programa que inicia el servidor |
args | No | Argumentos que se pasan a ese programa |
env | No | Variables de entorno definidas para el proceso del servidor |
env_vars | No | Variables de entorno existentes que se permiten y reenvían |
cwd | No | Directorio de trabajo usado al iniciar |
env define valores literales, mientras que env_vars reenvía variables que ya existen en tu shell. Para cualquier dato secreto, usa env_vars, para que el valor nunca aparezca en el archivo:
[mcp_servers.postgres]
command = "node"
args = ["pg-mcp-server.js"]
cwd = "/home/dev/db-tools"
env_vars = ["DATABASE_URL"]
[mcp_servers.postgres.env]
LOG_LEVEL = "info"
Las entradas remotas cambian command por url:
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"
| Ajuste | Obligatorio | Qué hace |
|---|---|---|
url | Sí | La dirección del servidor |
bearer_token_env_var | No | Nombre de la variable que contiene un token bearer |
http_headers | No | Nombres de cabeceras estáticas asociados a valores |
env_http_headers | No | Nombres de cabeceras asociados a nombres de variables de entorno |
Cuando un servicio quiere una cabecera personalizada en lugar de un token bearer, usa las dos tablas de cabeceras. La segunda mantiene los secretos fuera del archivo:
[mcp_servers.docs]
url = "https://docs.example.com/mcp"
[mcp_servers.docs.http_headers]
X-Team = "platform"
[mcp_servers.docs.env_http_headers]
X-Api-Token = "DOCS_API_TOKEN"
Ambos tipos de servidor aceptan los mismos ajustes opcionales:
| Ajuste | Valor por defecto | Qué hace |
|---|---|---|
startup_timeout_sec | 10 | Cuánto espera Codex a que el servidor arranque |
tool_timeout_sec | 60 | Cuánto puede tardar una sola llamada a una herramienta |
enabled | true | Ponlo en false para desactivar un servidor sin borrarlo |
enabled_tools | Sin filtro | Una lista de permitidos con las herramientas que Codex puede llamar |
disabled_tools | Sin filtro | Una lista de bloqueados con las herramientas que Codex no debe llamar |
required | false | Ponlo en true para que el arranque falle si el servidor no está disponible |
Una entrada ajustada tiene este aspecto. Sustituye los nombres de herramienta por los que /mcp muestre para tu servidor:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled_tools = ["tool_one", "tool_two"]
Una lista de permitidos es la opción más segura para servidores que pueden escribir o borrar datos. Usa disabled_tools cuando confíes en un servidor y solo quieras bloquear una o dos herramientas arriesgadas. Usa required = true en ejecuciones automatizadas, donde un servidor que falta debe detener el trabajo con un error claro en lugar de dejar que Codex continúe sin sus datos.
💡 Consejo: Pon
enabled = falseen lugar de borrar una entrada que solo necesitas de vez en cuando. Los ajustes se mantienen y basta con cambiar una línea para recuperarla.
Añadir un servidor no demuestra nada hasta que Codex muestra sus herramientas. Haz ambas comprobaciones cada vez.
En una sesión interactiva, escribe /mcp. Codex muestra los servidores conectados y las herramientas que expone cada uno. Si tu servidor no aparece, o aparece sin herramientas, nada más importa hasta que se resuelva. Reinicia la sesión después de editar el archivo para que Codex lea los nuevos ajustes.
La familia codex mcp gestiona todo sin abrir un editor:
| Comando | Finalidad |
|---|---|
codex mcp list | Muestra los servidores configurados con su estado de autenticación |
codex mcp get <name> | Inspecciona la configuración de un servidor |
codex mcp add <name> | Registra un servidor stdio o HTTP |
codex mcp remove <name> | Elimina una entrada de servidor |
codex mcp login <name> | Inicia la autenticación OAuth |
codex mcp logout <name> | Elimina las credenciales OAuth guardadas |
Añade --json a list o get cuando un script necesite leer la salida. Cuando el servidor aparezca, dale a Codex una tarea que solo ese servidor pueda responder, como pedir la firma actual de una función de biblioteca que indexa tu servidor de documentación.
La mayoría de los fallos se reducen a unas pocas causas. Revísalas en este orden.
npx -y descarga el paquete, y 10 segundos suele ser poco. Sube startup_timeout_sec a 30 o más.command directamente, así que el programa debe estar en el PATH del shell que inició Codex. Una ruta absoluta elimina la duda.npx es un script en Windows, y un lanzamiento directo puede fallar. Pásalo por cmd:[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
required = true mientras pruebas para que un servidor caído detenga la sesión con un error legible.bearer_token_env_var y env_vars leen el entorno del proceso que lanzó Codex. Una variable definida en otra pestaña de la terminal, o una aplicación de escritorio abierta desde el dock sin tu perfil de shell, no la verá. Compruébalo con echo $GITHUB_PAT_TOKEN.codex mcp logout <name> y luego codex mcp login <name> para obtener una sesión nueva..codex/config.toml en un proyecto que no es de confianza se omite. Marca el proyecto como de confianza o mueve la entrada al archivo global.tool_timeout_sec por encima de su valor por defecto de 60 segundos.Las sesiones de programación necesitan a menudo imágenes: una imagen principal para una landing page, una maqueta de producto o un clip corto para un README. PicassoIA ofrece sus modelos de generación a través de una API para desarrolladores y de conexiones MCP, así que la misma configuración de Codex puede pedir medios sin salir de la terminal.
Estos son los datos que conviene conocer antes de conectarlo:
https://api.picassoia.com/v1, y las credenciales empiezan por pia_sk_.picassoia.com/en/mcp/accounts después de iniciar sesión, y la dirección del servidor se muestra allí en lugar de publicarse en el sitio público.Una vez que tengas la dirección, el lado de Codex sigue el patrón de antes. Si la página te da una URL remota, regístrala con codex mcp add picassoia --url <address> y añade una variable de token bearer si te la pide. Si te da un comando para ejecutar en local, usa en su lugar la forma stdio. Los requisitos de plan para el acceso a la API y a MCP están en la página de precios, así que revísalos antes de construir un flujo de trabajo sobre ello.
Antes de automatizar nada, prueba un prompt a mano para saber cómo es una petición buena:
Los modelos de chat también ayudan con la configuración. Pega un error confuso en GPT 5.6 Sol o Claude Sonnet 5 y pregunta a qué ajuste TOML apunta. Ambos aparecen en PicassoIA para tareas de programación, y una segunda opinión sale barata antes de editar el archivo.
Ya tienes todo lo necesario para una configuración MCP de Codex que funcione: las ubicaciones de los archivos, los comandos de la CLI, los ajustes de ambos tipos de servidor, una rutina de verificación y una lista corta de soluciones. Añade un servidor, confírmalo con /mcp y dale a Codex una tarea real.
Si quieres ponerlo a trabajar con recursos visuales, abre PicassoIA Image y escribe tu primer prompt. Describe una escena como lo haría un fotógrafo, con la luz, la lente y las texturas, y luego compara el resultado con una versión en PicassoIA Video de la misma idea. Explora el catálogo completo en picassoia.com/en/all-models y mira lo que Picasso IA puede crear para ti.
Elige tu idioma
