Servidores MCP | OpenAI API

Además de las herramientas que pones a disposición del modelo mediante la llamada a funciones, puedes darle nuevas capacidades con servidores MCP remotos o Secure MCP Tunnel. Estas herramientas permiten al modelo conectarse a servicios externos y controlarlos cuando lo necesita para responder al prompt de un usuario. Como desarrollador, puedes permitir estas llamadas a herramientas de forma automática o exigir tu aprobación explícita.

Los servidores MCP remotos pueden alojarse en cualquier servidor accesible desde la internet pública que implemente el Model Context Protocol (MCP) para conexiones remotas.
Secure MCP Tunnel permite conectar un servidor MCP local o privado sin exponerlo a la internet pública.

Esta guía muestra cómo usar herramientas MCP con la API Responses. Los modelos existentes siguen siendo compatibles con los conectores integrados. Consulta la política de desuso y los ejemplos de compatibilidad en Conectores heredados. Para las sesiones de la API Agents, consulta Conexiones MCP, donde se explica cómo conectarte desde el servicio administrado o desde tu sandbox.

Secure MCP Tunnel

Si tu servidor MCP es privado, está alojado en tus instalaciones o se encuentra detrás de un firewall, usa Secure MCP Tunnel para conectarlo a los productos de OpenAI compatibles sin exponerlo a la internet pública. Descarga la versión pública más reciente de openai/tunnel-client.

Inicio rápido

Usa el tipo de herramienta mcp en la API Responses. Especifica server_url para un servidor MCP remoto o usa tunnel_id para conectarte a un servidor MCP local mediante Secure MCP Tunnel. Según el servidor, es posible que también necesites proporcionar un token de acceso OAuth en el parámetro authorization.

El siguiente ejemplo usa el servidor MCP de documentación de OpenAI, de acceso público, para buscar documentación sobre cómo recibir la salida de la API Responses a medida que se genera. Este servidor ofrece herramientas de documentación de solo lectura y no requiere autenticación. El ejemplo omite la aprobación de las llamadas a herramientas para esta consulta de documentación pública. Solicita aprobación cuando compartas datos sensibles.

Usar un servidor MCP remoto en la API Responses

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "never"
      }
    ],
    "input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "openai_docs",
      server_description: "Search and read the public OpenAI documentation.",
      server_url: "https://developers.openai.com/mcp",
      require_approval: "never",
    },
  ],
  input:
    "Search the OpenAI docs for Responses API streaming and return the relevant links.",
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "openai_docs",
            "server_description": "Search and read the public OpenAI documentation.",
            "server_url": "https://developers.openai.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Search the OpenAI docs for Responses API streaming and return the relevant links.",
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("openai_docs")
	tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
	tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Search the OpenAI docs for Responses API streaming and return the relevant links.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Search the OpenAI docs for Responses API streaming and return the relevant links.")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("openai_docs")
                .serverDescription("Search and read the public OpenAI documentation.")
                .serverUrl("https://developers.openai.com/mcp")
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "openai_docs",
        serverUri: new Uri("https://developers.openai.com/mcp"),
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19require "openai"

openai = OpenAI::Client.new

response = openai.responses.create(
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "openai_docs",
      server_description: "Search and read the public OpenAI documentation.",
      server_url: "https://developers.openai.com/mcp",
      require_approval: "never"
    }
  ],
  input: "Search the OpenAI docs for Responses API streaming and return the relevant links."
)

puts(response.output_text)

Usa la API Responses solo con servidores MCP remotos en los que confíes. Un servidor malicioso puede extraer datos sensibles de cualquier contenido que entre en el contexto del modelo. Antes de usar esta herramienta, revisa con atención la sección Riesgos y seguridad que aparece más adelante.

La API devuelve nuevos elementos en el arreglo output de la respuesta del modelo. Si el modelo decide usar un servidor MCP, primero solicita la lista de herramientas disponibles en el servidor. Esto genera un elemento de salida mcp_list_tools. El siguiente ejemplo de salida muestra solo la herramienta de búsqueda, con una descripción abreviada. El servidor también ofrece otras herramientas de documentación.

12345678910111213141516171819202122232425262728293031323334{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "openai_docs",
  "tools": [
    {
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      },
      "description": "Search the public OpenAI documentation.",
      "input_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "cursor": {
            "type": "string"
          }
        },
        "required": ["query"]
      },
      "name": "search_openai_docs"
    }
  ]
}

Si el modelo decide llamar a una de las herramientas disponibles en el servidor MCP, también encontrarás un elemento de salida mcp_call que muestra qué envió el modelo a la herramienta MCP y qué devolvió la herramienta.

12345678910{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "error": null,
  "name": "search_openai_docs",
  "output": "{\"hits\":[{\"url\":\"https://developers.openai.com/api/docs/guides/streaming-responses\"}]}",
  "server_label": "openai_docs"
}

Sigue leyendo para conocer cómo funciona la herramienta MCP, cómo filtrar las herramientas disponibles y cómo gestionar las solicitudes de aprobación de llamadas a herramientas.

Cómo funciona

La mayoría de los modelos recientes admiten la herramienta MCP en la API Responses. Comprueba si tu modelo es compatible con la herramienta MCP en el catálogo de modelos. Al usar la herramienta MCP, solo pagas por los tokens que se consumen al importar definiciones de herramientas o realizar llamadas a herramientas. No se aplican cargos adicionales por llamada.

A continuación se describen los pasos que sigue la API al llamar a una herramienta MCP.

Paso 1: obtener la lista de herramientas disponibles

Cuando especificas un servidor MCP remoto en el parámetro tools, la API intenta obtener la lista de herramientas del servidor. La API Responses es compatible con los servidores MCP remotos que admiten el protocolo de transporte Streamable HTTP o HTTP/SSE.

Si la API obtiene la lista de herramientas, aparece un nuevo elemento de salida mcp_list_tools en la respuesta del modelo. La propiedad tools de este objeto muestra las herramientas que se importaron correctamente. Este fragmento de ejemplo muestra solo la herramienta de búsqueda, con una descripción abreviada.

12345678910111213141516171819202122232425262728293031323334{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "openai_docs",
  "tools": [
    {
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      },
      "description": "Search the public OpenAI documentation.",
      "input_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "cursor": {
            "type": "string"
          }
        },
        "required": ["query"]
      },
      "name": "search_openai_docs"
    }
  ]
}

Mientras el elemento mcp_list_tools esté presente en el contexto de una solicitud a la API, la API no volverá a pedir la lista de herramientas al servidor MCP en cada turno de una conversación. Para reducir la latencia, te recomendamos mantener este elemento en el contexto del modelo en cada conversación o ejecución de un flujo de trabajo.

Filtrar herramientas

Algunos servidores MCP ofrecen decenas de herramientas. Poner muchas herramientas a disposición del modelo puede aumentar los costos y la latencia. Si solo te interesa un subconjunto de las herramientas que ofrece un servidor MCP, usa el parámetro allowed_tools para importar únicamente esas herramientas. Este ejemplo importa solo search_openai_docs para buscar enlaces a la documentación.

Limitar las herramientas permitidas

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "never",
        "allowed_tools": ["search_openai_docs"]
      }
    ],
    "input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "openai_docs",
      server_description: "Search and read the public OpenAI documentation.",
      server_url: "https://developers.openai.com/mcp",
      require_approval: "never",
      allowed_tools: ["search_openai_docs"],
    },
  ],
  input:
    "Search the OpenAI docs for Responses API streaming and return the relevant links.",
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "openai_docs",
            "server_description": "Search and read the public OpenAI documentation.",
            "server_url": "https://developers.openai.com/mcp",
            "require_approval": "never",
            "allowed_tools": ["search_openai_docs"],
        }
    ],
    input="Search the OpenAI docs for Responses API streaming and return the relevant links.",
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("openai_docs")
	tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
	tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}
	tool.OfMcp.AllowedTools = responses.ToolMcpAllowedToolsUnionParam{OfMcpAllowedTools: []string{"search_openai_docs"}}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Search the OpenAI docs for Responses API streaming and return the relevant links.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;
import java.util.List;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Search the OpenAI docs for Responses API streaming and return the relevant links.")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("openai_docs")
                .serverDescription("Search and read the public OpenAI documentation.")
                .serverUrl("https://developers.openai.com/mcp")
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
                .allowedToolsOfMcp(List.of("search_openai_docs"))
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "openai_docs",
        serverUri: new Uri("https://developers.openai.com/mcp"),
        allowedTools: new McpToolFilter() { ToolNames = { "search_openai_docs" } },
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "Search the OpenAI docs for Responses API streaming and return the relevant links.",
  tools: [
    {
      type: :mcp,
      server_label: "openai_docs",
      server_description: "Search and read the public OpenAI documentation.",
      server_url: "https://developers.openai.com/mcp",
      require_approval: :never,
      allowed_tools: ["search_openai_docs"]
    }
  ]
)

puts(response.output_text)

Paso 2: llamar a las herramientas

Una vez que el modelo tiene acceso a las definiciones de las herramientas, puede decidir a cuáles llamar según el contenido de su contexto. Cuando el modelo decide llamar a una herramienta MCP, la API envía una solicitud al servidor MCP remoto para que ejecute la herramienta e incorpora la salida al contexto del modelo. Esto crea un elemento mcp_call. Para abreviar, el siguiente ejemplo de salida omite los metadatos de los resultados de búsqueda.

12345678910{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "error": null,
  "name": "search_openai_docs",
  "output": "{\"hits\":[{\"url\":\"https://developers.openai.com/api/docs/guides/streaming-responses\"}]}",
  "server_label": "openai_docs"
}

Este elemento incluye tanto los argumentos que el modelo eligió para la llamada como el valor de output que devolvió el servidor MCP remoto. Todos los modelos pueden decidir realizar varias llamadas a herramientas MCP, por lo que una sola solicitud a la API puede generar varios de estos elementos.

Si falla una llamada a una herramienta, el campo de error de este elemento indica si hubo un error del protocolo MCP, un error de ejecución de la herramienta MCP o un error general de conectividad. Los errores de MCP se describen en esta sección de la especificación del protocolo.

Aprobaciones

De forma predeterminada, OpenAI te solicita aprobación antes de compartir datos con un conector o un servidor MCP remoto. Las aprobaciones te permiten ver y controlar qué datos se envían a un servidor MCP. Te recomendamos encarecidamente que revises con atención todos los datos que se comparten con un servidor MCP remoto. También puedes registrarlos. Para probar el flujo de aprobación, ejecuta el ejemplo de inicio rápido con require_approval establecido en "always" en lugar de "never". Cuando se solicita aprobación para llamar a una herramienta MCP, se crea un elemento mcp_approval_request en la salida del objeto Response. El siguiente ejemplo ilustra este caso.

1234567{
  "id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
  "type": "mcp_approval_request",
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "name": "search_openai_docs",
  "server_label": "openai_docs"
}

Revisa la herramienta solicitada y sus argumentos antes de aprobar la llamada. Luego puedes responder creando un nuevo objeto Response y agregándole un elemento mcp_approval_response. En los siguientes ejemplos, sustituye los ID de respuesta y de solicitud de aprobación por los que devuelva tu solicitud. El ejemplo de .NET obtiene estos ID de la respuesta inicial. Cada aprobación se aplica a una sola llamada a una herramienta. Gestiona de la misma manera las solicitudes de aprobación posteriores.

Aprobar el uso de herramientas en una solicitud a la API

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "always"
      }
    ],
    "previous_response_id": "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
    "input": [{
      "type": "mcp_approval_response",
      "approve": true,
      "approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa"
    }]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "openai_docs",
      server_description: "Search and read the public OpenAI documentation.",
      server_url: "https://developers.openai.com/mcp",
      require_approval: "always",
    },
  ],
  previous_response_id: "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
  input: [
    {
      type: "mcp_approval_response",
      approve: true,
      approval_request_id:
        "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
    },
  ],
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "openai_docs",
            "server_description": "Search and read the public OpenAI documentation.",
            "server_url": "https://developers.openai.com/mcp",
            "require_approval": "always",
        }
    ],
    previous_response_id="resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
    input=[
        {
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
        }
    ],
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("openai_docs")
	tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
	tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("always")}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:              "gpt-6-astra",
		PreviousResponseID: openai.String("resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa"),
		Tools:              []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
			responses.ResponseInputItemParamOfMcpApprovalResponse("mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa", true),
		}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.Tool;
import java.util.List;

String responseId = "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa";

String approvalRequestId = "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            ResponseCreateParams.Input.ofResponse(
                List.of(
                    ResponseInputItem.ofMcpApprovalResponse(
                        ResponseInputItem.McpApprovalResponse.builder()
                            .approvalRequestId(approvalRequestId)
                            .approve(true)
                            .build()))))
        .previousResponseId(responseId)
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("openai_docs")
                .serverDescription("Search and read the public OpenAI documentation.")
                .serverUrl("https://developers.openai.com/mcp")
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.ALWAYS)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    ParallelToolCallsEnabled = false
};
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "openai_docs",
        serverUri: new Uri("https://developers.openai.com/mcp"),
        allowedTools: new McpToolFilter { ToolNames = { "search_openai_docs" } },
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )
);

// Step 1: Create a response that requests tool-call approval.
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));
ResponseResult response1 = await client.CreateResponseAsync(options);

McpToolCallApprovalRequestItem approvalRequest =
    response1.OutputItems.OfType<McpToolCallApprovalRequestItem>().Single();

// Step 2: Approve the tool call and get the final response.
options.PreviousResponseId = response1.Id;
options.ToolChoice = ResponseToolChoice.CreateNoneChoice();
options.InputItems.Clear();
options.InputItems.Add(
    ResponseItem.CreateMcpApprovalResponseItem(approvalRequest.Id, approved: true)
);
ResponseResult response2 = await client.CreateResponseAsync(options);

Console.WriteLine(response2.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  previous_response_id: "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
  input: [
    {
      type: :mcp_approval_response,
      approval_request_id: "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
      approve: true
    }
  ],
  tools: [
    {
      type: :mcp,
      server_label: "openai_docs",
      server_url: "https://developers.openai.com/mcp",
      server_description: "Search and read the public OpenAI documentation.",
      require_approval: :always
    }
  ]
)

puts(response.output_text)

Aquí usamos el parámetro previous_response_id para vincular el nuevo objeto Response con el objeto Response anterior que generó la solicitud de aprobación. También puedes pasar las salidas de una respuesta como entradas de otra para tener el máximo control sobre lo que entra en el contexto del modelo.

Si confías lo suficiente en un servidor MCP remoto, puedes omitir las aprobaciones para reducir la latencia. Para hacerlo, asigna al parámetro require_approval de la herramienta MCP un objeto que incluya solo las herramientas para las que quieras omitir la aprobación, como se muestra a continuación. También puedes asignarle el valor 'never' para omitir las aprobaciones de todas las herramientas de ese servidor MCP remoto.

Omitir siempre la aprobación de determinadas herramientas

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "require_approval": {
          "never": {
            "tool_names": ["ask_question", "read_wiki_structure"]
          }
        }
      }
    ],
    "input": "What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: {
        never: {
          tool_names: ["ask_question", "read_wiki_structure"],
        },
      },
    },
  ],
  input:
    "What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?",
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "deepwiki",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "require_approval": {
                "never": {"tool_names": ["ask_question", "read_wiki_structure"]}
            },
        },
    ],
    input="What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?",
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("deepwiki")
	tool.OfMcp.ServerURL = openai.String("https://mcp.deepwiki.com/mcp")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{
		OfMcpToolApprovalFilter: &responses.ToolMcpRequireApprovalMcpToolApprovalFilterParam{
			Never: responses.ToolMcpRequireApprovalMcpToolApprovalFilterNeverParam{
				ToolNames: []string{"ask_question", "read_wiki_structure"},
			},
		},
	}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What transport protocols does the 2025-03-26 version of the MCP spec support?")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("deepwiki")
                .serverUrl("https://mcp.deepwiki.com/mcp")
                .requireApproval(
                    Tool.Mcp.RequireApproval.McpToolApprovalFilter.builder()
                        .never(
                            Tool.Mcp.RequireApproval.McpToolApprovalFilter.Never.builder()
                                .addToolName("ask_question")
                                .addToolName("read_wiki_structure")
                                .build())
                        .build())
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "deepwiki",
        serverUri: new Uri("https://mcp.deepwiki.com/mcp"),
        toolCallApprovalPolicy: new CustomMcpToolCallApprovalPolicy
        {
            ToolsNeverRequiringApproval = new McpToolFilter
            {
                ToolNames = { "ask_question", "read_wiki_structure" },
            },
        }
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem(
        "What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?"
    )
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "What transport protocols does the 2025-03-26 version of the MCP spec support?",
  tools: [
    {
      type: :mcp,
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: {
        never: { tool_names: ["ask_question", "read_wiki_structure"] }
      }
    }
  ]
)

puts(response.output_text)

Autenticación

El servidor MCP de documentación de OpenAI no requiere autenticación. Otros servidores MCP pueden requerirla. El mecanismo más común es un token de acceso OAuth. Proporciona este token en el campo authorization de la herramienta MCP.

Usar la herramienta MCP de Stripe

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6-astra",
    "input": "Create a payment link for $20",
    "tools": [
      {
        "type": "mcp",
        "server_label": "stripe",
        "server_url": "https://mcp.stripe.com",
        "authorization": "$STRIPE_OAUTH_ACCESS_TOKEN"
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  input: "Create a payment link for $20",
  tools: [
    {
      type: "mcp",
      server_label: "stripe",
      server_url: "https://mcp.stripe.com",
      authorization: "$STRIPE_OAUTH_ACCESS_TOKEN",
    },
  ],
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import os
from openai import OpenAI

client = OpenAI()
authorization = os.environ["STRIPE_OAUTH_ACCESS_TOKEN"]

resp = client.responses.create(
    model="gpt-6-astra",
    input="Create a payment link for $20",
    tools=[
        {
            "type": "mcp",
            "server_label": "stripe",
            "server_url": "https://mcp.stripe.com",
            "authorization": authorization,
        }
    ],
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	authorization := os.Getenv("STRIPE_OAUTH_ACCESS_TOKEN")
	if authorization == "" {
		panic("STRIPE_OAUTH_ACCESS_TOKEN is required")
	}
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("stripe")
	tool.OfMcp.ServerURL = openai.String("https://mcp.stripe.com")
	tool.OfMcp.Authorization = openai.String(authorization)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Create a payment link for $20")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;

String stripeAccessToken = System.getenv("STRIPE_OAUTH_ACCESS_TOKEN");

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Create a payment link for $20.")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("stripe")
                .serverUrl("https://mcp.stripe.com")
                .authorization(stripeAccessToken)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23using OpenAI.Responses;
#pragma warning disable OPENAI001

string authToken =
    Environment.GetEnvironmentVariable("STRIPE_OAUTH_ACCESS_TOKEN")!;
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "stripe",
        serverUri: new Uri("https://mcp.stripe.com"),
        authorizationToken: authToken
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Create a payment link for $20")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Create a payment link for $20.",
  tools: [
    {
      type: :mcp,
      server_label: "stripe",
      server_url: "https://mcp.stripe.com",
      authorization: ENV.fetch("STRIPE_OAUTH_ACCESS_TOKEN")
    }
  ]
)

puts(response.output_text)

Para evitar la filtración de tokens sensibles, la API Responses no almacena el valor que proporcionas en el campo authorization. Este valor tampoco aparece en el objeto Response que se crea. Por eso, debes enviar el valor de authorization cada vez que solicites a la API Responses que cree una respuesta.

Conectores heredados

connector_id está en desuso para los modelos lanzados después del 1 de septiembre de 2026. Usa server_url para conectarte a un servidor MCP remoto o tunnel_id para conectarte a un servidor MCP local mediante Secure MCP Tunnel. Los modelos existentes siguen siendo compatibles con los conectores. Los ejemplos de esta sección usan gpt-5.2, que se lanzó antes de esa fecha.

La API Responses ofrece compatibilidad integrada con un conjunto limitado de conectores para servicios de terceros. Estos conectores permiten incorporar contexto de aplicaciones populares, como Dropbox y Gmail, para que el modelo interactúe con esos servicios.

Puedes usar los conectores de la misma manera que los servidores MCP remotos. Ambos permiten que un modelo de OpenAI acceda a herramientas adicionales de terceros en una solicitud a la API. La diferencia es que, en lugar de pasar un server_url como harías para llamar a un servidor MCP remoto, pasas un connector_id que identifica de manera única un conector disponible en la API.

Los conectores requieren un token de acceso OAuth que tu aplicación debe proporcionar en el parámetro authorization.

Usar un conector heredado con GPT-5.2

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-5.2",
    "tools": [
      {
        "type": "mcp",
        "server_label": "Dropbox",
        "connector_id": "connector_dropbox",
        "authorization": "<oauth access token>",
        "require_approval": "never"
      }
    ],
    "input": "Summarize the Q2 earnings report."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-5.2",
  tools: [
    {
      type: "mcp",
      server_label: "Dropbox",
      connector_id: "connector_dropbox",
      authorization: "<oauth access token>",
      require_approval: "never",
    },
  ],
  input: "Summarize the Q2 earnings report.",
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import os

from openai import OpenAI

client = OpenAI()
connector_authorization = os.environ["OPENAI_CONNECTOR_AUTHORIZATION"]

resp = client.responses.create(
    model="gpt-5.2",
    tools=[
        {
            "type": "mcp",
            "server_label": "Dropbox",
            "connector_id": "connector_dropbox",
            "authorization": connector_authorization,
            "require_approval": "never",
        },
    ],
    input="Summarize the Q2 earnings report.",
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("Dropbox")
	tool.OfMcp.ConnectorID = "connector_dropbox"
	tool.OfMcp.Authorization = openai.String("<oauth access token>")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.2",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Summarize the Q2 earnings report.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;

String oauthAccessToken = "<oauth access token>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("Summarize the Q2 earnings report.")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("Dropbox")
                .connectorId(Tool.Mcp.ConnectorId.of("connector_dropbox"))
                .authorization(oauthAccessToken)
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24using OpenAI.Responses;
#pragma warning disable OPENAI001

string dropboxToken =
    Environment.GetEnvironmentVariable("DROPBOX_OAUTH_ACCESS_TOKEN")!;
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-5.2" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "Dropbox",
        connectorId: McpToolConnectorId.Dropbox,
        authorizationToken: dropboxToken,
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Summarize the Q2 earnings report.")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  input: "Summarize the Q2 earnings report.",
  tools: [
    {
      type: :mcp,
      server_label: "Dropbox",
      connector_id: "connector_dropbox",
      authorization: "<oauth access token>",
      require_approval: :never
    }
  ]
)

puts(response.output_text)

Conectores disponibles

Dropbox: connector_dropbox
Gmail: connector_gmail
Google Calendar: connector_googlecalendar
Google Drive: connector_googledrive
Microsoft Teams: connector_microsoftteams
Calendario de Outlook: connector_outlookcalendar
Correo de Outlook: connector_outlookemail
SharePoint: connector_sharepoint

Dimos prioridad a los servicios que no tienen servidores MCP remotos oficiales. GitHub, por ejemplo, tiene un servidor MCP oficial al que puedes conectarte pasando https://api.githubcopilot.com/mcp/ al campo server_url de la herramienta MCP.

Autorizar un conector

En el campo authorization, pasa un token de acceso OAuth. Tu aplicación debe gestionar por separado el registro del cliente OAuth y la autorización.

Para hacer pruebas, puedes usar el OAuth 2.0 Playground de Google para generar tokens de acceso temporales que puedes usar en una solicitud a la API.

Para probar los conectores de la API en el Playground, ingresa lo siguiente.

https://www.googleapis.com/auth/calendar.events

Ingresa este alcance en Step 1: Select and authorize APIs para que la API pueda leer los eventos de Google Calendar.

Después de autorizar la aplicación con tu cuenta de Google, pasarás a Step 2: Exchange authorization code for tokens. En ese paso, intercambia el código por un token de acceso que puedes usar en una solicitud a la API con el conector de Google Calendar.

Usar el conector de Google Calendar

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "tools": [
      {
        "type": "mcp",
        "server_label": "google_calendar",
        "connector_id": "connector_googlecalendar",
        "authorization": "ya29.A0AS3H6...",
        "require_approval": "never"
      }
    ],
    "input": "What is on my Google Calendar for today?"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-5.2",
  tools: [
    {
      type: "mcp",
      server_label: "google_calendar",
      connector_id: "connector_googlecalendar",
      authorization: "ya29.A0AS3H6...",
      require_approval: "never",
    },
  ],
  input: "What's on my Google Calendar for today?",
});

console.log(resp.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import os
from openai import OpenAI

client = OpenAI()
authorization = os.environ["GOOGLE_CALENDAR_OAUTH_ACCESS_TOKEN"]

resp = client.responses.create(
    model="gpt-5.2",
    tools=[
        {
            "type": "mcp",
            "server_label": "google_calendar",
            "connector_id": "connector_googlecalendar",
            "authorization": authorization,
            "require_approval": "never",
        },
    ],
    input="What's on my Google Calendar for today?",
)

print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfMcp("google_calendar")
	tool.OfMcp.ConnectorID = "connector_googlecalendar"
	tool.OfMcp.Authorization = openai.String("<oauth access token>")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.2",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What's on my Google Calendar for today?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;

String oauthAccessToken = "<oauth access token>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("What's on my Google Calendar for today?")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("google_calendar")
                .connectorId(Tool.Mcp.ConnectorId.of("connector_googlecalendar"))
                .authorization(oauthAccessToken)
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24using OpenAI.Responses;
#pragma warning disable OPENAI001

string authToken =
    Environment.GetEnvironmentVariable("GOOGLE_CALENDAR_OAUTH_ACCESS_TOKEN")!;
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-5.2" };
options.Tools.Add(
    ResponseTool.CreateMcpTool(
        serverLabel: "google_calendar",
        connectorId: McpToolConnectorId.GoogleCalendar,
        authorizationToken: authToken,
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What's on my Google Calendar for today?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  input: "What's on my Google Calendar for today?",
  tools: [
    {
      type: :mcp,
      server_label: "google_calendar",
      connector_id: "connector_googlecalendar",
      authorization: "<oauth access token>",
      require_approval: :never
    }
  ]
)

puts(response.output_text)

Una llamada a una herramienta MCP de un conector tiene el mismo formato que una llamada a una herramienta MCP de un servidor remoto. Ambas usan el tipo de elemento de salida mcp_call. En este caso, tanto los argumentos que recibe el conector como la respuesta que devuelve son cadenas JSON.

12345678910{
  "id": "mcp_68a62ae1c93c81a2b98c29340aa3ed8800e9b63986850588",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"time_min\":\"2025-08-20T00:00:00\",\"time_max\":\"2025-08-21T00:00:00\",\"timezone_str\":null,\"max_results\":50,\"query\":null,\"calendar_id\":null,\"next_page_token\":null}",
  "error": null,
  "name": "search_events",
  "output": "{\"events\": [{\"id\": \"2n8ni54ani58pc3ii6soelupcs_20250820\", \"summary\": \"Home\", \"location\": null, \"start\": \"2025-08-20T00:00:00\", \"end\": \"2025-08-21T00:00:00\", \"url\": \"https://www.google.com/calendar/event?eid=Mm44bmk1NGFuaTU4cGMzaWk2c29lbHVwY3NfMjAyNTA4MjAga3doaW5uZXJ5QG9wZW5haS5jb20&ctz=America/Los_Angeles\", \"description\": \"\\n\\n\", \"transparency\": \"transparent\", \"display_url\": \"https://www.google.com/calendar/event?eid=Mm44bmk1NGFuaTU4cGMzaWk2c29lbHVwY3NfMjAyNTA4MjAga3doaW5uZXJ5QG9wZW5haS5jb20&ctz=America/Los_Angeles\", \"display_title\": \"Home\"}], \"next_page_token\": null}",
  "server_label": "Google_Calendar"
}

Herramientas disponibles en cada conector

Las herramientas disponibles dependen de los alcances de tu token OAuth. Expande las tablas para ver qué herramientas puedes usar al conectarte a cada aplicación.

Herramienta	Descripción	Alcances
`search`	Busca en Dropbox archivos que coincidan con una consulta	files.metadata.read, account_info.read
`fetch`	Obtiene un archivo por su ruta, con la opción de descargarlo sin procesar	files.content.read
`search_files`	Busca archivos en Dropbox y devuelve los resultados	files.metadata.read, account_info.read
`fetch_file`	Obtiene el texto de un archivo o su contenido sin procesar	files.content.read, account_info.read
`list_recent_files`	Devuelve los archivos modificados más recientemente a los que el usuario tiene acceso	files.metadata.read, account_info.read
`get_profile`	Obtiene el perfil de Dropbox del usuario actual	account_info.read

Herramienta	Descripción	Alcances
`get_profile`	Devuelve el perfil del usuario actual de Gmail	userinfo.email, userinfo.profile
`search_emails`	Busca en Gmail correos que coincidan con una consulta o etiqueta	gmail.modify
`search_email_ids`	Obtiene los ID de los mensajes de Gmail que coinciden con una búsqueda	gmail.modify
`get_recent_emails`	Devuelve los mensajes recibidos más recientemente en Gmail	gmail.modify
`read_email`	Obtiene un mensaje de Gmail, incluido el cuerpo	gmail.modify
`batch_read_email`	Lee varios mensajes de Gmail en una sola llamada	gmail.modify

Herramienta	Descripción	Alcances
`get_profile`	Devuelve el perfil del usuario actual de Google Calendar	userinfo.email, userinfo.profile
`search`	Busca eventos de Google Calendar con la opción de especificar un intervalo de tiempo	calendar.events
`fetch`	Obtiene los detalles de un evento de Google Calendar	calendar.events
`search_events`	Busca eventos de Google Calendar mediante filtros	calendar.events
`read_event`	Lee un evento de Google Calendar por su ID	calendar.events

Herramienta	Descripción	Alcances
`get_profile`	Devuelve el perfil del usuario actual de Drive	userinfo.email, userinfo.profile
`list_drives`	Enumera las unidades compartidas a las que el usuario tiene acceso	drive.readonly
`search`	Busca archivos en Drive mediante una consulta	drive.readonly
`recent_documents`	Devuelve los documentos modificados más recientemente	drive.readonly
`fetch`	Descarga el contenido de un archivo de Drive	drive.readonly

Herramienta	Descripción	Alcances
`search`	Busca en los chats y mensajes de canales de Microsoft Teams	Chat.Read, ChannelMessage.Read.All
`fetch`	Obtiene un mensaje de Teams por su ruta	Chat.Read, ChannelMessage.Read.All
`get_chat_members`	Enumera los miembros de un chat de Teams	Chat.Read
`get_profile`	Devuelve el perfil del usuario autenticado en Teams	User.Read

Herramienta	Descripción	Alcances
`search_events`	Busca eventos del calendario de Outlook con filtros de fecha	Calendars.Read
`fetch_event`	Obtiene los detalles de un evento	Calendars.Read
`fetch_events_batch`	Obtiene varios eventos en una sola llamada	Calendars.Read
`list_events`	Enumera los eventos del calendario dentro de un intervalo de fechas	Calendars.Read
`get_profile`	Obtiene el perfil del usuario actual	User.Read

Herramienta	Descripción	Alcances
`get_profile`	Devuelve información del perfil de la cuenta de Outlook	User.Read
`list_messages`	Obtiene los correos de una carpeta de Outlook	Mail.Read
`search_messages`	Busca correos en Outlook con filtros opcionales	Mail.Read
`get_recent_emails`	Devuelve los correos recibidos más recientemente	Mail.Read
`fetch_message`	Obtiene un correo por su ID	Mail.Read
`fetch_messages_batch`	Obtiene varios correos en una sola solicitud	Mail.Read

Herramienta	Descripción	Alcances
`get_site`	Identifica un sitio de SharePoint a partir del nombre de host y la ruta	Sites.Read.All
`search`	Busca documentos de SharePoint o OneDrive por palabra clave	Sites.Read.All, Files.Read.All
`list_recent_documents`	Devuelve los documentos consultados recientemente	Files.Read.All
`fetch`	Obtiene el contenido de un archivo a partir de una URL de descarga de Graph	Files.Read.All
`get_profile`	Obtiene el perfil del usuario actual	User.Read

Diferir la carga de herramientas de un servidor MCP

Si usas la búsqueda de herramientas, puedes diferir la carga de las funciones que ofrece un servidor MCP hasta que el modelo determine que las necesita. Para hacerlo, establece defer_loading: true en la definición de la herramienta del servidor MCP.

Cuando difieres la carga de un servidor MCP, el modelo aún puede usar la etiqueta y la descripción del servidor para decidir cuándo buscar herramientas en él. Las definiciones de las funciones individuales solo se cargan cuando se necesitan. Esto puede reducir el consumo total de tokens y resulta especialmente útil con servidores MCP que ofrecen muchas funciones.

1
2
3
4
5
6
7
8{
    "type": "mcp",
    "server_label": "openai_docs",
    "server_description": "Search and read the public OpenAI documentation.",
    "server_url": "https://developers.openai.com/mcp",
    "defer_loading": true,
    "require_approval": "never"
}

Riesgos y seguridad

La herramienta MCP te permite conectar modelos de OpenAI a servicios externos. Esta capacidad conlleva algunos riesgos.

Al usar conectores, corres el riesgo de enviar datos sensibles a OpenAI o de dar a los modelos acceso de lectura a datos de esos servicios que podrían ser sensibles.

Los servidores MCP remotos presentan los mismos riesgos. Además, OpenAI no los ha verificado. Estos servidores pueden permitir que los modelos accedan a datos, los envíen y reciban, y realicen acciones en esos servicios. Todos los servidores MCP son servicios de terceros sujetos a sus propios términos y condiciones.

Si encuentras un servidor MCP malicioso, repórtalo a security@openai.com.

Ten en cuenta las siguientes prácticas al integrar conectores y servidores MCP remotos.

Inyección de prompts

La inyección de prompts es un riesgo de seguridad importante en cualquier aplicación que use LLM, especialmente cuando das al modelo acceso a servidores MCP y conectores que pueden acceder a datos sensibles o realizar acciones. Si el prompt del modelo incluye contenido proporcionado por el usuario, usa estas herramientas con precaución y aplica medidas de protección adecuadas.

Por ejemplo, una página web podría indicarle al modelo que busque a un cliente en tu CRM e incluya la dirección de correo electrónico del cliente en una URL. Enviar una solicitud a esa URL revelaría la dirección de correo, incluso si la herramienta del CRM solo permite operaciones de lectura.

Para comparar un anuncio público de una empresa con registros privados del CRM, reúne la información pública en una solicitud en la que solo esté habilitada la búsqueda web. Pasa los datos pertinentes a una segunda solicitud que solo tenga acceso a la herramienta de búsqueda de tu CRM interno. Así evitas que los registros de clientes se incluyan en las consultas web o en las URL.

Exigir siempre aprobación para las acciones sensibles

Configura los parámetros require_approval y allowed_tools para que toda acción sensible pase por un flujo de aprobación.

URL en las llamadas a herramientas MCP y sus salidas

Puede ser peligroso enviar solicitudes a las URL o insertar imágenes mediante las URL que devuelven las llamadas a herramientas de conectores o servidores MCP remotos. Antes de insertar esas URL o usarlas de otro modo en el código de tu aplicación, asegúrate de que los dominios y servicios que las proporcionan sean de confianza.

Conectarse a servidores de confianza

Elige servidores oficiales alojados por los propios proveedores de servicios. Por ejemplo, te recomendamos conectarte al servidor que Stripe aloja en mcp.stripe.com en lugar de usar un servidor MCP de Stripe alojado por un tercero. Como todavía hay pocos servidores MCP remotos oficiales, quizá consideres usar un servidor MCP alojado por una organización que no opera el servidor del servicio y que reenvía las solicitudes a ese servicio a través de tu API. Si necesitas hacerlo, evalúa con especial cuidado a estos “agregadores” y revisa cómo usan tus datos.

Registrar y revisar los datos que se comparten con servidores MCP de terceros

Los servidores MCP definen sus propias herramientas, por lo que pueden solicitar datos que preferirías no compartir con quien aloja el servidor. Por eso, de forma predeterminada, la herramienta MCP de la API Responses exige aprobación para cada llamada a una herramienta MCP. Al desarrollar tu aplicación, revisa detenidamente qué tipos de datos se comparten con estos servidores MCP. Cuando tengas suficiente confianza en un servidor MCP, puedes omitir estas aprobaciones para reducir la latencia de ejecución.

También recomendamos registrar todos los datos que se envían a servidores MCP. Si usas la API Responses con store=true, la API ya conserva un registro de estos datos durante 30 días, salvo que tu organización tenga habilitada la retención cero de datos. También puedes registrar estos datos en tus propios sistemas y revisarlos periódicamente para comprobar que se comparten según lo previsto.

Los servidores MCP maliciosos pueden incluir instrucciones ocultas (inyecciones de prompts) diseñadas para que los modelos de OpenAI se comporten de manera inesperada. Aunque OpenAI ha incorporado medidas de protección para ayudar a detectar y bloquear estas amenazas, es fundamental que revises con atención las entradas y salidas y que solo establezcas conexiones con servidores de confianza.

Los servidores MCP pueden cambiar de forma inesperada el funcionamiento de sus herramientas, lo que podría dar lugar a comportamientos no deseados o maliciosos.

Implicaciones para la retención cero de datos y la residencia de datos

La herramienta MCP es compatible con la retención cero de datos y la residencia de datos. Ten en cuenta que los servidores MCP son servicios de terceros y que los datos que envíes a un servidor MCP estarán sujetos a las políticas de retención y residencia de datos de ese servicio.

Por ejemplo, si tu organización tiene residencia de datos en Europa, OpenAI limita a Europa la inferencia y el almacenamiento del contenido del cliente hasta el momento en que se envían comunicaciones o datos al servidor MCP. Es tu responsabilidad asegurarte de que el servidor MCP también cumpla con tus requisitos de retención cero de datos o de residencia de datos. Consulta más información sobre la retención cero de datos y la residencia de datos en la guía sobre tus datos.

Notas de uso

Disponibilidad por API	Límites de solicitudes	Notas
Responses Chat Completions Assistants	Build 1000 RPM Launch y Grow 2000 RPM	Precios Retención cero de datos y residencia de datos

Disponibilidad por API

Límites de solicitudes

Notas

Responses

Chat Completions

Assistants

Build
1000 RPM

Launch y Grow
2000 RPM

Precios
Retención cero de datos y residencia de datos

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las funciones de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Ampliar funciones y automatizar

Entornos

Codex Cloud

Desarrollar con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Ciberseguridad

Primeros pasos

Configuración de funciones

Identidad y acceso