MCP en Codex: config.toml, clave y timeouts

Q: ¿Cómo conecto MCP a Codex?

Añade a ~/.codex/config.toml una sección [mcp_servers.nombre] . Para un servidor remoto, indica url y, si hace falta clave, bearer_token_env_var con el nombre de una variable de entorno. O ejecuta codex mcp add nombre --url dirección y Codex escribe la sección solo.

Q: ¿Dónde está la configuración MCP de Codex?

En ~/.codex/config.toml para todos los proyectos, y en .codex/config.toml en la raíz de un proyecto de confianza, sólo para ese proyecto.

Q: ¿Por qué una herramienta MCP en Codex falla por timeout?

Porque tool_timeout_sec vale 60 segundos por defecto. Las herramientas lentas —la generación de vídeo y, a veces, de imágenes en alta resolución— no caben ahí. Sube el valor en la sección del servidor, por ejemplo a 600 para vídeo.

En corto: Codex guarda los servidores MCP en ~/.codex/config.toml, en secciones [mcp_servers.nombre]. Un servidor remoto necesita url, y la clave Codex la toma de una variable de entorno cuyo nombre se indica en bearer_token_env_var. Y un ajuste que casi todo el mundo se salta: por defecto, una llamada a una herramienta se corta a los 60 segundos.

Dónde guarda Codex los servidores MCP

Los ajustes globales, en ~/.codex/config.toml. Para un proyecto de confianza se puede crear un .codex/config.toml en su raíz, y esos servidores se activarán sólo ahí. El archivo está en formato TOML y cada servidor es una sección. Qué es un servidor MCP y para qué lo quiere un agente está en el repaso de los servidores MCP.

Paso 1. La clave en una variable de entorno

Codex no guarda la clave en la configuración: la lee del entorno al conectarse. Consigue una clave (sin registro):

Una clave para Codex

Consigue una clave sk-… en esta misma página

Elige la serie de modelo que quieras: Codex funciona con su propio modelo y a los servidores MCP sólo les hace falta la clave. Se sustituye en la línea de abajo.

Pulsa y obtén tu base_url y tu clave API.

Sin registro ni tarjeta.

Gratis. Tu clave aparecerá aquí mismo.

Plantilla — así no va a funcionar~/.zshrc o ~/.bashrcLo resaltado son marcadores. El botón de arriba los emite en segundos, sin registro.

export TWELVER_API_KEY="sk-<tu-clave>"

Abre una terminal nueva, o ejecuta source ~/.zshrc, para que la variable exista en la shell actual.

Paso 2. Las secciones mcp_servers en config.toml

[mcp_servers.twelver-web-search]
url = "https://twelver.app/api/mcp/v1/web-search"
bearer_token_env_var = "TWELVER_API_KEY"

[mcp_servers.twelver-image]
url = "https://twelver.app/api/mcp/v1/image-generation"
bearer_token_env_var = "TWELVER_API_KEY"
tool_timeout_sec = 120

Ojo: en bearer_token_env_var se escribe el nombre de la variable, no la clave. Codex añade solo la cabecera Authorization: Bearer … a cada petición.

O con un solo comando

El servidor se puede añadir desde la terminal y Codex escribe la sección por ti. El nombre de la variable con la clave hay que añadirlo después a la sección de todos modos (bearer_token_env_var), o entrar por OAuth, para lo cual hace falta una cuenta registrada:

codex mcp add twelver-web-search --url https://twelver.app/api/mcp/v1/web-search
codex mcp login twelver-web-search

Paso 3. Timeouts: por qué la generación «falla» al minuto

Codex tiene dos timeouts por servidor, y conviene conocer los dos:

Parámetro	Por defecto	De qué se ocupa
`startup_timeout_sec`	10 segundos	Conectarse al servidor y recibir su lista de herramientas
`tool_timeout_sec`	60 segundos	Ejecutar una llamada a una herramienta

Según la documentación de Codex el 17 de septiembre de 2026.

Para la búsqueda, un minuto sobra. Para generar una imagen en alta resolución, no siempre. Y la generación de vídeo mantiene la llamada abierta hasta que el clip está listo, y eso son minutos. Si Codex avisa de un timeout y aun así se descontaron tokens, es justamente este caso: el servidor terminó el trabajo, pero el cliente ya había dejado de esperar la respuesta. Sube el timeout del servidor de vídeo por adelantado:

[mcp_servers.twelver-video]
url = "https://twelver.app/api/mcp/v1/seedance-video-generation"
bearer_token_env_var = "TWELVER_API_KEY"
tool_timeout_sec = 600

La búsqueda, global; la generación, por proyecto

Las descripciones de las herramientas de todos los servidores conectados se le envían al modelo en cada petición. La búsqueda sirve en casi cualquier tarea: su sitio es ~/.codex/config.toml. La generación de imágenes y vídeo es más sensato activarla en el .codex/config.toml de los proyectos que la necesitan, por ejemplo un frontend o una landing.

Paso 4. Compruébalo

Arranca codex y dale una tarea que necesite una herramienta: «busca qué breaking changes trae la última versión mayor de nuestro ORM y comprueba si afectan a nuestro código». Codex llamará a web-search, leerá el changelog y sólo después recorrerá los archivos del proyecto. La lista de servidores conectados la muestra:

codex mcp list

Si no funciona

Síntoma	Causa	Qué hacer
401 al conectar	La variable de entorno está vacía en la shell donde corre Codex	Comprueba echo $TWELVER_API_KEY; en bearer_token_env_var debe ir el nombre de la variable, no la clave
El servidor no llega a conectar en 10 segundos	Red lenta en la primera conexión	Sube startup_timeout_sec a 20–30
La llamada se corta al minuto	tool_timeout_sec vale 60 por defecto	Para imágenes, 120; para vídeo, 600
Los servidores no aparecen en el proyecto	El .codex/config.toml de proyecto sólo se lee en un proyecto de confianza	Marca el proyecto como de confianza, o pasa las secciones a ~/.codex/config.toml

El mismo par «URL + clave» funciona en OpenCode y en Claude Code. Qué más conviene conectar además de la búsqueda está en la selección de los mejores servidores MCP.

Preguntas frecuentes

¿Cómo conecto MCP a Codex?

Añade a ~/.codex/config.toml una sección [mcp_servers.nombre]. Para un servidor remoto, indica url y, si hace falta clave, bearer_token_env_var con el nombre de una variable de entorno. O ejecuta codex mcp add nombre --url dirección y Codex escribe la sección solo.

¿Dónde está la configuración MCP de Codex?

En ~/.codex/config.toml para todos los proyectos, y en .codex/config.toml en la raíz de un proyecto de confianza, sólo para ese proyecto.

¿Cómo le paso un token al servidor MCP en Codex?

Pon el token en una variable de entorno e indica su nombre en bearer_token_env_var: Codex añade solo la cabecera Authorization: Bearer. Para otras cabeceras existe http_headers. Si el servidor admite OAuth, puedes entrar con codex mcp login nombre.

¿Por qué una herramienta MCP en Codex falla por timeout?

Porque tool_timeout_sec vale 60 segundos por defecto. Las herramientas lentas —la generación de vídeo y, a veces, de imágenes en alta resolución— no caben ahí. Sube el valor en la sección del servidor, por ejemplo a 600 para vídeo.

¿Qué servidores MCP son útiles en Codex?

Sobre todo la búsqueda en internet con lectura de páginas (documentación y changelogs recientes), el acceso a GitHub y un navegador para revisar la interfaz. Una selección por tareas está en los mejores servidores MCP.

Pruébalo tú mismo

Todo lo de esta guía funciona en Twelver

Un chat para texto, imágenes, vídeo, música y voz — sin servicios ni suscripciones aparte.

Abrir el chat de Twelver

Página relacionadaToolsets MCP

Califica tu experiencia