除了通过函数调用向模型提供工具,您还可以使用 远程 MCP 服务器 或 安全 MCP 隧道 扩展模型的能力。模型在响应用户提示词时,可以根据需要使用这些工具连接并控制外部服务。作为开发者,您可以自动允许这些工具调用,也可以要求每次调用先获得您的明确批准。
本指南介绍如何在 Responses API 中使用 MCP 工具。现有模型仍支持内置连接器。有关弃用策略和兼容性示例,请参阅旧版连接器。如果您使用 Agents API 会话,请参阅 MCP 连接,了解如何从托管服务或您的沙盒建立连接。
如果您的 MCP 服务器是私有服务器、部署在本地或位于防火墙后方,可以通过安全 MCP 隧道将其连接到支持此功能的 OpenAI 产品,无需将服务器暴露在公共互联网上。请从 openai/tunnel-client 下载最新公开版本。
使用 mcp 工具类型即可在 Responses API 中连接 MCP 服务器。要连接远程 MCP 服务器,请设置 server_url。要连接本地 MCP 服务器,请使用 tunnel_id 通过安全 MCP 隧道建立连接。根据服务器的要求,您可能还需要在 authorization 参数中提供 OAuth 访问令牌。
以下示例使用公开的 OpenAI 文档 MCP 服务器查找有关 Responses API 流式输出的文档。此服务器提供只读文档工具,无需身份验证。示例在查询公开文档时跳过了工具调用审批。共享敏感数据时,请启用审批。
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.2-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.2-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.2-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.2-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.2-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.2-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.2-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)
在 Responses API 中,请仅使用您信任的远程 MCP 服务器。恶意服务器可能从进入模型上下文的任何内容中窃取敏感数据。使用此工具前,请仔细阅读下文的风险与安全一节。
API 会在模型响应的 output 数组中返回新的输出项。如果模型决定使用 MCP 服务器,它会先向服务器请求可用工具列表,从而生成一个 mcp_list_tools 输出项。以下输出示例仅列出搜索工具,并缩短了工具描述。该服务器还提供其他文档工具。
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"
}
]
}
如果模型决定调用 MCP 服务器提供的某个工具,响应中还会包含一个 mcp_call 输出项,显示模型向 MCP 工具发送了什么,以及工具返回了什么。
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"
}
继续阅读,了解 MCP 工具的工作原理、如何筛选可用工具,以及如何处理工具调用审批请求。
大多数近期推出的模型都支持在 Responses API 中使用 MCP 工具。您可以在模型文档中查看您的模型是否支持 MCP 工具。使用 MCP 工具时,您只需为导入工具定义或调用工具时消耗的 Token 付费。每次工具调用均不另行收费。
API 调用 MCP 工具的过程分为以下步骤。
当您在 tools 参数中指定远程 MCP 服务器时,API 会尝试从服务器获取工具列表。Responses API 可连接支持 Streamable HTTP 或 HTTP/SSE 传输协议的远程 MCP 服务器。
成功获取工具列表后,模型响应中会出现一个新的 mcp_list_tools 输出项。该对象的 tools 属性列出已成功导入的工具。以下示例片段仅列出搜索工具,并缩短了工具描述。
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"
}
]
}
只要 API 请求的上下文中包含 mcp_list_tools 项,API 就不会在每轮对话中重新向 MCP 服务器获取工具列表。建议您在每次对话或工作流执行期间,都将该项保留在模型上下文中,以减少延迟。
有些 MCP 服务器提供数十个工具。向模型提供大量工具可能会增加费用和延迟。如果您只需要服务器提供的部分工具,可以使用 allowed_tools 参数仅导入这些工具。以下示例只导入 search_openai_docs,用于查找文档链接。
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.2-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.2-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.2-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.2-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.2-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.2-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.2-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)
模型获得这些工具的定义后,可以根据上下文决定是否调用工具。当模型决定调用某个 MCP 工具时,API 会向远程 MCP 服务器发出调用请求,将工具输出放入模型上下文,并生成一个 mcp_call 项。为简洁起见,以下输出示例省略了搜索结果的元数据:
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"
}
该项包含模型为本次工具调用选择的参数,以及远程 MCP 服务器返回的 output。所有模型都可以选择多次调用 MCP 工具,因此一次 API 请求可能生成多个这样的输出项。
如果工具调用失败,该项的 error 字段会包含 MCP 协议错误、MCP 工具执行错误或一般连接错误。有关 MCP 错误的说明,请参阅 MCP 规范中的错误处理。
默认情况下,在与连接器或远程 MCP 服务器共享任何数据之前,OpenAI 都会请求您审批。通过审批,您可以查看并控制向 MCP 服务器发送的数据。强烈建议您仔细检查与远程 MCP 服务器共享的所有数据,也可以将其记录到日志中。要试用审批流程,请在快速入门示例中将 require_approval 设为 "always",而非 "never",然后运行示例。当 API 就某次 MCP 工具调用请求审批时,Response 对象的输出中会出现一个 mcp_approval_request 项。示例如下:
1234567{
"id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
"type": "mcp_approval_request",
"arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
"name": "search_openai_docs",
"server_label": "openai_docs"
}
批准调用前,请检查请求调用的工具及其参数。随后,您可以创建一个新的 Response 对象并向其中追加一个 mcp_approval_response 项,以回复审批请求。请将以下示例中的响应 ID 和审批请求 ID 替换为您的请求实际返回的 ID。.NET 示例会从初始响应中获取这些 ID。每次审批仅适用于一次工具调用。后续审批请求也请按相同方式处理。
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.2-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.2-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.2-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.2-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.2-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.2-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.2-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)
此处使用 previous_response_id 参数,将新的 Response 对象与之前生成审批请求的 Response 对象关联起来。您也可以将一个响应的输出作为下一次请求的输入,从而最大程度地控制哪些内容进入模型上下文。
当您确信某个远程 MCP 服务器值得信任时,可以选择跳过审批以减少延迟。如下例所示,您可以将 MCP 工具的 require_approval 参数设置为一个对象,仅列出您希望跳过审批的工具。也可以将该参数设置为 'never',跳过对该远程 MCP 服务器上所有工具的审批。
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.2-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.2-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.2-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.2-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.2-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.2-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.2-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)
OpenAI 文档 MCP 服务器无需身份验证。其他 MCP 服务器可能要求进行身份验证,最常见的方式是使用 OAuth 访问令牌。请在 MCP 工具的 authorization 字段中提供该令牌:
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.2-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.2-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.2-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.2-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.2-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.2-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.2-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)
为防止敏感令牌泄露,Responses API 不会存储您在 authorization 字段中提供的值。创建的 Response 对象中也不会显示该值。因此,每次向 Responses API 发送创建响应的请求时,都必须提供 authorization 的值。
对于 2026 年 9 月 1 日之后发布的模型,connector_id 已弃用。请使用 server_url 连接远程 MCP 服务器,或使用
tunnel_id 通过
安全 MCP 隧道连接本地 MCP 服务器。现有模型仍支持连接器。本节示例使用的 gpt-5.2 发布于上述日期之前。
Responses API 内置了少量用于访问第三方服务的连接器。通过这些连接器,您可以从 Dropbox、Gmail 等常用应用中获取上下文,让模型与这些服务交互。
连接器的使用方式与远程 MCP 服务器相同。两者都能让 OpenAI 模型在 API 请求中访问额外的第三方工具。调用远程 MCP 服务器时,您需要传入 server_url。使用连接器时,则需传入 connector_id,它是 API 中可用连接器的唯一标识。
连接器需要 OAuth 访问令牌,由您的应用通过 authorization 参数提供。
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)
- Dropbox:
connector_dropbox
- Gmail:
connector_gmail
- Google 日历:
connector_googlecalendar
- Google 云端硬盘:
connector_googledrive
- Microsoft Teams:
connector_microsoftteams
- Outlook 日历:
connector_outlookcalendar
- Outlook 邮件:
connector_outlookemail
- SharePoint:
connector_sharepoint
我们优先为没有官方远程 MCP 服务器的服务提供连接器。例如,GitHub 已有官方 MCP 服务器。将 https://api.githubcopilot.com/mcp/ 传入 MCP 工具的 server_url 字段即可连接。
请在 authorization 字段中传入 OAuth 访问令牌。您的应用必须单独处理 OAuth 客户端注册和授权。
测试时,您可以使用 Google 的 OAuth 2.0 Playground 生成临时访问令牌,并在 API 请求中使用。
要在 Playground 中测试 API 的连接器功能,请先输入以下内容:
https://www.googleapis.com/auth/calendar.events
请在第 1 步:选择 API 并授权中输入上述授权范围,以允许 API 读取 Google 日历中的活动。
使用您的 Google 账号为应用授权后,您会进入第 2 步:用授权码换取令牌。这一步会生成访问令牌,供您在使用 Google 日历连接器的 API 请求中使用:
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)
通过连接器调用 MCP 工具与通过远程 MCP 服务器调用 MCP 工具的输出格式相同,输出项的类型都是 mcp_call。在此示例中,传给连接器的参数和连接器返回的响应都是 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"
}
可用工具取决于您的 OAuth 令牌具有哪些授权范围。展开下表,即可查看连接到各个应用时可以使用的工具。
| 工具 | 说明 | 授权范围 |
|---|
search | 在 Dropbox 中搜索与查询匹配的文件 | files.metadata.read, account_info.read |
fetch | 按路径获取文件,也可下载原始文件 | files.content.read |
search_files | 搜索 Dropbox 文件并返回结果 | files.metadata.read, account_info.read |
fetch_file | 获取文件的文本或原始内容 | files.content.read, account_info.read |
list_recent_files | 返回用户有权访问且最近修改过的文件 | files.metadata.read, account_info.read |
get_profile | 获取当前 Dropbox 用户的个人资料 | account_info.read |
| 工具 | 说明 | 授权范围 |
|---|
get_profile | 返回当前 Gmail 用户的个人资料 | userinfo.email, userinfo.profile |
search_emails | 在 Gmail 中搜索与查询或标签匹配的邮件 | gmail.modify |
search_email_ids | 获取符合搜索条件的 Gmail 邮件 ID | gmail.modify |
get_recent_emails | 返回最近收到的 Gmail 邮件 | gmail.modify |
read_email | 获取一封 Gmail 邮件,包括正文 | gmail.modify |
batch_read_email | 在一次调用中读取多封 Gmail 邮件 | gmail.modify |
| 工具 | 说明 | 授权范围 |
|---|
get_profile | 返回当前 Google 日历用户的个人资料 | userinfo.email, userinfo.profile |
search | 搜索日历活动,可指定时间范围 | calendar.events |
fetch | 获取单个日历活动的详细信息 | calendar.events |
search_events | 按筛选条件查找日历活动 | calendar.events |
read_event | 按 ID 读取 Google 日历活动 | calendar.events |
| 工具 | 说明 | 授权范围 |
|---|
get_profile | 返回当前 Google 云端硬盘用户的个人资料 | userinfo.email, userinfo.profile |
list_drives | 列出用户有权访问的共享云端硬盘 | drive.readonly |
search | 按查询条件搜索云端硬盘中的文件 | drive.readonly |
recent_documents | 返回最近修改的文档 | drive.readonly |
fetch | 下载云端硬盘中文件的内容 | drive.readonly |
| 工具 | 说明 | 授权范围 |
|---|
search | 搜索 Microsoft Teams 聊天和频道消息 | Chat.Read, ChannelMessage.Read.All |
fetch | 按路径获取 Teams 消息 | Chat.Read, ChannelMessage.Read.All |
get_chat_members | 列出 Teams 聊天的成员 | Chat.Read |
get_profile | 获取已通过身份验证的 Teams 用户的个人资料 | User.Read |
| 工具 | 说明 | 授权范围 |
|---|
search_events | 按日期筛选条件搜索 Outlook 日历事件 | Calendars.Read |
fetch_event | 获取单个事件的详细信息 | Calendars.Read |
fetch_events_batch | 在一次调用中获取多个事件 | Calendars.Read |
list_events | 列出指定日期范围内的日历事件 | Calendars.Read |
get_profile | 获取当前用户的个人资料 | User.Read |
| 工具 | 说明 | 授权范围 |
|---|
get_profile | 返回 Outlook 账号的个人资料 | User.Read |
list_messages | 获取文件夹中的 Outlook 邮件 | Mail.Read |
search_messages | 搜索 Outlook 邮件,可指定筛选条件 | Mail.Read |
get_recent_emails | 返回最近收到的邮件 | Mail.Read |
fetch_message | 按 ID 获取单封邮件 | Mail.Read |
fetch_messages_batch | 在一次请求中获取多封邮件 | Mail.Read |
| 工具 | 说明 | 授权范围 |
|---|
get_site | 根据主机名和路径解析 SharePoint 站点 | Sites.Read.All |
search | 按关键词搜索 SharePoint 和 OneDrive 文档 | Sites.Read.All, Files.Read.All |
list_recent_documents | 返回最近访问的文档 | Files.Read.All |
fetch | 通过 Graph 文件下载 URL 获取文件内容 | Files.Read.All |
get_profile | 获取当前用户的个人资料 | User.Read |
如果您使用工具搜索,可以等到模型确定需要某个函数时,再加载 MCP 服务器提供的该函数。要启用此功能,请在 MCP 服务器的工具定义中设置 defer_loading: true。
启用延迟加载后,模型仍可根据 MCP 服务器的标签和描述决定何时搜索该服务器上的工具,但只有在需要时才会加载具体的函数定义。这有助于减少总体 Token 用量,尤其适合提供大量函数的 MCP 服务器。
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"
}
MCP 工具可以将 OpenAI 模型连接到外部服务。这项功能很强大,但也伴随一些风险。
使用连接器可能会将敏感数据发送给 OpenAI,或允许模型读取相关服务中可能含有敏感信息的数据。
远程 MCP 服务器也存在这些风险,而且 OpenAI 未对这些服务器进行验证。这些服务器可以让模型访问、发送和接收数据,以及在相关服务中执行操作。所有 MCP 服务器均属于第三方服务,适用各自的条款和条件。
如果您发现恶意 MCP 服务器,请向 security@openai.com 举报。
集成连接器和远程 MCP 服务器时,请参考以下最佳实践。
在任何 LLM 应用中,提示词注入都是需要重视的安全问题。如果模型可以使用能够访问敏感数据或执行操作的 MCP 服务器和连接器,这一点尤为重要。如果模型的提示词包含用户提供的内容,请谨慎使用这些工具,并采取适当的防护措施。
例如,网页中的指令可能会让模型在您的 CRM 系统中查找某位客户,并将该客户的电子邮件地址放入 URL 中。即使 CRM 工具只有只读权限,访问该 URL 也会泄露客户的电子邮件地址。
要将一家公司的公开公告与私有 CRM 记录进行比对,请在第一个请求中仅启用网页搜索,收集公开信息。然后,将其中与比对有关的信息传入第二个请求,并仅允许该请求使用您的内部 CRM 搜索工具。这样,客户记录就不会出现在网页搜索的查询内容或 URL 中。
请配置 require_approval 和 allowed_tools 参数,确保所有敏感操作都必须经过审批流程。
连接器或远程 MCP 服务器的工具调用输出可能包含 URL。向这些 URL 发送请求,或在应用中嵌入工具返回的图片 URL,都可能带来风险。在应用代码中嵌入这些 URL 或以其他方式使用它们之前,请确认提供这些 URL 的域名和服务值得信任。
请选择由服务提供商自行托管的官方服务器。例如,我们建议连接 Stripe 在 mcp.stripe.com 托管的官方服务器,而非第三方托管的 Stripe MCP 服务器。目前官方远程 MCP 服务器数量有限,您可能会考虑使用其他组织托管的 MCP 服务器。这些组织并不运营目标服务,而是通过您的 API 将请求转发给该服务。如果必须采用这种方式,请格外谨慎地调查这些“聚合服务商”,并仔细审查它们如何使用您的数据。
MCP 服务器自行定义其工具,因此工具可能会请求一些您不愿与服务器运营方共享的数据。为此,Responses API 中的 MCP 工具默认要求每次 MCP 工具调用都经过审批。开发应用时,请全面、仔细地检查与这些服务器共享的数据类型。当您确信某个 MCP 服务器值得信任后,可以跳过审批以减少执行延迟。
我们也建议记录发送到 MCP 服务器的所有数据。如果您在使用 Responses API 时设置了 store=true,API 会将这些数据记录并保留 30 天,除非您的组织已启用零数据保留。您也可以在自己的系统中记录这些数据,并定期审查,确认实际共享的数据符合您的预期。
恶意 MCP 服务器可能包含隐藏指令(提示词注入),试图诱使 OpenAI 模型执行非预期操作。OpenAI 已内置防护机制,帮助检测和阻止这些威胁,但您仍须仔细审查输入和输出,并确保只与可信服务器建立连接。
MCP 服务器可能会在您不知情的情况下更改工具的行为,从而导致非预期行为或恶意行为。
MCP 工具与零数据保留和数据驻留兼容。请注意,MCP 服务器属于第三方服务,发送到 MCP 服务器的数据受相应服务的数据保留和数据驻留政策约束。
例如,如果您的组织选择了欧洲数据驻留,在向 MCP 服务器发送消息或数据之前,OpenAI 仅在欧洲对客户内容执行推理和存储。您有责任确保 MCP 服务器也符合适用于您的所有零数据保留或数据驻留要求。有关零数据保留和数据驻留的更多信息,请参阅数据指南。