如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

MCP 伺服器

讓模型連線至遠端 MCP 伺服器,或透過安全 MCP 通道連線至本機伺服器。

除了透過函式呼叫提供工具給模型,你也可以使用遠端 MCP 伺服器或安全 MCP 通道擴充模型的能力。有了這些工具,模型就能在回應使用者的提示詞時,視需要連線至外部服務並操作這些服務。身為開發人員,你可以自動允許這些工具呼叫,也可以要求呼叫前必須先取得你的明確核准。

  • 遠端 MCP 伺服器可以是公用網際網路上任何實作模型上下文協定(MCP)並支援遠端連線的伺服器。

  • 安全 MCP 通道可連線至本機或私有 MCP 伺服器,無須將伺服器開放至公用網際網路。

本指南說明如何在 Responses API 中使用 MCP 工具。現有模型仍支援內建連接器。如需瞭解棄用政策並查看相容性範例,請參閱舊版連接器。如果你使用 Agents API 工作階段,請參閱 MCP 連線,瞭解如何從受管理的服務或你的沙盒建立連線。

安全 MCP 通道

如果你的 MCP 伺服器是私有伺服器、部署在地端,或位於防火牆後方,可以使用安全 MCP 通道將伺服器連線至支援此功能的 OpenAI 產品,無須將伺服器開放至公用網際網路。請從 openai/tunnel-client 下載最新公開版本。

快速入門

使用 mcp 工具類型即可在 Responses API 中連線至 MCP 伺服器。若要連線至遠端 MCP 伺服器,請設定 server_url。若要連線至本機 MCP 伺服器,請使用 tunnel_id,透過安全 MCP 通道建立連線。視伺服器而定,你可能還需要在 authorization 參數中提供 OAuth 存取權杖。

以下範例使用公開的 OpenAI 文件 MCP 伺服器,查找如何以串流方式取得 Responses API 輸出的文件。此伺服器提供唯讀的文件工具,無須驗證身分。範例查詢的是公開文件,因此略過工具呼叫的核准程序。分享敏感資料時,請啟用核准程序。

在 Responses API 中使用遠端 MCP 伺服器
curl 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."
  }'

使用 Responses API 時,請只連線至你信任的遠端 MCP 伺服器。惡意伺服器可能從任何進入模型上下文的內容中竊取敏感資料。使用此工具前,請詳閱下方的風險與安全一節。

API 會在模型回應的 output 陣列中傳回新項目。如果模型決定使用 MCP 伺服器,API 會先向伺服器要求列出可用工具,並建立 mcp_list_tools 輸出項目。以下輸出範例僅列出搜尋工具,並簡化了工具說明。伺服器也提供其他文件工具。

{
  "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 工具的內容,以及工具傳回的輸出。

{
  "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 工具的流程。

步驟 1:列出可用工具

在 tools 參數中指定遠端 MCP 伺服器後,API 會嘗試向該伺服器取得工具清單。Responses API 可搭配支援 Streamable HTTP 或 HTTP/SSE 傳輸協定的遠端 MCP 伺服器使用。

成功取得工具清單後,模型回應的輸出中會出現新的 mcp_list_tools 項目。此物件的 tools 屬性會列出成功匯入的工具。以下範例節錄僅列出搜尋工具,並簡化了工具說明。

{
  "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 來查找文件連結。

限制可使用的工具
curl 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."
  }'

步驟 2:呼叫工具

模型取得工具定義後,可能會根據上下文決定呼叫其中的工具。當模型決定呼叫 MCP 工具時,API 會向遠端 MCP 伺服器發出請求來呼叫該工具,並將工具的輸出加入模型的上下文。這會建立一個 mcp_call 項目。為求簡潔,以下輸出範例省略了搜尋結果的中繼資料:

{
  "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 項目,如下例所示:

{
  "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。每次核准僅適用於一次工具呼叫,後續的核准要求也應以相同方式處理。

核准 API 請求中的工具呼叫
curl 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"
    }]
  }'

這裡使用 previous_response_id 參數,將新的 Response 與先前產生核准要求的 Response 串接起來。你也可以將一個回應的輸出作為下一個回應的輸入,以便更精確地控制哪些內容會進入模型的上下文。

如果你確信遠端 MCP 伺服器值得信任,可以選擇略過核准程序以降低延遲。如以下範例所示,你可以將 MCP 工具的 require_approval 參數設為一個物件,僅列出要略過核准的工具。也可以將參數設為 'never',略過該遠端 MCP 伺服器上所有工具的核准程序。

指定一律無須核准的工具
curl 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?"
  }'

身分驗證

OpenAI 文件 MCP 伺服器無須驗證身分。其他 MCP 伺服器可能需要身分驗證,最常見的方式是使用 OAuth 存取權杖。請在 MCP 工具的 authorization 欄位中提供此權杖:

使用 Stripe MCP 工具
curl 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"
      }
    ]
  }'

為避免敏感權杖外洩,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 參數中提供此權杖。

搭配 GPT-5.2 使用舊版連接器
curl 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."
  }'

可用的連接器

  • 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 日曆連接器存取日曆活動:

使用 Google 日曆連接器
curl 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?"
  }'

透過連接器呼叫 MCP 工具時,輸出格式與透過遠端 MCP 伺服器呼叫工具時相同,都使用 mcp_call 輸出項目類型。在此範例中,傳給連接器的引數與連接器傳回的回應都是 JSON 字串:

{
  "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 權杖的授權範圍。展開下列表格,即可查看連線至各應用程式時可使用的工具。

延後載入 MCP 伺服器的工具

如果你使用工具搜尋,可以等到模型判定需要某個函式時,再載入 MCP 伺服器提供的該函式。若要啟用此功能,請在 MCP 伺服器的工具定義中設定 defer_loading: true。

延後載入時,模型仍可根據 MCP 伺服器的標籤和說明,判斷何時要在該伺服器上搜尋工具,但只會在需要時才載入個別函式定義。這有助於減少整體 Token 用量,對於提供大量函式的 MCP 伺服器尤其有用。

{
    "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 工具呼叫與輸出中的網址

向工具呼叫輸出中的網址發出請求,或嵌入輸出中的圖片網址,都可能有風險。無論輸出來自連接器還是遠端 MCP 伺服器,在應用程式的程式碼中嵌入或使用這些網址前,請先確認你信任提供網址的網域和服務。

連線至受信任的伺服器

請選擇由服務供應商自行託管的官方伺服器。例如,建議連線至 Stripe 在 mcp.stripe.com 託管的伺服器,避免使用第三方託管的 Stripe MCP 伺服器。目前官方遠端 MCP 伺服器數量有限,你可能會考慮使用其他組織託管的 MCP 伺服器。這些組織並非原服務的營運者,而是透過你的 API 代為轉送請求。如果必須這麼做,請特別審慎地查核這些「彙整服務供應商」,並仔細審查它們如何使用你的資料。

記錄並審查與第三方 MCP 伺服器分享的資料

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

價格
零資料保留與資料駐留