Codex MCP: cómo conectar herramientas y servidores externos
Aprende
cómo usar Model Context Protocol con Codex
para conectar
documentación,
APIs,
navegadores,
plataformas de desarrollo
y herramientas externas.
Veremos
servidores
STDIO y Streamable HTTP,
configuración mediante
config.toml,
OAuth,
tokens,
variables de entorno,
herramientas permitidas,
aprobaciones,
timeouts,
configuración por proyecto
y cómo combinar
MCP con Skills
y Subagents.
¿Qué es MCP en Codex?
MCP, o Model Context Protocol, permite conectar Codex con herramientas y fuentes de información externas. Un servidor MCP puede ofrecer herramientas, datos y acciones que Codex puede utilizar durante una tarea. Por ejemplo, Codex puede consultar documentación técnica, interactuar con herramientas de desarrollo, acceder a servicios autorizados o utilizar un navegador conectado mediante MCP.
Qué puede aportar un servidor MCP a Codex
Documentación
Consultar documentación actualizada durante la implementación.
APIs
Consumir herramientas proporcionadas por servicios externos.
Navegador
Inspeccionar una interfaz o aplicación web mediante herramientas compatibles.
Desarrollo
Conectar plataformas utilizadas por equipos técnicos.
Datos
Consultar fuentes que no viven dentro del repositorio.
Acciones
Ejecutar operaciones externas cuando el servidor las expone y están autorizadas.
Codex decide cuándo utilizar las herramientas disponibles
Recibe una tarea
Codex analiza qué necesita para resolverla.
Descubre tools
El servidor MCP publica las herramientas disponibles.
Invoca
Codex utiliza una herramienta cuando aporta valor.
Continúa
Incorpora el resultado al trabajo del agente.
STDIO vs Streamable HTTP
Proceso local
Codex inicia un programa local mediante un comando.
- command
- args
- variables de entorno
- directorio de trabajo
Servidor por URL
Codex se conecta a un endpoint MCP mediante HTTP.
- URL
- OAuth
- Bearer token
- headers HTTP
Cuándo usar cada tipo
Desktop, CLI e IDE utilizan la misma configuración MCP
La configuración MCP local de Codex se almacena junto con el resto de la configuración del agente. Una vez añadido un servidor, puede estar disponible desde la aplicación de escritorio, Codex CLI y la extensión IDE.
~/.codex/config.tomlTambién puedes definir MCP solo para un repositorio
mi-proyecto/
├── .codex/
│ └── config.toml
│
├── AGENTS.md
├── src/
└── tests/Esto ayuda a evitar que un repositorio desconocido pueda activar automáticamente configuración MCP sin que previamente confíes en ese proyecto.
Añadir un servidor MCP desde terminal
La sintaxis para un servidor STDIO es:
codex mcp add <server-name> -- <command>Ejemplo con Context7:
codex mcp add context7 -- npx -y @upstash/context7-mcpAdministrar servidores MCP desde Codex CLI
# Ver servidores configurados
codex mcp list
# Ver ayuda completa
codex mcp --help
# Autenticar un servidor OAuth
codex mcp login <server-name>
Utiliza
/mcp
para ver
los servidores MCP
activos
desde
una sesión
de Codex CLI.
Configurar un servidor STDIO manualmente
[mcp_servers.context7]
command = "npx"
args = [
"-y",
"@upstash/context7-mcp"
]| Opción | Uso |
|---|---|
command |
Programa que inicia el servidor |
args |
Argumentos del comando |
env |
Variables definidas específicamente para el servidor |
env_vars |
Variables existentes que Codex puede reenviar |
cwd |
Directorio donde iniciar el proceso |
Pasar credenciales sin escribirlas en config.toml
[mcp_servers.my_server]
command = "node"
args = ["server.js"]
env_vars = [
"MY_API_TOKEN"
]También puedes establecer variables concretas:
[mcp_servers.my_server.env]
MODE = "development"
Si versionas
.codex/config.toml,
utiliza
referencias
a variables
de entorno
en lugar
de credenciales
reales.
Conectar Codex con un servidor MCP remoto
[mcp_servers.example]
url = "https://mcp.example.com/mcp"Los servidores Streamable HTTP pueden utilizar diferentes métodos de autenticación, incluyendo tokens y OAuth.
Autenticación mediante variable de entorno
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"Así puedes mantener la configuración compartible sin guardar directamente el token.
Añadir headers personalizados
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
http_headers = {
"X-Region" = "south-america"
}
Para valores
sensibles
también puedes
obtener
headers
desde variables
de entorno
mediante
env_http_headers.
Autenticar un servidor MCP con OAuth
Cuando el servidor soporta OAuth, inicia el proceso con:
codex mcp login <server-name>Codex inicia OAuth
Abre el flujo de autorización compatible.
Usuario autoriza
Concede los permisos solicitados.
Codex guarda credenciales
Quedan asociadas al servidor MCP.
Las tools quedan disponibles
Según permisos y configuración.
Servidores con Client ID pre-registrado
codex mcp add example \
--url https://mcp.example.com \
--oauth-client-id my-clientCodex mostrará la callback URL que debes registrar con el proveedor.
Para servidores MCP habituales con OAuth no necesitas configurar manualmente un Client ID salvo que el proveedor lo requiera.
No tienes que exponer todas las herramientas del servidor
Puedes limitar
las tools
que Codex
puede utilizar
de un servidor
mediante
enabled_tools.
[mcp_servers.browser]
url = "http://localhost:3000/mcp"
enabled_tools = [
"open",
"screenshot"
]Bloquear herramientas específicas
[mcp_servers.browser]
enabled_tools = [
"open",
"screenshot",
"click"
]
disabled_tools = [
"click"
]
En este ejemplo,
aunque
click
aparece
en la lista
permitida,
finalmente
queda deshabilitada.
Controla cuándo Codex debe pedir permiso
[mcp_servers.browser]
default_tools_approval_mode = "prompt"| Modo | Comportamiento |
|---|---|
auto |
Codex aplica el comportamiento automático correspondiente |
prompt |
Solicita aprobación antes de la tool |
writes |
Solicita aprobación para tools que no estén marcadas como read-only |
approve |
La herramienta queda aprobada según esa configuración |
Una tool puede tener su propia política
[mcp_servers.browser.tools.open]
approval_mode = "approve"
[mcp_servers.browser.tools.delete_resource]
approval_mode = "prompt"Una tool de lectura puede tener una política menos restrictiva que una acción capaz de modificar o eliminar información.
Controlar cuánto espera Codex por un servidor MCP
[mcp_servers.my_server]
startup_timeout_sec = 20
tool_timeout_sec = 45| Configuración | Predeterminado |
|---|---|
startup_timeout_sec |
10 segundos |
tool_timeout_sec |
60 segundos |
Servidor opcional vs servidor obligatorio
[mcp_servers.internal_docs]
url = "https://mcp.example.com"
required = trueSi un servidor habilitado y marcado como obligatorio no puede iniciarse, Codex puede hacer fallar el inicio o reanudación correspondiente, en lugar de continuar sin esa herramienta.
Mantener la configuración sin iniciar el servidor
[mcp_servers.experimental]
url = "https://example.com/mcp"
enabled = falseAsí puedes conservar la configuración sin eliminarla.
Limitar cuánto contenido devuelve una tool
[mcp_servers.docs.tools.search]
output_token_limit = 12000Si una tool puede devolver grandes cantidades de texto, limitar su salida ayuda a proteger la ventana de contexto del agente.
Un servidor MCP también puede explicar a Codex cómo usar sus tools
Durante
la inicialización,
Codex puede leer
el campo MCP
instructions
enviado
por el servidor
y utilizarlo
como guía
general
para trabajar
con sus herramientas.
Esto resulta útil para describir:
Orden recomendado entre tools.
Límites de uso.
Restricciones generales.
Relaciones entre operaciones.
OpenAI recomienda que los primeros 512 caracteres de estas instrucciones puedan entenderse por sí solos, ya que contienen la orientación más importante para decidir cómo utilizar el servidor.
MCP para documentación técnica
codex mcp add context7 -- npx -y @upstash/context7-mcpDespués puedes pedir:
Antes de modificar código,
consulta la documentación
actual de la librería.
Confirma:
- API recomendada
- versión
- métodos obsoletos
- ejemplo oficial
Después implementa
el cambio mínimo
compatible.MCP puede extender Codex con herramientas de navegador
[mcp_servers.browser]
url = "http://localhost:3000/mcp"
enabled_tools = [
"open",
"screenshot"
]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45Codex puede combinar análisis del código con información obtenida desde una interfaz real cuando el servidor ofrece esas tools.
La Skill define el workflow y MCP aporta la herramienta
Skill:
api-migration-review
Workflow:
1. detectar API usada
2. consultar documentación mediante MCP
3. confirmar versión actual
4. localizar breaking changes
5. modificar implementación
6. ejecutar tests
7. generar resumenUn subagente puede especializarse alrededor de una herramienta MCP
name = "docs_researcher"
description = "Verifies external APIs using official documentation."
sandbox_mode = "read-only"
developer_instructions = """
Use documentation tools
to verify APIs,
versions
and supported behavior.
Do not modify code.
Return concise,
actionable findings.
"""
[mcp_servers.documentation]
url = "https://example.com/mcp"Un servidor MCP amplía lo que el agente puede hacer
Antes de configurarlo, revisa quién mantiene el servidor, qué tools expone, qué credenciales necesita y qué acciones puede ejecutar.
Utiliza servidores de confianza.
Expón solamente las tools necesarias.
Prefiere variables de entorno para secretos.
Solicita aprobación para operaciones sensibles.
Utiliza permisos mínimos en sistemas externos.
No versionar tokens ni credenciales.
Separa tools de lectura y escritura cuando sea posible
Menor riesgo
Buscar, listar, consultar y leer información.
Mayor impacto
Crear, modificar, publicar o eliminar información.
Para un workflow de investigación, normalmente no existe razón para habilitar herramientas destructivas o de escritura.
Revisa .codex/config.toml antes de confiar en un proyecto
Un repositorio
puede contener
configuración
MCP
propia.
Antes
de marcar
como confiable
un proyecto
descargado
desde Internet,
revisa
su carpeta
.codex
y los servidores
que intenta
iniciar
o conectar.
MCP no es lo mismo que llamar directamente una API
| MCP | API tradicional |
|---|---|
| Expone herramientas al agente | Tu código consume endpoints |
| Codex decide cuándo usar una tool | Tu aplicación controla la llamada |
| Interfaz estandarizada para agentes | Cada API tiene su propio contrato |
| Útil para contextos agentic | Útil para lógica determinista de aplicaciones |
Herramienta y procedimiento son capas diferentes
Procedimiento
Explica cómo ejecutar una tarea.
Capacidad
Proporciona herramientas y datos externos.
Un Plugin puede distribuir configuración MCP
MCP es el protocolo mediante el cual las herramientas se conectan al agente.
Un Plugin es una unidad instalable que puede combinar:
Skills.
Servidores MCP.
Hooks y configuración asociada.
Problemas comunes con MCP en Codex
| Problema | Qué revisar |
|---|---|
| Servidor no aparece | codex mcp list y /mcp |
| STDIO no inicia | command, args, PATH y dependencias |
| Timeout al iniciar | startup_timeout_sec |
| Tool demasiado lenta | tool_timeout_sec |
| Error OAuth | codex mcp login y scopes |
| Token no disponible | Variable de entorno |
| Tool peligrosa visible | enabled_tools / disabled_tools |
| Demasiado contexto | output_token_limit |
| Config de proyecto ignorada | Comprueba que el proyecto esté marcado como confiable |
Configuración MCP con controles de seguridad
[mcp_servers.browser]
url = "http://localhost:3000/mcp"
enabled = true
required = false
enabled_tools = [
"open",
"screenshot"
]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
[mcp_servers.browser.tools.open]
approval_mode = "approve"
output_token_limit = 30000Cómo utilizar MCP sin convertir Codex en un agente sobrecargado
Añade solo servidores que realmente aporten contexto o acciones.
Usa allowlists de tools cuando sea posible.
Limita tools de escritura a workflows que las necesiten.
Configura aprobación para acciones sensibles.
No almacenes tokens directamente en Git.
Define timeouts razonables.
Evita servidores redundantes con tools equivalentes.
Revisa periódicamente qué integraciones siguen siendo necesarias.
Qué capa de Codex necesitas realmente
Guías relacionadas
Documentación oficial de Codex MCP
Model Context Protocol
STDIO, HTTP, OAuth, tools y configuración.
Ver MCP →Config Reference
Opciones completas de config.toml y MCP.
Ver referencia →Customization
Relación entre MCP, Skills y agentes.
Ver personalización →FAQ sobre Codex MCP
MCP, o Model Context Protocol, permite conectar Codex con herramientas, fuentes de datos y servicios externos mediante servidores que exponen capacidades al agente.
Codex soporta servidores STDIO, que se ejecutan como procesos locales, y servidores Streamable HTTP, a los que accede mediante una dirección URL.
La configuración global se almacena normalmente en ~/.codex/config.toml. También puedes usar .codex/config.toml dentro de un proyecto de confianza.
Sí. La aplicación de escritorio, Codex CLI y la extensión para IDE comparten la configuración MCP local de Codex.
Puedes utilizar codex mcp add seguido del nombre del servidor y su comando o configuración. Por ejemplo, un servidor STDIO puede añadirse ejecutando codex mcp add context7 seguido del comando que inicia ese servidor.
Desde terminal puedes ejecutar codex mcp list. Dentro de la TUI de Codex puedes utilizar /mcp para consultar los servidores activos.
Sí. Los servidores Streamable HTTP pueden utilizar OAuth. El inicio de sesión puede iniciarse desde CLI mediante codex mcp login seguido del nombre del servidor.
Sí. Puedes utilizar enabled_tools como allowlist y disabled_tools como denylist. También puedes configurar políticas de aprobación generales o específicas por herramienta.
El tiempo predeterminado de inicio de un servidor es 10 segundos. El timeout predeterminado para ejecutar una herramienta es 60 segundos. Ambos valores pueden configurarse.
Una Skill define cómo ejecutar un procedimiento reutilizable. MCP proporciona herramientas y acceso a sistemas externos. Una Skill puede utilizar herramientas MCP durante su workflow.
Sí. Los agentes personalizados pueden configurar sus propios servidores MCP o utilizar las capacidades disponibles según la configuración del workflow.
No. Un servidor MCP puede ampliar considerablemente lo que Codex puede hacer. Debes revisar su procedencia, las tools que expone, sus permisos, las credenciales requeridas y aplicar el principio de mínimo privilegio.
Codex Plugins: instala y distribuye capacidades completas
Ya sabes cómo conectar Codex con herramientas externas mediante MCP. Ahora veremos cómo los Plugins pueden empaquetar Skills, servidores MCP y otros recursos dentro de una unidad instalable, cómo utilizarlos desde Codex y cuándo crear tus propios Plugins.
Aprender Codex Plugins →