Servidores MCP | OpenAI API

Além das ferramentas que você disponibiliza ao modelo com a chamada de função, você pode oferecer novas capacidades aos modelos usando servidores MCP remotos ou o Túnel MCP seguro. Essas ferramentas permitem que o modelo se conecte a serviços externos e os controle quando necessário para responder ao prompt de um usuário. Essas chamadas de ferramentas podem ser permitidas automaticamente ou restringidas para exigir sua aprovação explícita como desenvolvedor.

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 conectores integrados continuam disponíveis para os modelos existentes; consulte Conectores legados para conhecer a política de descontinuação e os exemplos de compatibilidade. Para sessões da API de Agentes, consulte Conexões MCP, que aborda conexões a partir do serviço gerenciado ou do seu sandbox.

Túnel MCP seguro

Se o seu servidor MCP for privado, estiver em infraestrutura local ou atrás de um firewall, use o Túnel MCP seguro para conectá-lo a produtos OpenAI compatíveis 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 por meio do Túnel MCP seguro. Dependendo do servidor, você também pode precisar de um token de acesso OAuth no parâmetro authorization.

Usar um servidor MCP remoto na Responses API

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": "dmcp",
        "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
        "server_url": "https://dmcp-server.deno.dev/mcp",
        "require_approval": "never"
      }
    ],
    "input": "Roll 2d4+1"
  }'

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: "dmcp",
      server_description:
        "A Dungeons and Dragons MCP server to assist with dice rolling.",
      server_url: "https://dmcp-server.deno.dev/mcp",
      require_approval: "never",
    },
  ],
  input: "Roll 2d4+1",
});

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": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://dmcp-server.deno.dev/mcp",
            "require_approval": "never",
        },
    ],
    input="Roll 2d4+1",
)

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("dmcp")
	tool.OfMcp.ServerDescription = openai.String("A Dungeons and Dragons MCP server to assist with dice rolling.")
	tool.OfMcp.ServerURL = openai.String("https://dmcp-server.deno.dev/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("Roll 2d4+1")},
	})
	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("Roll 2d4+1")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("dmcp")
                .serverDescription(
                    "A Dungeons and Dragons MCP server to assist with dice rolling.")
                .serverUrl("https://dmcp-server.deno.dev/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: "dmcp",
        serverUri: new Uri("https://dmcp-server.deno.dev/mcp"),
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Roll 2d4+1"));

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: "dmcp",
      server_description: "A Dungeons and Dragons MCP server to assist with dice rolling.",
      server_url: "https://dmcp-server.deno.dev/mcp",
      require_approval: "never"
    }
  ],
  input: "Roll 2d4+1"
)

puts(response.output_text)

É muito importante que os desenvolvedores confiem em qualquer servidor MCP remoto que usem com a API Responses. Um servidor malicioso pode exfiltrar dados sensíveis de qualquer conteúdo que entre no contexto do modelo. Leia com atenção a seção Riscos e segurança abaixo antes de usar esta ferramenta.

A API retornará novos itens no array output da resposta do modelo. Se o modelo decidir usar um servidor MCP, primeiro fará uma solicitação para listar as ferramentas disponíveis no servidor, o que criará um item de saída mcp_list_tools. No exemplo de servidor MCP remoto acima, esse item contém apenas uma definição de ferramenta:

1234567891011121314151617181920212223{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "dmcp",
  "tools": [
    {
      "annotations": null,
      "description": "Given a string of text describing a dice roll...",
      "input_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "diceRollExpression": {
            "type": "string"
          }
        },
        "required": ["diceRollExpression"],
        "additionalProperties": false
      },
      "name": "roll"
    }
  ]
}

Se o modelo decidir chamar uma das ferramentas disponíveis no servidor MCP, você também encontrará uma saída mcp_call que mostrará o que o modelo enviou à ferramenta MCP e o que ela retornou como saída.

12345678910{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"diceRollExpression\":\"2d4 + 1\"}",
  "error": null,
  "name": "roll",
  "output": "4",
  "server_label": "dmcp"
}

Continue lendo o guia abaixo para saber mais sobre como a ferramenta MCP funciona, como filtrar as ferramentas disponíveis e como lidar com solicitações de aprovação de chamadas de ferramenta.

Como funciona

A ferramenta MCP está disponível na API Responses na maioria dos modelos recentes. Verifique aqui a compatibilidade da ferramenta MCP com seu modelo. Ao usar a ferramenta MCP, você paga apenas pelos tokens usados ao importar definições de ferramentas ou fazer chamadas de ferramentas. Não há taxas adicionais por chamada de ferramenta.

A seguir, veremos passo a passo o processo 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 uma lista de ferramentas do servidor. A Responses API funciona com servidores MCP remotos que oferecem suporte aos protocolos de transporte Streamable HTTP ou HTTP/SSE.

Se a lista de ferramentas for obtida com sucesso, um novo item de saída mcp_list_tools aparecerá na saída da resposta do modelo. A propriedade tools desse objeto mostrará as ferramentas que foram importadas com sucesso.

1234567891011121314151617181920212223{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "dmcp",
  "tools": [
    {
      "annotations": null,
      "description": "Given a string of text describing a dice roll...",
      "input_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "diceRollExpression": {
            "type": "string"
          }
        },
        "required": ["diceRollExpression"],
        "additionalProperties": false
      },
      "name": "roll"
    }
  ]
}

Enquanto o item mcp_list_tools estiver presente no contexto de uma solicitação à API, ela não buscará novamente a lista de ferramentas do servidor MCP a cada turno de uma conversa. Recomendamos manter esse item no contexto do modelo em todas as conversas ou execuções de fluxos de trabalho para reduzir a latência.

Filtrar ferramentas

Alguns servidores MCP podem ter dezenas de ferramentas, e expor muitas ferramentas ao modelo pode resultar em custo e latência elevados. Se você tiver interesse apenas em um subconjunto das ferramentas que um servidor MCP expõe, poderá usar o parâmetro allowed_tools para importar somente essas ferramentas.

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": "dmcp",
        "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
        "server_url": "https://dmcp-server.deno.dev/mcp",
        "require_approval": "never",
        "allowed_tools": ["roll"]
      }
    ],
    "input": "Roll 2d4+1"
  }'

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: "dmcp",
      server_description:
        "A Dungeons and Dragons MCP server to assist with dice rolling.",
      server_url: "https://dmcp-server.deno.dev/mcp",
      require_approval: "never",
      allowed_tools: ["roll"],
    },
  ],
  input: "Roll 2d4+1",
});

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": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://dmcp-server.deno.dev/mcp",
            "require_approval": "never",
            "allowed_tools": ["roll"],
        }
    ],
    input="Roll 2d4+1",
)

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("dmcp")
	tool.OfMcp.ServerDescription = openai.String("A Dungeons and Dragons MCP server to assist with dice rolling.")
	tool.OfMcp.ServerURL = openai.String("https://dmcp-server.deno.dev/mcp")
	tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}
	tool.OfMcp.AllowedTools = responses.ToolMcpAllowedToolsUnionParam{OfMcpAllowedTools: []string{"roll"}}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Roll 2d4+1")},
	})
	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("Roll 2d4+1")
        .addTool(
            Tool.Mcp.builder()
                .serverLabel("dmcp")
                .serverDescription(
                    "A Dungeons and Dragons MCP server to assist with dice rolling.")
                .serverUrl("https://dmcp-server.deno.dev/mcp")
                .requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
                .allowedToolsOfMcp(List.of("roll"))
                .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: "dmcp",
        serverUri: new Uri("https://dmcp-server.deno.dev/mcp"),
        allowedTools: new McpToolFilter() { ToolNames = { "roll" } },
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
    )
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Roll 2d4+1"));

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: "Roll 2d4+1",
  tools: [
    {
      type: :mcp,
      server_label: "dmcp",
      server_description: "A Dungeons and Dragons MCP server to assist with dice rolling.",
      server_url: "https://dmcp-server.deno.dev/mcp",
      require_approval: :never,
      allowed_tools: ["roll"]
    }
  ]
)

puts(response.output_text)

Etapa 2: Chamar ferramentas

Depois que o modelo tiver acesso a essas definições de ferramentas, poderá optar por chamá-las dependendo do que estiver em seu contexto. Quando o modelo decidir chamar uma ferramenta MCP, a API fará uma solicitação ao servidor MCP remoto para chamar a ferramenta e incluirá a saída no contexto do modelo. Isso cria um item mcp_call como este:

12345678910{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"diceRollExpression\":\"2d4 + 1\"}",
  "error": null,
  "name": "roll",
  "output": "4",
  "server_label": "dmcp"
}

Esse item inclui tanto os argumentos que o modelo decidiu usar nessa chamada de ferramenta quanto o output retornado pelo servidor MCP remoto. Todos os modelos podem optar por fazer várias chamadas de ferramenta MCP, então você poderá ver vários desses itens gerados em uma única solicitação à API.

Chamadas de ferramenta que falharem preencherão o campo error desse item com erros do protocolo MCP, erros de execução de ferramentas MCP ou erros gerais de conectividade. Os erros MCP estão documentados na especificação MCP aqui.

Aprovações

Por padrão, a OpenAI solicitará sua aprovação antes de compartilhar qualquer dado com um conector ou servidor MCP remoto. As aprovações ajudam você a manter o controle e a visibilidade sobre quais dados estão sendo enviados a um servidor MCP. Recomendamos fortemente que você revise com atenção (e, opcionalmente, registre em logs) todos os dados compartilhados com um servidor MCP remoto. Uma solicitação de aprovação para fazer uma chamada de ferramenta MCP cria um item mcp_approval_request na saída do objeto Response, como este:

1234567{
  "id": "mcpr_68a619e1d82c8190b50c1ccba7ad18ef0d2d23a86136d339",
  "type": "mcp_approval_request",
  "arguments": "{\"diceRollExpression\":\"2d4 + 1\"}",
  "name": "roll",
  "server_label": "dmcp"
}

Você pode responder a essa solicitação criando um novo objeto Response e adicionando um item mcp_approval_response a ele.

Aprovar o uso de ferramentas em uma solicitaçã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": "dmcp",
        "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
        "server_url": "https://dmcp-server.deno.dev/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
26
27import OpenAI from "openai";
const client = new OpenAI();

const resp = await client.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "mcp",
      server_label: "dmcp",
      server_description:
        "A Dungeons and Dragons MCP server to assist with dice rolling.",
      server_url: "https://dmcp-server.deno.dev/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": "dmcp",
            "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
            "server_url": "https://dmcp-server.deno.dev/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("dmcp")
	tool.OfMcp.ServerDescription = openai.String("A Dungeons and Dragons MCP server to assist with dice rolling.")
	tool.OfMcp.ServerURL = openai.String("https://dmcp-server.deno.dev/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("dmcp")
                .serverDescription("A Dungeons and Dragons MCP server.")
                .serverUrl("https://dmcp-server.deno.dev/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
31using 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: "dmcp",
        serverUri: new Uri("https://dmcp-server.deno.dev/mcp"),
        toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )
);

// Step 1: Create a response that requests tool-call approval.
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Roll 2d4+1"));
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.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: "dmcp",
      server_url: "https://dmcp-server.deno.dev/mcp",
      server_description: "A Dungeons and Dragons MCP server.",
      require_approval: :always
    }
  ]
)

puts(response.output_text)

Aqui, usamos o parâmetro previous_response_id para encadear esta nova resposta com a resposta anterior, que gerou a solicitação de aprovação. Mas você também pode enviar as saídas de uma resposta como entradas de outra para ter o máximo de controle sobre o que entra no contexto do modelo.

Se e quando você se sentir à vontade para confiar em um servidor MCP remoto, poderá optar por 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 deseja dispensar aprovações, conforme mostrado abaixo, ou defina-o como 'never' para dispensar aprovações para todas as ferramentas desse servidor MCP remoto.

Nunca exigir aprovação para algumas ferramentas

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

Ao contrário do servidor MCP que usamos como exemplo acima, a maioria dos outros servidores MCP exige autenticação. O método mais comum é um token de acesso OAuth. Forneça esse token no campo authorization da ferramenta MCP:

Usar a ferramenta MCP do 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 sensíveis, a Responses API não armazena o valor fornecido no campo authorization. Esse valor também não ficará visível no objeto Response criado. Por isso, você deve enviar o valor de authorization em cada solicitação de criação que fizer à Responses API.

Conectores legados

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 mantêm o suporte a conectores. Os exemplos desta seção usam gpt-5.2, que foi lançado antes dessa data.

A Responses API oferece suporte integrado a um conjunto limitado de conectores para serviços de terceiros. Esses conectores permitem trazer contexto de aplicativos populares, como Dropbox e Gmail, para que o modelo possa interagir com serviços populares.

Conectores podem ser usados da mesma forma que servidores MCP remotos. Ambos permitem que um modelo OpenAI acesse ferramentas adicionais de terceiros em uma solicitação à API. No entanto, em vez de passar um server_url, como faria para chamar um servidor MCP remoto, você passa um connector_id, que identifica de forma única um conector disponível na API.

Os conectores exigem um token de acesso OAuth fornecido pelo seu aplicativo no parâmetro authorization.

Use um conector legado com 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 Calendar: connector_googlecalendar
Google Drive: connector_googledrive
Microsoft Teams: connector_microsoftteams
Outlook Calendar: connector_outlookcalendar
Outlook Email: 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 ao qual você pode se conectar passando https://api.githubcopilot.com/mcp/ no campo server_url da ferramenta MCP.

Como autorizar um conector

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

Para 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 usar o playground para testar a funcionalidade de conectores da API, comece inserindo:

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

Esse escopo de autorização permitirá que a API leia eventos do Google Calendar. Na interface, em "Etapa 1: Selecionar e autorizar APIs".

Depois de autorizar o aplicativo com sua conta do Google, você chegará à Etapa 2: Trocar o código de autorização por tokens. Isso gerará um token de acesso que você poderá usar em uma solicitação à API com o conector do Google Calendar:

Use o conector do 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)

Uma chamada de ferramenta MCP de um Conector terá o mesmo formato que uma chamada de ferramenta MCP de um servidor MCP remoto, usando o tipo de item de saída mcp_call. Nesse 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 do 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`	Obtém 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 no 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 e-mails que correspondem a uma consulta ou 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`	Obtém uma única mensagem do Gmail, incluindo seu corpo	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 Calendar	userinfo.email, userinfo.profile
`search`	Pesquisa eventos do Calendar, com opção de limitar a um intervalo de tempo	calendar.events
`fetch`	Obtém os detalhes de um único evento do Calendar	calendar.events
`search_events`	Consulta eventos do Calendar usando filtros	calendar.events
`read_event`	Lê um evento do Google Calendar 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 do Microsoft Teams	Chat.Read, ChannelMessage.Read.All
`fetch`	Obtém 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 do Outlook Calendar com filtros de data	Calendars.Read
`fetch_event`	Obtém os detalhes de um único evento	Calendars.Read
`fetch_events_batch`	Obtém vários eventos em uma única chamada	Calendars.Read
`list_events`	Lista eventos do calendário em um intervalo de datas	Calendars.Read
`get_profile`	Obter o perfil do usuário atual	User.Read

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

Ferramenta	Descrição	Escopos
`get_site`	Identificar um site do SharePoint pelo nome do host e pelo caminho	Sites.Read.All
`search`	Pesquisar documentos do SharePoint/OneDrive por palavra-chave	Sites.Read.All, Files.Read.All
`list_recent_documents`	Retornar documentos acessados recentemente	Files.Read.All
`fetch`	Obter conteúdo de uma URL de download de arquivo do Graph	Files.Read.All
`get_profile`	Obter o perfil do usuário atual	User.Read

Adiar o carregamento de ferramentas de um servidor MCP

Se você usa a pesquisa de ferramentas, pode adiar o carregamento das funções expostas 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, mas as definições de cada função só são carregadas quando necessário. Isso pode ajudar a reduzir o uso total de tokens e é especialmente útil para servidores MCP que expõem muitas funções.

1
2
3
4
5
6
7
8{
    "type": "mcp",
    "server_label": "dmcp",
    "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
    "server_url": "https://dmcp-server.deno.dev/mcp",
    "defer_loading": true,
    "require_approval": "never"
}

Riscos e segurança

A ferramenta MCP permite conectar modelos da OpenAI a serviços externos. É um recurso poderoso que envolve alguns riscos.

No caso dos conectores, há o risco de enviar dados sensíveis à OpenAI ou de permitir que os modelos leiam dados potencialmente sensíveis nesses serviços.

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

Se você encontrar um servidor MCP malicioso, denuncie-o para security@openai.com.

Veja abaixo algumas práticas recomendadas a considerar ao integrar conectores e servidores MCP remotos.

Injeção de prompt

A injeção de prompt é uma questão importante de segurança em qualquer aplicativo que use LLMs, especialmente quando você dá ao modelo acesso a servidores MCP e conectores que podem acessar dados sensíveis ou executar ações. Use essas ferramentas com a devida cautela e medidas de proteção adequadas se o prompt enviado ao modelo contiver conteúdo fornecido pelo usuário.

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

Use as configurações disponíveis dos parâmetros require_approval e allowed_tools para garantir que qualquer ação sensível exija um fluxo de aprovação.

URLs nas chamadas e saídas de ferramentas MCP

Pode ser perigoso fazer requisições a URLs ou incorporar URLs de imagens fornecidas nas saídas de chamadas de ferramentas, sejam elas de conectores ou de servidores MCP remotos. Certifique-se de que você confia nos domínios e serviços que fornecem essas URLs antes de incorporá-las ou usá-las de qualquer outra forma no código do seu aplicativo.

Conexão com servidores confiáveis

Escolha servidores oficiais hospedados pelos próprios provedores de serviços (por exemplo, recomendamos conectar-se ao servidor Stripe hospedado pela Stripe em mcp.stripe.com, em vez de um servidor MCP da Stripe hospedado por terceiros). Como ainda não há muitos servidores MCP remotos oficiais, você pode considerar usar um servidor MCP hospedado por uma organização que não opera esse servidor e que encaminha solicitações a esse serviço por meio da sua API. Se precisar fazer isso, redobre o cuidado ao avaliar esses "agregadores" e analise atentamente como eles usam seus dados.

Registre e revise os dados compartilhados com servidores MCP de terceiros.

Como os servidores MCP fornecem suas próprias definições de ferramentas, eles podem solicitar dados que você nem sempre se sente à vontade para compartilhar com o host desse servidor MCP. Por isso, a ferramenta MCP na API Responses exige, por padrão, aprovação para cada chamada de ferramenta MCP. Ao desenvolver seu aplicativo, analise de forma cuidadosa e rigorosa os tipos de dados compartilhados com esses servidores MCP. Quando tiver confiança suficiente nesse servidor MCP, você poderá dispensar essas 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 Responses API com store=true, esses dados já são registrados pela API 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 garantir que o compartilhamento ocorra conforme o esperado.

Servidores MCP maliciosos podem incluir instruções ocultas (injeções de prompt) criadas para fazer os modelos da OpenAI se comportarem de forma inesperada. Embora a OpenAI tenha implementado proteções integradas para ajudar a detectar e bloquear essas ameaças, é essencial revisar cuidadosamente as entradas e saídas e garantir que as conexões sejam estabelecidas apenas com servidores confiáveis.

Os servidores MCP podem alterar o comportamento das ferramentas de forma inesperada, o que pode levar a comportamentos indesejados ou maliciosos.

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

A ferramenta MCP é compatível com zero retenção de dados e residência de dados, mas é importante lembrar que 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.

Em outras palavras, se sua organização tem residência de dados na Europa, a OpenAI restringirá a inferência e o armazenamento do Conteúdo do Cliente à Europa até o momento em que comunicações ou dados forem enviados ao servidor MCP. É sua responsabilidade garantir que o servidor MCP também cumpra quaisquer requisitos de zero retenção de dados ou residência de dados que você tenha. Saiba mais sobre zero retenção de dados e residência de dados aqui.

Notas de uso

Disponibilidade na API	Limites de taxa	Notas
Responses Chat Completions Assistants	Nível 1 200 RPM Níveis 2 e 3 1000 RPM Níveis 4 e 5 2000 RPM	Preços ZDR e residência de dados

Disponibilidade na API

Limites de taxa

Notas

Responses

Chat Completions

Assistants

Nível 1
200 RPM

Níveis 2 e 3
1000 RPM

Níveis 4 e 5
2000 RPM

Preços
ZDR e residência de dados

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog