除了透過函式呼叫提供工具給模型,你也可以使用遠端 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-astra",
"tools": [
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never"
}
],
"input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import OpenAI from "openai";
const client = new OpenAI();
const resp = await client.responses.create({
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "never",
},
],
input:
"Search the OpenAI docs for Responses API streaming and return the relevant links.",
});
console.log(resp.output_text);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never",
},
],
input="Search the OpenAI docs for Responses API streaming and return the relevant links.",
)
print(resp.output_text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfMcp("openai_docs")
tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Search the OpenAI docs for Responses API streaming and return the relevant links.")},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Search the OpenAI docs for Responses API streaming and return the relevant links.")
.addTool(
Tool.Mcp.builder()
.serverLabel("openai_docs")
.serverDescription("Search and read the public OpenAI documentation.")
.serverUrl("https://developers.openai.com/mcp")
.requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
.build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
ResponseTool.CreateMcpTool(
serverLabel: "openai_docs",
serverUri: new Uri("https://developers.openai.com/mcp"),
toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
)
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19require "openai"
openai = OpenAI::Client.new
response = openai.responses.create(
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "never"
}
],
input: "Search the OpenAI docs for Responses API streaming and return the relevant links."
)
puts(response.output_text)
使用 Responses API 時,請只連線至你信任的遠端 MCP 伺服器。惡意伺服器可能從任何進入模型上下文的內容中竊取敏感資料。使用此工具前,請詳閱下方的風險與安全一節。
API 會在模型回應的 output 陣列中傳回新項目。如果模型決定使用 MCP 伺服器,API 會先向伺服器要求列出可用工具,並建立 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 伺服器提供數十項工具。讓模型存取大量工具可能會提高成本並增加延遲。如果你只需要 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-astra",
"tools": [
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never",
"allowed_tools": ["search_openai_docs"]
}
],
"input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import OpenAI from "openai";
const client = new OpenAI();
const resp = await client.responses.create({
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "never",
allowed_tools: ["search_openai_docs"],
},
],
input:
"Search the OpenAI docs for Responses API streaming and return the relevant links.",
});
console.log(resp.output_text);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never",
"allowed_tools": ["search_openai_docs"],
}
],
input="Search the OpenAI docs for Responses API streaming and return the relevant links.",
)
print(resp.output_text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfMcp("openai_docs")
tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}
tool.OfMcp.AllowedTools = responses.ToolMcpAllowedToolsUnionParam{OfMcpAllowedTools: []string{"search_openai_docs"}}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Search the OpenAI docs for Responses API streaming and return the relevant links.")},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;
import java.util.List;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Search the OpenAI docs for Responses API streaming and return the relevant links.")
.addTool(
Tool.Mcp.builder()
.serverLabel("openai_docs")
.serverDescription("Search and read the public OpenAI documentation.")
.serverUrl("https://developers.openai.com/mcp")
.requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
.allowedToolsOfMcp(List.of("search_openai_docs"))
.build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
ResponseTool.CreateMcpTool(
serverLabel: "openai_docs",
serverUri: new Uri("https://developers.openai.com/mcp"),
allowedTools: new McpToolFilter() { ToolNames = { "search_openai_docs" } },
toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
)
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20require "openai"
client = OpenAI::Client.new
response = client.responses.create(
model: "gpt-6-astra",
input: "Search the OpenAI docs for Responses API streaming and return the relevant links.",
tools: [
{
type: :mcp,
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: :never,
allowed_tools: ["search_openai_docs"]
}
]
)
puts(response.output_text)
模型取得工具定義後,可能會根據上下文決定呼叫其中的工具。當模型決定呼叫 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 規格中的錯誤處理說明。
根據預設,OpenAI 會先要求你核准,才會與連接器或遠端 MCP 伺服器分享任何資料。核准程序讓你能查看並控制傳送至 MCP 伺服器的資料。強烈建議你仔細審查與遠端 MCP 伺服器分享的所有資料,也可以將這些資料寫入記錄。若要試用核准流程,請執行快速入門範例,並將 require_approval 設為 "always",取代原本的 "never"。要求核准 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-astra",
"tools": [
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "always"
}
],
"previous_response_id": "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
"input": [{
"type": "mcp_approval_response",
"approve": true,
"approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa"
}]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import OpenAI from "openai";
const client = new OpenAI();
const resp = await client.responses.create({
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "always",
},
],
previous_response_id: "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
input: [
{
type: "mcp_approval_response",
approve: true,
approval_request_id:
"mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
},
],
});
console.log(resp.output_text);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "always",
}
],
previous_response_id="resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
input=[
{
"type": "mcp_approval_response",
"approve": True,
"approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
}
],
)
print(resp.output_text)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfMcp("openai_docs")
tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("always")}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
PreviousResponseID: openai.String("resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa"),
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
responses.ResponseInputItemParamOfMcpApprovalResponse("mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa", true),
}},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.Tool;
import java.util.List;
String responseId = "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa";
String approvalRequestId = "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
ResponseCreateParams.Input.ofResponse(
List.of(
ResponseInputItem.ofMcpApprovalResponse(
ResponseInputItem.McpApprovalResponse.builder()
.approvalRequestId(approvalRequestId)
.approve(true)
.build()))))
.previousResponseId(responseId)
.addTool(
Tool.Mcp.builder()
.serverLabel("openai_docs")
.serverDescription("Search and read the public OpenAI documentation.")
.serverUrl("https://developers.openai.com/mcp")
.requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.ALWAYS)
.build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new()
{
Model = "gpt-6-astra",
ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
ParallelToolCallsEnabled = false
};
options.Tools.Add(
ResponseTool.CreateMcpTool(
serverLabel: "openai_docs",
serverUri: new Uri("https://developers.openai.com/mcp"),
allowedTools: new McpToolFilter { ToolNames = { "search_openai_docs" } },
toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.AlwaysRequireApproval
)
);
// Step 1: Create a response that requests tool-call approval.
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));
ResponseResult response1 = await client.CreateResponseAsync(options);
McpToolCallApprovalRequestItem approvalRequest =
response1.OutputItems.OfType<McpToolCallApprovalRequestItem>().Single();
// Step 2: Approve the tool call and get the final response.
options.PreviousResponseId = response1.Id;
options.ToolChoice = ResponseToolChoice.CreateNoneChoice();
options.InputItems.Clear();
options.InputItems.Add(
ResponseItem.CreateMcpApprovalResponseItem(approvalRequest.Id, approved: true)
);
ResponseResult response2 = await client.CreateResponseAsync(options);
Console.WriteLine(response2.GetOutputText());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25require "openai"
client = OpenAI::Client.new
response = client.responses.create(
model: "gpt-6-astra",
previous_response_id: "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
input: [
{
type: :mcp_approval_response,
approval_request_id: "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
approve: true
}
],
tools: [
{
type: :mcp,
server_label: "openai_docs",
server_url: "https://developers.openai.com/mcp",
server_description: "Search and read the public OpenAI documentation.",
require_approval: :always
}
]
)
puts(response.output_text)
這裡使用 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-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)
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-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)
為避免敏感權杖外洩,Responses API 不會儲存你在 authorization 欄位中提供的值。建立的 Response 物件也不會顯示這個值。因此,每次透過 Responses API 發出建立回應的請求時,都必須傳送 authorization 的值。
connector_id 在 2026 年 9 月 1 日之後推出的模型中已棄用。請使用 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:以授權碼交換權杖。這個步驟會產生存取權杖,供你在 API 請求中透過 Google 日曆連接器存取日曆活動:
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_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 檔案下載網址取得內容 | 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)系統中查找某位客戶,並將該客戶的電子郵件地址加入網址。即使 CRM 工具只有唯讀權限,只要存取該網址,客戶的電子郵件地址就會外洩。
若要比對公司對外發布的公告與非公開的 CRM 紀錄,請在第一個請求中只啟用網頁搜尋,蒐集公開的事實。接著,將其中與比對有關的事實傳入第二個請求,並限制這個請求只能使用內部 CRM 搜尋工具。這樣就能避免客戶紀錄出現在網頁搜尋的查詢內容或網址中。
請適當設定 require_approval 和 allowed_tools 參數,確保所有敏感操作都必須經過核准流程。
向工具呼叫輸出中的網址發出請求,或嵌入輸出中的圖片網址,都可能有風險。無論輸出來自連接器還是遠端 MCP 伺服器,在應用程式的程式碼中嵌入或使用這些網址前,請先確認你信任提供網址的網域和服務。
請選擇由服務供應商自行託管的官方伺服器。例如,建議連線至 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 伺服器的資料適用該服務的資料保留與資料駐留政策。
舉例來說,如果你的組織使用歐洲資料駐留,OpenAI 只會在歐洲境內對客戶內容執行推論及儲存。這項限制適用到通訊內容或資料傳送至 MCP 伺服器為止。你有責任確認 MCP 伺服器也符合你的所有零資料保留或資料駐留要求。如需進一步瞭解零資料保留與資料駐留,請參閱資料使用指南。
| API 支援情況 | 速率限制 | 備註 |
|---|
| Build
1000 RPM Launch 與 Grow
2000 RPM | 價格
零資料保留與資料駐留 |