Conexiones MCP

Un servidor MCP publica definiciones de herramientas y ejecuta llamadas a herramientas. La API de agentes descubre las herramientas, llama al servidor y devuelve los resultados al agente. Tu aplicación no necesita gestionar cada llamada.

Elige desde dónde se establece la conexión según desde dónde se pueda acceder al servidor:

Conectarse desde OpenAI

Agrega un servidor MCP HTTP a agent.tools. El servidor debe ser accesible desde OpenAI. Esto funciona con o sin un entorno de sesión.

Por ejemplo, el MCP de la documentación de OpenAI permite el acceso anónimo:

12345678910{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

Conectarse desde tu entorno

Un MCP del ejecutor se conecta desde el entorno de la sesión. Úsalo para servidores en una red privada o software instalado en ese entorno.

Establece environment.type de la sesión en self_hosted o openai_hosted. Para un entorno autoalojado, conecta el ejecutor antes de que el agente use sus herramientas.

Conectarse por HTTP

Usa HTTP para un servidor que ya esté en ejecución. Agrega esta entrada a agent.tools y reemplaza la URL por una dirección accesible desde tu entorno:

12345678910{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

Aquí, una URL de localhost hace referencia al entorno de la sesión. Si omites connection_origin, OpenAI establece la conexión en su lugar.

Iniciar un servidor mediante stdio

Usa stdio para permitir que el ejecutor inicie un proceso de servidor. Primero instala el servidor y sus dependencias en el entorno.

Para este ejemplo de consulta de clientes, instala el SDK de MCP:

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

Guarda el servidor como /workspace/lookup_mcp.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

Agrega el servidor a agent.tools. El argumento stdio selecciona el transporte del script:

1234567891011{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

Para stdio, se requieren command y una ruta absoluta en cwd; args es opcional. Omite connection_origin.

Envía un mensaje pidiéndole al agente que busque al cliente 123. La herramienta devuelve Example Customer, que tiene el plan pro.

Para los MCP con stdio alojados en OpenAI, omite la política de red o establécela en enabled. Las políticas de red disabled y restricted no son compatibles con estas conexiones.

Agregar autenticación

Para un servidor que permite el acceso anónimo, omite los campos de autenticación y vault_ids. De lo contrario, elige el origen de las credenciales para tu conexión:

• Credenciales HTTP para una sesión: establece transport.authorization o transport.headers al crear la sesión. La API de agentes cifra estos valores y los omite del recurso de sesión devuelto.
• Credenciales HTTP reutilizables: almacena las credenciales en una bóveda y adjúntala mediante vault_ids. Las bóvedas solo se aplican a las conexiones desde OpenAI. Las credenciales se asocian según la URL del servidor; usa credential_id para seleccionar una cuando haya varias coincidencias.
• Credenciales de stdio: proporciona los valores en el entorno y enumera sus nombres en transport.env_vars. El código que se ejecuta en el entorno puede leer estos valores. Las sesiones autoalojadas no aceptan valores definidos directamente en transport.env.

Por ejemplo, un transporte HTTP puede incluir un token de portador y otro encabezado:

123456{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Usa un solo origen para Authorization: la configuración directa o una credencial coincidente de una bóveda. Otros encabezados pueden acompañar la autenticación mediante bóveda. Las conexiones HTTP que se originan en el entorno no usan credenciales de bóvedas; usa autenticación definida directamente en la configuración o un proxy de confianza.

Mantén los secretos fuera de las definiciones de agentes reutilizables, los archivos de complementos y los registros. Para que las credenciales sean inaccesibles para el código generado por el agente, usa un proxy o servidor de confianza que las proporcione fuera del entorno.

Controlar el acceso a las herramientas y el inicio

Configura allowed_tools para limitar las herramientas que el agente puede descubrir y llamar. Configura required: true para que el turno falle si el servidor no puede inicializarse. La inicialización es opcional de forma predeterminada.

Consulta la referencia de Crear sesión para conocer todos los campos de configuración de MCP.

Solucionar problemas de conexión

Si un servidor obligatorio no puede inicializarse, revisa el error en agent.session.turn.failed. Para los servidores con stdio, revisa también los registros del proceso MCP.

• Acceso a la red: verifica la URL y connection_origin. Para las conexiones desde el entorno, verifica que el ejecutor esté conectado y que su red pueda acceder al servidor.
• Credenciales: verifica el token o los encabezados. Si usas una bóveda, verifica que la credencial coincida con la URL del servidor.
• Ejecutable y dependencias: verifica que el comando configurado se ejecute dentro del entorno.
• Directorio de trabajo: para una configuración directa de stdio, usa en cwd una ruta absoluta a un directorio existente.

Guías relacionadas

• Los complementos empaquetan la configuración de MCP y las habilidades para reutilizarlas en distintas sesiones.
• La guía de búsqueda de herramientas explica el descubrimiento automático de herramientas MCP en los modelos y proveedores compatibles.