Configuración del servidor Codex MCP

MCP (Model Context Protocol, Protocolo de Contexto de Modelo) permite a Codex integrarse con herramientas y servicios externos.

Esta sección detalla cómo configurar y utilizar servidores MCP.


¿Qué es MCP?

MCP es un protocolo abierto que permite a los modelos de IA interactuar de forma estandarizada con herramientas y servicios externos. Mediante servidores MCP, puedes ampliar las capacidades de Codex:

  • Conectar sistemas de archivos
  • Acceder a bases de datos
  • Integrar herramientas de gestión de proyectos
  • Llamar APIs externas
MCP se basa en unModel Context Protocolestándar abierto, que admite integración estandarizada entre diferentes herramientas.

Configuración básica de MCP

Menú de configuración de Codex

Puedes gestionar o añadir servicios MCP a través del menú de configuración:

Conectar a MCP personalizado:

Ubicación del archivo de configuración

Los servidores MCP se configuran en la~/.codex/config.tomldemcp_serverssección.

Servidores tipo stdio

Configurar servidor MCP stdio

[mcp_servers.filesystem]
# Comando de inicio del servidor
command = "npx"

# Parámetros pasados al comando
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]

# Directorio de trabajo del servidor
cwd = "/path/to/workdir"

# Variables de entorno pasadas
env = {
    NODE_ENV = "production"
}

Servidores tipo HTTP

Configurar servidor MCP HTTP

[mcp_servers.docs]
# Endpoint del servidor MCP HTTP
url = "https://docs.example.com/mcp"

# Cabeceras HTTP incluidas
http_headers = {
    Authorization = "Bearer token"
}

Configuración de herramientas MCP

Limitar herramientas disponibles

Puedes limitar las herramientas expuestas por el servidor MCP:

Lista blanca/negrita de herramientas

[mcp_servers.filesystem]
# Lista de herramientas permitidas
enabled_tools = ["read_file", "write_file", "list_directory"]

# Lista de herramientas denegadas (se aplica después de enabled_tools)
disabled_tools = ["delete_file"]
Usar restricciones de herramientas mejora la seguridad, exponiendo solo las herramientas que necesitas.

Configuración de tiempo de espera

Configurar tiempo de espera

[mcp_servers.slow_server]
command = "python"
args = ["-m", "slow_server"]

# Tiempo de espera de inicio (segundos, predeterminado 10)
startup_timeout_sec = 30

# Tiempo de espera por llamada de herramienta (segundos, predeterminado 60)
tool_timeout_sec = 120

Configuración de autenticación MCP

Configuración de OAuth

Configurar OAuth

[mcp_servers.protected]
url = "https://api.example.com/mcp"

# Ámbitos OAuth solicitados
scopes = ["read", "write"]

# Parámetros de recurso OAuth
oauth_resource = "codex-integration"

# Variable de entorno del token Bearer
bearer_token_env_var = "EXAMPLE_API_TOKEN"

Configuración de cabeceras HTTP

Configurar cabeceras HTTP

[mcp_servers.api]
url = "https://api.example.com/mcp"

# Rellenar cabeceras HTTP desde variables de entorno
env_http_headers = {
    X_API_KEY = "MY_API_KEY"
}

# Cabeceras HTTP estáticas
http_headers = {
    X_Custom_Header = "value"
}

Configuración de devolución de llamada OAuth

Configurar devolución de llamada OAuth

# Puerto de devolución de llamada fijo
mcp_oauth_callback_port = 8080

# URL de devolución de llamada personalizada
mcp_oauth_callback_url = "https://my-devbox.example.com/callback"

# Ubicación de almacenamiento de credenciales
mcp_oauth_credentials_store = "keyring"  # file | keyring | auto

Permisos de herramientas MCP

Puedes establecer permisos individualmente para las herramientas de cada servidor MCP:

Configurar permisos de herramientas

[mcp_servers.docs.tools.search]
# Modo de permiso: ask | approve | deny
approval_mode = "approve"
Modo de permisoDescripción
askPreguntar antes de cada ejecución (predeterminado)
approveAprobación automática
denyDenegación automática
Ten cuidado al configurar permisos de herramientas; asegúrate de otorgar aprobación automática solo a herramientas en las que confíes.

Servidores MCP comunes

Servidor de sistema de archivos

MCP de sistema de archivos

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]

Servidor de GitHub

GitHub MCP

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = {
    GITHUB_PERSONAL_ACCESS_TOKEN = "your-token-here"
}

Servidor de PostgreSQL

PostgreSQL MCP

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]

Servidores MCP comunes

Puedes instalar más servidores MCP mediante npm:

# 搜索 MCP 服务器
npm search @modelcontextprotocol/server

# 安装 MCP 服务器
npm install -g @modelcontextprotocol/server-filesystem
OpenAI proporciona oficialmente múltiples servidores MCP; consulta elrepositorio de GitHubpara obtener la lista completa.

Solución de problemas

Error al iniciar el servidor

Comprueba lo siguiente:

  • Si el comando y los parámetros son correctos
  • Si las dependencias necesarias están instaladas
  • Si las variables de entorno están establecidas correctamente

Tiempo de espera agotado en llamada de herramienta

Aumenta el tiempo de espera:

tool_timeout_sec = 120

Problemas de autenticación

Asegúrate de que el puerto de devolución de llamada OAuth no esté ocupado y de que el almacenamiento de credenciales esté configurado correctamente.

Usacodex --verbosepara ver información detallada de depuración de MCP.

Preguntas frecuentes

P: ¿No puede iniciarse el servidor MCP?

Comprueba que el comando esté instalado correctamente; intenta ejecutar el comando manualmente para confirmar que no haya errores.

P: ¿Dónde se configuran los permisos de herramientas?

En lamcp_servers.<id>.tools.<tool>sección del archivo de configuración.

P: ¿Cómo deshabilitar un servidor MCP?

Añade en la configuraciónenabled = falseo elimina directamente la configuración.

P: ¿Cuántos servidores MCP se admiten?

No hay un límite estricto, pero se recomienda configurar solo los servidores que realmente necesites.

Otras extensiones