Servidores MCP | OpenAI API

Além das ferramentas que você disponibiliza ao modelo por meio da chamada de função, você pode ampliar os recursos do modelo usando servidores MCP remotos ou o túnel MCP seguro. Com essas ferramentas, o modelo pode se conectar a serviços externos e controlá-los quando isso for necessário para responder ao prompt de um usuário. Você, como desenvolvedor, pode permitir essas chamadas automaticamente ou exigir sua aprovação explícita.

Servidores MCP remotos podem ser quaisquer servidores na internet pública que implementem um servidor remoto do Model Context Protocol (MCP).
O túnel MCP seguro conecta um servidor MCP local ou privado sem expô-lo à internet pública.

Este guia mostra como usar ferramentas MCP com a API Responses. Os modelos existentes continuam compatíveis com os conectores integrados. Consulte a política de descontinuação e os exemplos de compatibilidade em Conectores legados. Para sessões da API Agents, consulte Conexões MCP, que explica como se conectar a partir do serviço gerenciado ou do seu sandbox.

Túnel MCP seguro

Se o servidor MCP for privado, estiver hospedado na sua infraestrutura ou estiver protegido por um firewall, use o túnel MCP seguro para conectá-lo a produtos compatíveis da OpenAI sem expor o servidor à internet pública. Baixe a versão pública mais recente em openai/tunnel-client.

Início rápido

Use o tipo de ferramenta mcp na API Responses. Defina server_url para um servidor MCP remoto ou use tunnel_id para um servidor MCP local conectado pelo túnel MCP seguro. Dependendo do servidor, talvez você também precise fornecer um token de acesso OAuth no parâmetro authorization.

O exemplo a seguir usa o servidor MCP público da documentação da OpenAI para encontrar documentação sobre como receber a saída da API Responses por streaming. Esse servidor oferece ferramentas de consulta à documentação com acesso de somente leitura e dispensa autenticação. O exemplo dispensa a aprovação das chamadas de ferramenta para essa consulta à documentação pública. Exija aprovação ao compartilhar dados confidenciais.

Uso de um servidor MCP remoto na 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)

Use a API Responses apenas com servidores MCP remotos em que você confia. Um servidor malicioso pode extrair dados confidenciais de qualquer conteúdo que entre no contexto do modelo. Antes de usar essa ferramenta, leia com atenção a seção Riscos e segurança abaixo.

A API retorna novos itens no array output da resposta do modelo. Se o modelo decidir usar um servidor MCP, primeiro fará uma requisição para listar as ferramentas disponíveis no servidor. Isso cria um item de saída mcp_list_tools. O exemplo de saída a seguir mostra apenas a ferramenta de pesquisa, com a descrição abreviada. O servidor também disponibiliza outras ferramentas de consulta à documentação.

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"
    }
  ]
}

Se o modelo decidir chamar uma das ferramentas disponíveis no servidor MCP, a saída também incluirá um item mcp_call. Ele mostra o que o modelo enviou à ferramenta MCP e o que ela retornou.

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"
}

As próximas seções explicam como a ferramenta MCP funciona, como filtrar as ferramentas disponíveis e como responder a pedidos de aprovação de chamadas de ferramenta.

Como funciona

A ferramenta MCP está disponível na API Responses para a maioria dos modelos recentes. Consulte a lista de modelos para verificar se o seu modelo é compatível com a ferramenta MCP. Ao usar a ferramenta MCP, você paga apenas pelos tokens usados na importação das definições de ferramentas ou nas chamadas de ferramenta. Não há cobrança adicional por chamada.

Veja as etapas que a API segue ao chamar uma ferramenta MCP.

Etapa 1 — Listar as ferramentas disponíveis

Quando você especifica um servidor MCP remoto no parâmetro tools, a API tenta obter a lista de ferramentas do servidor. A API Responses funciona com servidores MCP remotos compatíveis com o protocolo de transporte Streamable HTTP ou HTTP/SSE.

Se a API conseguir obter a lista de ferramentas, a saída da resposta do modelo incluirá um novo item mcp_list_tools. A propriedade tools desse objeto mostra quais ferramentas a API conseguiu importar. O trecho a seguir mostra apenas a ferramenta de pesquisa, com a descrição 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"
    }
  ]
}

Enquanto o item mcp_list_tools estiver no contexto da requisição à API, a API não voltará a buscar a lista de ferramentas no servidor MCP a cada interação de uma conversa. Para reduzir a latência, recomendamos manter esse item no contexto do modelo em todas as conversas e em cada execução de um fluxo de trabalho.

Filtrar ferramentas

Alguns servidores MCP oferecem dezenas de ferramentas. Disponibilizar muitas ferramentas ao modelo pode aumentar o custo e a latência. Se você precisar apenas de algumas ferramentas do servidor MCP, use o parâmetro allowed_tools para importar somente as que interessam. Este exemplo importa apenas search_openai_docs para encontrar links da documentação.

Restringir as ferramentas 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)

Etapa 2 — Chamar ferramentas

Depois de ter acesso às definições das ferramentas, o modelo pode decidir chamá-las conforme o conteúdo do seu contexto. Quando o modelo decide chamar uma ferramenta MCP, a API envia uma requisição ao servidor MCP remoto para executar a ferramenta e inclui a saída no contexto do modelo. Isso cria um item mcp_call. Para simplificar, o exemplo de saída a seguir omite os metadados dos resultados da pesquisa.

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"
}

Esse item inclui os argumentos que o modelo escolheu para a chamada de ferramenta e a saída (output) retornada pelo servidor MCP remoto. Todos os modelos podem optar por fazer várias chamadas de ferramenta MCP, portanto uma única requisição à API pode gerar vários desses itens.

Se uma chamada de ferramenta falhar, o campo de erro desse item indicará um erro de protocolo MCP, de execução da ferramenta MCP ou de conectividade em geral. Consulte a documentação dos erros MCP na especificação do protocolo.

Aprovações

Por padrão, a OpenAI pede sua aprovação antes de compartilhar qualquer dado com um conector ou servidor MCP remoto. Com as aprovações, você pode verificar e controlar quais dados são enviados a um servidor MCP. Recomendamos enfaticamente que você examine com atenção todos os dados compartilhados com um servidor MCP remoto e, se desejar, registre esses dados. Para testar o fluxo de aprovação, execute o exemplo de início rápido com require_approval definido como "always" em vez de "never". Um pedido de aprovação para chamar uma ferramenta MCP cria um item mcp_approval_request na saída do objeto Response, como no exemplo a seguir.

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

Antes de aprovar, confira a ferramenta solicitada e seus argumentos. Para responder, crie um objeto Response e adicione a ele um item mcp_approval_response. Nos exemplos a seguir, substitua os IDs de exemplo da resposta e do pedido de aprovação pelos IDs retornados pela sua requisição. O exemplo em .NET obtém esses IDs da resposta inicial. Cada aprovação vale para uma única chamada de ferramenta. Responda da mesma forma aos pedidos de aprovação seguintes.

Aprovar o uso de ferramentas em uma requisição à 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)

Neste exemplo, o parâmetro previous_response_id vincula o novo objeto Response ao objeto Response anterior, que gerou o pedido de aprovação. Para ter o máximo de controle sobre o que entra no contexto do modelo, você também pode usar as saídas de uma resposta como entradas da próxima.

Quando considerar que um servidor MCP remoto é confiável, você pode dispensar as aprovações para reduzir a latência. Para isso, defina o parâmetro require_approval da ferramenta MCP como um objeto que liste apenas as ferramentas para as quais você quer dispensar a aprovação, como no exemplo abaixo. Para dispensar a aprovação de todas as ferramentas desse servidor MCP remoto, use o valor 'never'.

Dispensar a aprovação para ferramentas específicas

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)

Autenticação

O servidor MCP da documentação da OpenAI não exige autenticação. Outros servidores MCP podem exigi-la. A forma mais comum de autenticação é com um token de acesso OAuth. Forneça esse token no campo authorization da ferramenta MCP.

Usar a ferramenta MCP da 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 o vazamento de tokens confidenciais, a API Responses não armazena o valor que você fornece no campo authorization. Esse valor também não aparece no objeto Response criado. Por isso, você deve enviar o valor de authorization em cada requisição à API Responses que crie uma resposta.

Conectores legados

O parâmetro connector_id está obsoleto para modelos lançados após 1º de setembro de 2026. Use server_url para se conectar a um servidor MCP remoto ou tunnel_id para se conectar a um servidor MCP local por meio do túnel MCP seguro. Os modelos existentes continuam compatíveis com os conectores. Os exemplos desta seção usam o gpt-5.2, lançado antes dessa data.

A API Responses oferece suporte integrado a um conjunto limitado de conectores para serviços de terceiros. Com esses conectores, você pode incorporar ao contexto dados de aplicativos populares, como Dropbox e Gmail, para que o modelo interaja com esses serviços.

Você pode usar conectores da mesma forma que servidores MCP remotos. Ambos permitem que um modelo da OpenAI acesse ferramentas adicionais de terceiros em uma requisição à API. Para chamar um servidor MCP remoto, você fornece um server_url. Para usar um conector, forneça um connector_id, que identifica de forma exclusiva um conector disponível na API.

Os conectores exigem que seu aplicativo forneça um token de acesso OAuth no parâmetro authorization.

Usar um conector legado com o 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 disponíveis

Dropbox: connector_dropbox
Gmail: connector_gmail
Google Agenda: connector_googlecalendar
Google Drive: connector_googledrive
Microsoft Teams: connector_microsoftteams
Calendário do Outlook: connector_outlookcalendar
Email do Outlook: connector_outlookemail
SharePoint: connector_sharepoint

Priorizamos serviços que não têm servidores MCP remotos oficiais. O GitHub, por exemplo, tem um servidor MCP oficial. Para se conectar a ele, informe https://api.githubcopilot.com/mcp/ no campo server_url da ferramenta MCP.

Autorizar um conector

No campo authorization, forneça um token de acesso OAuth. Seu aplicativo deve cuidar separadamente do registro do cliente OAuth e da autorização.

Para fazer testes, você pode usar o OAuth 2.0 Playground do Google para gerar tokens de acesso temporários e usá-los em uma requisição à API.

Para testar os conectores da API no Playground, comece pelo seguinte escopo de autorização:

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

Insira esse escopo em Step 1: Select and authorize APIs para permitir que a API leia eventos do Google Agenda.

Depois de autorizar o aplicativo com sua Conta do Google, você chegará à etapa Step 2: Exchange authorization code for tokens. Troque o código por um token de acesso para usar em uma requisição à API com o conector do Google Agenda.

Usar o conector do Google Agenda

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)

Uma chamada de ferramenta MCP feita por um conector tem o mesmo formato de uma chamada feita por um servidor MCP remoto. Ambas usam o tipo de item de saída mcp_call. Neste caso, tanto os argumentos enviados ao conector quanto a resposta dele são strings 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"
}

Ferramentas disponíveis em cada conector

As ferramentas disponíveis dependem dos escopos concedidos ao seu token OAuth. Expanda as tabelas abaixo para ver quais ferramentas você pode usar ao se conectar a cada aplicativo.

Ferramenta	Descrição	Escopos
`search`	Pesquisa no Dropbox arquivos que correspondem a uma consulta	files.metadata.read, account_info.read
`fetch`	Busca um arquivo pelo caminho, com opção de baixar o conteúdo bruto	files.content.read
`search_files`	Pesquisa arquivos no Dropbox e retorna os resultados	files.metadata.read, account_info.read
`fetch_file`	Obtém o texto ou o conteúdo bruto de um arquivo	files.content.read, account_info.read
`list_recent_files`	Retorna os arquivos modificados mais recentemente aos quais o usuário tem acesso	files.metadata.read, account_info.read
`get_profile`	Obtém o perfil do usuário atual do Dropbox	account_info.read

Ferramenta	Descrição	Escopos
`get_profile`	Retorna o perfil do usuário atual do Gmail	userinfo.email, userinfo.profile
`search_emails`	Pesquisa no Gmail emails que correspondem a uma consulta ou a um marcador	gmail.modify
`search_email_ids`	Obtém os IDs das mensagens do Gmail que correspondem a uma pesquisa	gmail.modify
`get_recent_emails`	Retorna as mensagens recebidas mais recentemente no Gmail	gmail.modify
`read_email`	Busca uma mensagem do Gmail, incluindo o corpo da mensagem	gmail.modify
`batch_read_email`	Lê várias mensagens do Gmail em uma única chamada	gmail.modify

Ferramenta	Descrição	Escopos
`get_profile`	Retorna o perfil do usuário atual do Google Agenda	userinfo.email, userinfo.profile
`search`	Pesquisa eventos do Google Agenda, com opção de limitar o período	calendar.events
`fetch`	Obtém os detalhes de um evento do Google Agenda	calendar.events
`search_events`	Busca eventos do Google Agenda usando filtros	calendar.events
`read_event`	Lê um evento do Google Agenda pelo ID	calendar.events

Ferramenta	Descrição	Escopos
`get_profile`	Retorna o perfil do usuário atual do Drive	userinfo.email, userinfo.profile
`list_drives`	Lista os drives compartilhados aos quais o usuário tem acesso	drive.readonly
`search`	Pesquisa arquivos no Drive usando uma consulta	drive.readonly
`recent_documents`	Retorna os documentos modificados mais recentemente	drive.readonly
`fetch`	Baixa o conteúdo de um arquivo do Drive	drive.readonly

Ferramenta	Descrição	Escopos
`search`	Pesquisa chats e mensagens de canais no Microsoft Teams	Chat.Read, ChannelMessage.Read.All
`fetch`	Busca uma mensagem do Teams pelo caminho	Chat.Read, ChannelMessage.Read.All
`get_chat_members`	Lista os membros de um chat do Teams	Chat.Read
`get_profile`	Retorna o perfil do usuário autenticado no Teams	User.Read

Ferramenta	Descrição	Escopos
`search_events`	Pesquisa eventos no Calendário do Outlook com filtros de data	Calendars.Read
`fetch_event`	Obtém os detalhes de um evento	Calendars.Read
`fetch_events_batch`	Obtém vários eventos em uma única chamada	Calendars.Read
`list_events`	Lista os eventos do calendário em um intervalo de datas	Calendars.Read
`get_profile`	Retorna o perfil do usuário atual	User.Read

Ferramenta	Descrição	Escopos
`get_profile`	Retorna informações do perfil da conta do Outlook	User.Read
`list_messages`	Obtém emails de uma pasta do Outlook	Mail.Read
`search_messages`	Pesquisa emails no Outlook com filtros opcionais	Mail.Read
`get_recent_emails`	Retorna os emails recebidos mais recentemente	Mail.Read
`fetch_message`	Busca um email pelo ID	Mail.Read
`fetch_messages_batch`	Obtém vários emails em uma única requisição	Mail.Read

Ferramenta	Descrição	Escopos
`get_site`	Localiza um site do SharePoint pelo nome do host e pelo caminho	Sites.Read.All
`search`	Pesquisa documentos do SharePoint e do OneDrive por palavra-chave	Sites.Read.All, Files.Read.All
`list_recent_documents`	Retorna os documentos acessados recentemente	Files.Read.All
`fetch`	Busca o conteúdo de um arquivo pela URL de download do Graph	Files.Read.All
`get_profile`	Obtém o perfil do usuário atual	User.Read

Adiar o carregamento das ferramentas de um servidor MCP

Se você usa a pesquisa de ferramentas, pode adiar o carregamento das funções disponibilizadas por um servidor MCP até que o modelo decida que precisa delas. Para isso, configure defer_loading: true na definição da ferramenta do servidor MCP.

Quando você adia o carregamento de um servidor MCP, o modelo ainda pode usar o rótulo e a descrição do servidor para decidir quando pesquisar nele. As definições de cada função só são carregadas quando necessário. Isso pode reduzir o consumo total de tokens e é especialmente útil para servidores MCP que disponibilizam muitas funções.

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"
}

Riscos e segurança

A ferramenta MCP permite conectar modelos da OpenAI a serviços externos. Essa capacidade traz alguns riscos.

Ao usar conectores, há o risco de enviar dados confidenciais à OpenAI ou de permitir que os modelos leiam dados potencialmente confidenciais nesses serviços.

Os servidores MCP remotos apresentam os mesmos riscos e não foram verificados pela OpenAI. Eles podem permitir que os modelos acessem, enviem e recebam dados e executem ações nesses serviços. Todos os servidores MCP são serviços de terceiros sujeitos a seus próprios termos e condições.

Se encontrar um servidor MCP malicioso, denuncie-o pelo email security@openai.com.

Considere as práticas a seguir ao integrar conectores e servidores MCP remotos.

Injeção de prompt

A injeção de prompt é um risco de segurança importante em qualquer aplicativo que use um LLM. O risco merece atenção especial quando o modelo tem acesso a servidores MCP e conectores capazes de acessar dados confidenciais ou executar ações. Se o prompt enviado ao modelo contiver conteúdo fornecido pelo usuário, use essas ferramentas com cautela e adote medidas de proteção adequadas.

Por exemplo, uma página da Web poderia instruir o modelo a procurar um cliente no seu CRM e incluir o email desse cliente em uma URL. Uma requisição a essa URL revelaria o endereço de email, mesmo que a ferramenta de CRM permitisse apenas operações de leitura.

Para comparar um comunicado público de uma empresa com registros privados do CRM, reúna as informações públicas em uma requisição com apenas a pesquisa na Web habilitada. Passe as informações relevantes para uma segunda requisição com acesso restrito à ferramenta interna de pesquisa no CRM. Assim, os registros dos clientes ficam fora das consultas à Web e das URLs.

Sempre exija aprovação para ações sensíveis

Use as opções de configuração dos parâmetros require_approval e allowed_tools para garantir que todas as ações sensíveis passem por um fluxo de aprovação.

URLs em chamadas e saídas de ferramentas MCP

Pode ser perigoso fazer requisições a URLs ou incorporar URLs de imagens retornadas por chamadas de ferramenta, tanto de conectores quanto de servidores MCP remotos. Antes de incorporar essas URLs ou usá-las de outra forma no código do aplicativo, confirme que você confia nos domínios e serviços que as fornecem.

Conexão com servidores confiáveis

Escolha servidores oficiais hospedados pelos próprios provedores dos serviços. Por exemplo, recomendamos usar o servidor que a própria Stripe hospeda em mcp.stripe.com, em vez de um servidor MCP da Stripe hospedado por terceiros. Como ainda há poucos servidores MCP remotos oficiais, talvez você considere usar um servidor MCP hospedado por uma organização que não opera o servidor do serviço e atua como intermediária, encaminhando requisições ao serviço por meio da sua API. Se precisar usar um desses “agregadores”, avalie sua confiabilidade com atenção redobrada e examine cuidadosamente como ele usa seus dados.

Registre e revise os dados compartilhados com servidores MCP de terceiros

Cada servidor MCP define suas próprias ferramentas e pode solicitar dados que você prefere não compartilhar com quem hospeda o servidor. Por isso, por padrão, a ferramenta MCP da API Responses exige aprovação para cada chamada de ferramenta MCP. Ao desenvolver seu aplicativo, examine de forma sistemática e cuidadosa os tipos de dados compartilhados com esses servidores. Quando considerar que o servidor MCP é confiável, você pode dispensar as aprovações para reduzir a latência de execução.

Também recomendamos registrar todos os dados enviados a servidores MCP. Se você usa a API Responses com store=true, a API já mantém esses registros por 30 dias, a menos que a opção de zero retenção de dados esteja habilitada para sua organização. Você também pode registrar esses dados nos seus próprios sistemas e revisá-los periodicamente para confirmar que o compartilhamento ocorre como esperado.

Servidores MCP maliciosos podem incluir instruções ocultas (injeções de prompt) para induzir os modelos da OpenAI a se comportar de maneira inesperada. A OpenAI implementou proteções integradas para ajudar a detectar e bloquear essas ameaças. Ainda assim, é essencial examinar com atenção as entradas e saídas e estabelecer conexões apenas com servidores confiáveis.

Servidores MCP podem alterar inesperadamente o funcionamento de suas ferramentas, o que pode resultar em comportamentos indesejados ou maliciosos.

Implicações para a zero retenção de dados e a residência de dados

A ferramenta MCP é compatível com a zero retenção de dados e a residência de dados. Como os servidores MCP são serviços de terceiros, os dados enviados a um servidor MCP estão sujeitos às políticas de retenção e residência de dados desse serviço.

Por exemplo, se sua organização tiver residência de dados na Europa, a OpenAI restringirá à Europa a inferência e o armazenamento do Conteúdo do Cliente até o envio de comunicações ou dados ao servidor MCP. Cabe a você garantir que o servidor MCP também atenda a todos os requisitos de zero retenção de dados ou de residência de dados da sua organização. Saiba mais sobre zero retenção de dados e residência de dados.

Observações sobre o uso

Disponibilidade na API	Limites de taxa	Observações
Responses Chat Completions Assistants	Build 1000 RPM Launch e Grow 2000 RPM	Preços ZDR e residência de dados

Disponibilidade na API

Limites de taxa

Observações

Responses

Chat Completions

Assistants

Build
1000 RPM

Launch e Grow
2000 RPM

Preços
ZDR e residência de dados

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso