Conexiones MCP

Un servidor MCP publica las definiciones de las herramientas y ejecuta las llamadas a esas 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 el origen de la conexión según desde dónde se pueda acceder al servidor:

Conectarse desde OpenAI

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

Por ejemplo, el servidor 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

El ejecutor establece la conexión MCP desde el entorno de la sesión. Usa esta conexión para acceder a servidores de una red privada o a software instalado en ese entorno.

Configura environment.type de la sesión como self_hosted u openai_hosted. Si alojas el entorno en tu propia infraestructura, conecta el ejecutor antes de que el agente use sus herramientas.

Conectarse por HTTP

Usa HTTP si el servidor 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
}

En este caso, una URL de localhost apunta al entorno de la sesión. Si omites connection_origin, OpenAI establece la conexión.

Iniciar un servidor con stdio

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

Para este ejemplo de búsqueda 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 código del servidor en /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 que usa el 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 usar stdio, debes especificar command y una ruta absoluta en cwd. El campo args es opcional. Omite connection_origin.

Envía un mensaje al agente y pídele que busque al cliente 123. La herramienta devuelve Example Customer, que tiene el plan pro.

Para los servidores MCP que usan stdio y se alojan en OpenAI, omite la política de red o configúrala como enabled. Estas conexiones no admiten las políticas de red disabled y restricted.

Agregar autenticación

Si el servidor permite el acceso anónimo, omite los campos de autenticación y vault_ids. En los demás casos, elige el origen de las credenciales para tu conexión:

• Credenciales HTTP para una sola sesión: configura transport.authorization o transport.headers al crear la sesión. La API de agentes cifra estos valores y los omite en el recurso de sesión que devuelve.
• Credenciales HTTP reutilizables: guarda las credenciales MCP en una bóveda y adjúntala a la sesión mediante vault_ids. La autenticación MCP mediante una bóveda solo se aplica a las conexiones desde OpenAI. Las credenciales se seleccionan según la URL del servidor. Si varias coinciden, usa credential_id para elegir una.
• Credenciales para stdio: define los valores de las variables en el entorno e incluye sus nombres en transport.env_vars. El código que se ejecuta en el entorno puede leer estos valores. Las sesiones alojadas en tu propia infraestructura no admiten 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: especifica el valor directamente en la configuración o usa una credencial de la bóveda que coincida con la URL del servidor. Puedes incluir otros encabezados junto con la autenticación mediante una bóveda. Las conexiones HTTP que se establecen desde el entorno no usan credenciales de la bóveda. Para esas conexiones, configura la autenticación directamente o usa un proxy de confianza.

Evita incluir secretos en las definiciones reutilizables de agentes, los archivos de complementos y los registros. Para impedir que el código generado por el agente acceda a las credenciales, usa un proxy o servidor de confianza que las proporcione fuera del entorno.

Controlar el acceso a las herramientas y el inicio del servidor

Configura allowed_tools para limitar las herramientas que el agente puede descubrir e invocar. Configura required: true para que el turno falle si el servidor no puede inicializarse. De forma predeterminada, la inicialización es opcional.

Consulta la referencia para crear una sesión para ver 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 que usan 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 se pueda acceder al servidor desde su red.
• 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: si configuras stdio directamente, usa en cwd la ruta absoluta de un directorio existente.

Guías relacionadas

• Los complementos agrupan la configuración de MCP y las habilidades para que puedas reutilizarlas en distintas sesiones.
• La guía de búsqueda de herramientas explica cómo funciona la detección automática de herramientas MCP con los modelos y proveedores compatibles.