驗證使用者身分
許多外掛程式的 MCP 伺服器都能以唯讀、匿名模式運作,但只要提供特定客戶的資料或允許寫入操作,就應驗證使用者身分。
已發布的外掛程式可在 ChatGPT 和 Codex 中執行。兩項產品都遵循相同的 MCP 授權協定。如果回呼、中繼資料文件或帳戶連結介面因產品而異,本指南會說明 ChatGPT 用戶端的具體做法。
如果需要連接既有的伺服器端應用程式,或讓使用者彼此共用資料,你可以整合自己的授權伺服器。
使用 OAuth 2.1 自訂身分驗證
如果 MCP 伺服器需要身分驗證,你應實作符合 MCP 授權規格的 OAuth 2.1 流程。
元件
- 資源伺服器: 也就是你的 MCP 伺服器,負責提供工具,並驗證每個請求的存取權杖。
- 授權伺服器: 由你的身分提供者提供,或由你自行實作,負責核發權杖並發布探索中繼資料。
- 用戶端: 代表使用者執行操作的 OpenAI 主機,例如 ChatGPT 或 Codex。受支援的用戶端可使用用戶端 ID 中繼資料文件(CIMD)、動態用戶端註冊(DCR)、預先定義的 OAuth 用戶端,以及 PKCE。
MCP 授權規格的要求
- 在 MCP 伺服器上提供受保護資源的中繼資料
- 透過授權伺服器發布 OAuth 中繼資料
- 在整個 OAuth 流程中傳遞相同的
resource參數值 - 選擇 OpenAI 主機識別或註冊其 OAuth 用戶端的方式:CIMD、DCR 或預先定義的 OAuth 用戶端
- 公布授權伺服器的權杖端點接受哪些身分驗證方法
以下逐項說明如何滿足這些要求。
在 MCP 伺服器上提供受保護資源的中繼資料
- 你需要提供 HTTPS 端點,例如
GET https://your-mcp.example.com/.well-known/oauth-protected-resource,或在WWW-Authenticate標頭中公布相同的 URL,並將該標頭包含在401 Unauthorized回應中。這樣 ChatGPT 就知道該去哪裡取得中繼資料。 - 該端點會傳回一份 JSON 文件,說明資源伺服器及其可用的授權伺服器:
{
"resource": "https://your-mcp.example.com",
"authorization_servers": ["https://auth.yourcompany.com"],
"scopes_supported": ["files:read", "files:write"],
"resource_documentation": "https://yourcompany.com/docs/mcp"
}
- 請填寫下列必要欄位,並視需要加入選用欄位:
resource:MCP 伺服器的標準 HTTPS 識別碼。在 OAuth 流程中,ChatGPT 會將這個值原封不動地放入resource查詢參數。authorization_servers:一或多個指向身分提供者的簽發者基底 URL。ChatGPT 會依序嘗試這些 URL,以尋找 OAuth 中繼資料。scopes_supported:選用的授權範圍清單,可協助 ChatGPT 向使用者說明即將要求哪些權限。- 你也可以加入 RFC 9728 定義的選用欄位,例如
resource_documentation、resource_policy_uri或resource_tos_uri,讓用戶端和管理員更容易瞭解你的設定。
如果請求未通過身分驗證而遭封鎖,請傳回如下的驗證挑戰:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-mcp.example.com/.well-known/oauth-protected-resource",
scope="files:read"
只要有這個標頭,即使 ChatGPT 先前不知道中繼資料的 URL,也能找到它。
透過授權伺服器發布 OAuth 中繼資料
- 身分提供者必須提供下列其中一份探索文件,讓 ChatGPT 能從標準位置讀取其設定:
- 在
https://auth.yourcompany.com/.well-known/oauth-authorization-server提供 OAuth 2.0 中繼資料 - 在
https://auth.yourcompany.com/.well-known/openid-configuration提供 OpenID Connect 中繼資料
- 在
- 這兩種文件都會告訴 OpenAI 主機該將使用者導向何處、如何用授權碼交換權杖,以及如何表明用戶端身分。典型的回應如下:
{
"issuer": "https://auth.yourcompany.com",
"authorization_response_iss_parameter_supported": true,
"authorization_endpoint": "https://auth.yourcompany.com/oauth2/v1/authorize",
"token_endpoint": "https://auth.yourcompany.com/oauth2/v1/token",
"client_id_metadata_document_supported": true,
"token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
"registration_endpoint": "https://auth.yourcompany.com/oauth2/v1/register",
"code_challenge_methods_supported": ["S256"],
"scopes_supported": ["files:read", "files:write"]
}
- 下列欄位必須設定正確:
issuer:授權伺服器的標準識別碼。受保護資源中繼資料的authorization_servers清單必須使用完全相同的值。authorization_response_iss_parameter_supported:若要設為true,授權伺服器就必須在每個授權回應(包括錯誤回應)中傳回iss參數。authorization_endpoint、token_endpoint:ChatGPT 執行完整 OAuth 授權碼與 PKCE 流程所需的 URL。client_id_metadata_document_supported:若要讓 ChatGPT 使用 CIMD 註冊用戶端,請設為true。ChatGPT 會優先使用 CIMD,但如果 CIMD 和 DCR 都可用,外掛程式開發者可以選擇 DCR。token_endpoint_auth_methods_supported:列出授權伺服器的權杖端點接受的身分驗證方法。此設定適用於 CIMD、DCR 和預先定義的 OAuth 用戶端。使用 CIMD 時,ChatGPT 支援以none讓公開用戶端交換權杖,也支援以private_key_jwt使用已簽署的用戶端斷言交換權杖。其他 OAuth 用戶端常用的方法包括none、client_secret_post或client_secret_basic。registration_endpoint:如果支援動態用戶端註冊(DCR),請加入此欄位。ChatGPT 即可為該 MCP 伺服器連線建立專用的client_id,並在後續使用同一個 ID。code_challenge_methods_supported:必須包含S256。如果授權伺服器的中繼資料省略此欄位,或未依規定宣告支援S256,對應的 MCP 伺服器就不受支援。詳見 MCP 授權規格。- 選用欄位依循 RFC 8414 與 OpenID 探索規格。可視需要加入有助於管理員設定政策的欄位。
OIDC 授權範圍
- 如果身分提供者將 OIDC 授權範圍(例如
openid、email、profile)列在scopes_supported欄位中,並透過.well-known/oauth-authorization-server或.well-known/openid-configuration文件公布,ChatGPT 預設會在 OAuth 流程中要求這些範圍。 - 有些身分提供者預設不會啟用其公布的 OIDC 授權範圍。請檢查提供者的設定,確認已為 OAuth 用戶端啟用每個公布的範圍,無論用戶端使用 CIMD、由人工建立,或透過 DCR 建立。
支援工作區網域限制
ChatGPT Enterprise 工作區可以驗證電子郵件網域的所有權。透過 OAuth 連結的外掛程式若提供使用者已驗證的電子郵件地址,ChatGPT 就能根據其網域,防止使用者以該企業身分在個人工作區或組織外的其他工作區連結外掛程式。
若要支援這項保護措施,請將授權伺服器設定為:
- 發布 OpenID Connect 探索中繼資料。
- 公布並啟用
openid和email授權範圍。 - 公布 UserInfo 端點,並讓該端點傳回使用者的
email宣告及email_verified: true。
你也可以在 OAuth 流程的 ID 權杖中傳回這些宣告,但要支援工作區網域限制,仍須提供 UserInfo 端點。
Enterprise 工作區也必須驗證自己的網域。授權伺服器負責提供使用者身分,讓 ChatGPT 與工作區設定中已驗證的網域比對。驗證工作區是否擁有該網域並非授權伺服器的職責。
在重新授權時保留登入狀態
當 ChatGPT 為既有連結重新取得授權時(例如要求額外的 OAuth 授權範圍),可能會透過標準的 id_token_hint 參數,在授權請求中附上先前的 OIDC ID 權杖。若要讓使用者無須重新登入即可授予額外範圍,請將授權伺服器設定為在初次 OAuth 流程中核發 ID 權杖,並在授權時採用 id_token_hint 提供的提示。
這項最佳化是選用的。即使沒有可用的 ID 權杖,或授權伺服器不使用此提示,仍可重新授權。
識別簽發者以保護回呼
OpenAI 主機使用 RFC 9207 的簽發者識別機制,保護 OAuth 回呼免於授權伺服器混淆攻擊。若要讓 ChatGPT 和 Codex 在建立符合條件的 OAuth 用戶端時使用固定的重新導向 URI,請完成下列設定:
- 將
authorization_response_iss_parameter_supported: true加入授權伺服器中繼資料。 - 在中繼資料的
issuer欄位和受保護資源中繼資料的authorization_servers清單中,使用完全相同的簽發者識別碼。 - 在每個成功或錯誤的授權回應中傳回
iss。其值必須與中繼資料中的issuer完全相同。用戶端會逐字比對,不會將結尾斜線、路徑、連接埠或大小寫正規化。
ChatGPT 和 Codex 會在將使用者重新導向之前,記錄所選中繼資料中的 issuer,並在使用授權碼交換權杖之前檢查傳回的 iss。如果伺服器宣告支援簽發者識別,卻未傳回 iss 或傳回的值不符,ChatGPT 和 Codex 就會拒絕該回應。這些要求依循 MCP 授權回應驗證規則。
重新導向 URL
將 MCP 伺服器管理頁面顯示的正式環境重新導向 URI 原封不動地複製到授權伺服器的允許清單中。
- 如果授權伺服器不符合上述簽發者識別要求,ChatGPT 會使用回呼 ID 專屬的重新導向 URI
https://chatgpt.com/connector/oauth/{callback_id}。 - 如果授權伺服器符合這些要求,ChatGPT 會使用固定的重新導向 URI
https://chatgpt.com/connector_platform_oauth_redirect。
在 ChatGPT 推出回呼 ID 專屬的重新導向機制之前發布的 MCP 伺服器,也會繼續使用固定的重新導向 URI。
在整個 OAuth 流程中傳遞相同的 resource 參數值
- ChatGPT 會在授權請求和權杖請求中都加上
resource=https%3A%2F%2Fyour-mcp.example.com,將權杖與上方的受保護資源中繼資料建立關聯。 - 將授權伺服器設定為把該值複製到存取權杖中(通常放在
aud宣告中),讓 MCP 伺服器能驗證該權杖是否專為自己核發。 - 如果收到的權杖缺少預期的適用對象或授權範圍,請拒絕該權杖,並透過
WWW-Authenticate驗證挑戰,要求 ChatGPT 使用正確的參數重新授權。
支援授權碼流程
- ChatGPT 作為 MCP 用戶端,會在授權碼流程中搭配 PKCE,採用
S256授權碼挑戰方法,防止攻擊者重放攔截到的授權碼。 - 授權伺服器必須公布
code_challenge_methods_supported並在其中列出S256,讓用戶端能透過中繼資料確認伺服器支援 PKCE。
OAuth 流程
實作上述 MCP 授權規格後,OAuth 流程如下:
- ChatGPT 向 MCP 伺服器查詢受保護資源的中繼資料。

- ChatGPT 表明自己的 OAuth 用戶端身分。當 MCP 伺服器使用 CIMD 時,ChatGPT 會略過動態用戶端註冊,改以 CIMD 文件 URL 作為
client_id傳送。如果授權伺服器符合上述簽發者識別要求,ChatGPT 會使用固定的https://chatgpt.com/oauth/client.json。對於其他伺服器,則使用回呼 ID 專屬的https://chatgpt.com/oauth/{callback_id}/client.json。MCP 伺服器管理頁面會顯示該連線的回呼模式所對應的用戶端中繼資料文件及確切的重新導向 URI。當 MCP 伺服器使用 DCR 時,ChatGPT 會針對該 MCP 伺服器連線呼叫一次授權伺服器的registration_endpoint,取得產生的client_id,並在該連線後續的操作中沿用這個用戶端。
使用 CIMD 時沒有用戶端註冊步驟。下圖顯示使用 DCR 時的流程:

- 使用者第一次叫用工具時,ChatGPT 用戶端會啟動搭配 PKCE 的 OAuth 授權碼流程。使用者完成身分驗證,並同意授予所要求的範圍。

- ChatGPT 使用授權碼交換存取權杖,並將權杖附加到後續 MCP 請求中(
Authorization: Bearer <token>)。

- 每次收到請求,伺服器都會先驗證權杖(簽發者、適用對象、到期時間及授權範圍),再執行工具。
用戶端註冊
如果授權伺服器支援用戶端 ID 中繼資料文件(CIMD),且外掛程式開發者選用此方法,請優先使用 CIMD 註冊用戶端。採用 CIMD 時,ChatGPT 會使用 HTTPS 中繼資料文件的 URL 作為 client_id。授權伺服器會擷取該文件,驗證其中公布的用戶端中繼資料和重新導向資源識別碼,並以該 URL 作為 ChatGPT 的固定用戶端識別碼。
如果支援 CIMD,請在授權伺服器的中繼資料中設定 client_id_metadata_document_supported: true。如此一來,ChatGPT 就能對選用 CIMD 的 MCP 伺服器使用同一個固定的用戶端識別碼,讓授權伺服器據此套用重新導向 URI 允許清單、速率限制和其他政策。
ChatGPT 正逐步採用 MCP SEP-3149 提議的 CIMD 變更。其正式環境的 CIMD 文件會以 token_endpoint_auth_methods_supported 陣列列出 ChatGPT 可使用的方法,排列順序不代表優先順序。在過渡期間,文件也會透過舊版單數欄位 token_endpoint_auth_method 指定偏好的方法:
{
"token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
"token_endpoint_auth_method": "private_key_jwt"
}
複數欄位在兩份文件中各有不同的意義:授權伺服器中繼資料列出權杖端點接受的方法,而 ChatGPT 的 CIMD 文件列出 ChatGPT 能使用的方法。ChatGPT 會從兩者共同支援的方法中選擇一種。如果雙方都支援舊版單數欄位指定的偏好方法,ChatGPT 就會採用該方法,以相容於仍將該欄位視為強制要求的授權伺服器。否則,ChatGPT 可使用雙方共同支援的其他方法。
讀取 CIMD 複數欄位的授權伺服器應接受雙方共同支援的任何方法,除非本機安全性政策禁止該用戶端使用其中某種方法。伺服器必須拒絕雙方未共同支援的方法。client_id URL 保持固定,不會透過查詢參數選擇特定方法專用的文件。
支援的方法如下:
none:如果權杖端點支援透過 PKCE 使用授權碼交換權杖,且無須驗證用戶端身分,請使用此公開用戶端流程。ChatGPT 不會為每個用戶端儲存專屬密鑰。private_key_jwt:如果權杖端點要求驗證用戶端身分,請使用此流程,以簽署過的用戶端斷言進行驗證。ChatGPT 會在 CIMD 中繼資料中公布可公開存取的 JWKS URL。JWKS 位於與中繼資料同源的/oauth/jwks.json。ChatGPT 會在伺服器端使用受管理的私密金鑰簽署權杖請求,並附上kid。授權伺服器則依據公開的 JWKS 驗證斷言。
ChatGPT 仍支援 DCR。如果中繼資料包含 registration_endpoint,當外掛程式開發者選擇 DCR 或無法使用 CIMD 時,ChatGPT 就能動態註冊。ChatGPT 會為每個 MCP 伺服器連線執行一次 DCR,之後保留並沿用該連線已註冊的 OAuth 用戶端。當獨立連線很多時,DCR 仍可能產生大量已註冊的用戶端,因此大規模部署時,CIMD 通常較容易管理。
在 MCP 伺服器連線使用期間,請確保已註冊的 OAuth 用戶端及其用戶端密鑰持續有效。如果授權伺服器讓其中任一項憑證到期,或將其刪除或取代,使用者與審查人員在連線時可能會收到 invalid_client 錯誤。存取權杖和更新權杖仍可正常到期或輪替。
識別用戶端
MCP 伺服器如何確認請求確實來自 ChatGPT?ChatGPT 連接 MCP 伺服器時會出示由 OpenAI 管理的用戶端憑證,因此你可以在傳輸層使用 mTLS 驗證用戶端。你也可以將 ChatGPT 公布的對外連線 IP 範圍加入允許清單。ChatGPT 不支援機器對機器的 OAuth 授權方式,例如用戶端認證資訊授權、服務帳戶或 JWT 持有者斷言,也無法出示自訂 API 金鑰或客戶提供的 mTLS 憑證。
CIMD 透過 HTTPS 提供穩定的 ChatGPT 身分宣告,讓授權伺服器更可靠地識別用戶端。使用 private_key_jwt 時,請依據 CIMD 中繼資料公布的公開 JWKS,驗證 ChatGPT 傳送至權杖端點的用戶端斷言。
雙向 TLS(mTLS)
ChatGPT 現在會在與 MCP 伺服器建立 TLS 連線時出示由 OpenAI 管理的用戶端憑證。如果你的應用程式會驗證用戶端憑證,請將其設定為信任下列 OpenAI 憑證鏈。
與 MCP 伺服器建立 TLS 連線時,請依下列方式驗證用戶端憑證:
- 確認用戶端已出示終端憑證,且其憑證鏈可追溯至 OpenAI Connectors mTLS 中繼 CA。
- 確認終端憑證可用於用戶端身分驗證。
- 確認終端憑證 SAN 中的
dnsName為mtls.prod.connectors.openai.com。 - 避免固定使用特定終端憑證的指紋。OpenAI 可能會輪替終端憑證,但仍使用已公布的 CA 憑證鏈。
請使用 mTLS 驗證 ChatGPT 作為 MCP 用戶端的身分,並繼續使用 OAuth 2.1 驗證終端使用者身分及授予工具存取權。
選擇身分提供者
大多數 OAuth 2.1 身分提供者只要提供探索文件、支援 CIMD 搭配 none 或 private_key_jwt、在需要時支援 DCR,並將 resource 參數值寫入核發的權杖,就能符合 MCP 授權要求。請優先選擇支援 CIMD 用戶端註冊的提供者。
我們強烈建議使用成熟的身分提供者,避免從零開始自行實作身分驗證。
以下是幾個常見身分提供者的設定指南。
Auth0
Auth0 提供中繼資料探索、CIMD 註冊、API 安全性,以及第一方與第三方工具呼叫所需的權杖交換機制,讓 MCP 用戶端能安全地連接 MCP 伺服器。
託管式提供者範例(Stytch)
實作權杖驗證
OAuth 流程完成後,ChatGPT 會將收到的存取權杖直接附加到後續 MCP 請求中(Authorization: Bearer …)。MCP 伺服器收到請求時,必須先將權杖視為不受信任,並自行完成資源伺服器的所有檢查,包括驗證簽章、比對簽發者與適用對象、檢查有效期限、評估重放風險,以及強制執行授權範圍限制。這些檢查由你負責,ChatGPT 不會代為執行。
實作時應執行以下步驟:
- 擷取授權伺服器公布的簽署金鑰(通常透過 JWKS 提供),並驗證權杖的簽章和
iss。 - 拒絕已到期或尚未生效的權杖(
exp/nbf)。 - 確認權杖是為你的伺服器核發(檢查
aud或resource宣告),且包含你指定為必要的授權範圍。 - 執行伺服器特有的政策檢查,再依結果將確認的身分加入請求上下文,或傳回
401並附上WWW-Authenticate驗證挑戰。
如果驗證失敗,請傳回 401 Unauthorized,並附上指向受保護資源中繼資料的 WWW-Authenticate 標頭,讓用戶端知道需要重新執行 OAuth 流程。
SDK 提供的權杖驗證功能
Python 和 TypeScript 的 MCP 軟體開發套件都提供輔助函式,無須從零開始實作整套驗證流程。
支援多個帳戶
多帳戶功能讓使用者將多個帳戶連結至同一個外掛程式,例如同時連結個人和工作帳戶。OpenAI 會使用所選連線中已通過驗證的憑證,將每次工具呼叫送往對應的帳戶。即使沒有個人資料工具,使用者也能連結多個帳戶。若要協助使用者區分連線,並在重新連線後辨識出同一份個人資料,請提供需要身分驗證的個人資料工具,傳回穩定的 ID 及有助辨識的顯示用中繼資料。
使用者如何使用多個帳戶
使用者可從外掛程式的設定頁面連結其他帳戶。模型可以使用所有已連結的帳戶,並在叫用工具時根據使用者的請求選擇一或多個相關帳戶。每次工具呼叫都會使用所選帳戶的憑證和權限。
改善帳戶識別
若要協助 OpenAI 辨識已連結的個人資料並顯示有助辨識的標籤,請採取以下做法:
- 提供需要身分驗證的個人資料工具,傳回不透明的 ID,用以唯一且持續地識別請求憑證所代表的個人資料。如此一來,OpenAI 就能在重新連線後辨識同一份個人資料,並將其與其他個人資料區分開來。即使欄位名稱為
id,其值仍須符合上述條件才能用於識別。 - 在 MCP 中繼資料中指定個人資料工具,讓 OpenAI 知道該呼叫哪個工具來取得已驗證身分的個人資料。
需要個人資料時,OpenAI 會在執行階段找出指定的工具,使用該連線的憑證呼叫它,並驗證回應後再使用其中的資料。即使沒有個人資料工具,使用者仍可連結帳戶,但帳戶標籤、帳戶識別或重複帳戶偵測可能較不可靠。如果宣告了個人資料工具,就必須傳回有效的身分資訊,否則可能導致帳戶無法連結。
定義穩定的個人資料識別碼
每份個人資料用來識別請求中已通過驗證的憑證所代表的身分。哪些個人資料可獨立連結,由你的服務決定。此協定並未規定服務應採用何種組織架構或授權模型。
請傳回不透明且在應用程式內唯一的個人資料 ID。更新權杖或重新連線後,同一份個人資料必須保留原有 ID,而不同的個人資料必須使用不同的 ID。OpenAI 會比對這些 ID,但不會解讀其內容。
如果提供者已有不可變更、不透明且能識別完整個人資料的 ID,請沿用它。否則,請為該個人資料指派一次不透明的 ID,儲存兩者的對應關係,並在後續請求中取回相同的 ID。內部關聯應保留在服務內,不要將姓名、電子郵件地址或組織關係編入傳回的 ID。
你的 id 必須符合下列條件:
- 必須是非空字串,且至少包含一個非空白字元。如果提供者的 ID 是數值,請將其序列化為字串。
- 同一份個人資料在更新權杖、重新連線或擴大授權範圍後,仍須使用相同的 ID。
- 可透過應用程式連結的不同個人資料,必須使用不同的 ID。
- 即使個人資料的電子郵件地址、姓名或顯示標籤變更,ID 也必須保持不變。
- 個人資料刪除後,不得將其 ID 重新指派給其他個人資料。
不要在每次登入、核發權杖、建立工作階段或呼叫工具時產生新的 ID。電子郵件地址和可編輯的名稱應放在顯示用中繼資料中。可能變更或重新指派的電子郵件地址,無法作為穩定的個人資料 ID。使用 Google OIDC 時,請採用穩定的 sub,而非電子郵件宣告。Google 的文件說明,電子郵件地址可能變更,但 sub 會保持不變,也絕不會指派給其他身分。詳見 Google 身分識別文件。
更新整合功能時,請保留既有的個人資料 ID。變更顯示名稱、取得新權杖或建立新連線,都不得讓同一份個人資料被識別為新的身分。
實作並宣告個人資料工具
提供需要身分驗證的唯讀工具,讓它接受空的引數物件並傳回目前的個人資料。工具可命名為 get_profile、whoami 或其他名稱。執行階段會依據工具的中繼資料,判斷它是否為個人資料工具。回應必須符合下列身分識別要求,OpenAI 才能正確使用它。
- 根據請求中已驗證的憑證判定身分。
- 將操作設為唯讀,並確保使用一般連線的權限即可執行。
- 只傳回一份個人資料,即目前請求的憑證所代表的個人資料。
- 不要要求呼叫端提供使用者 ID、電子郵件地址或指定要使用的帳戶。
- 身分驗證失敗時,請傳回適當的驗證錯誤,不要傳回替代用的 ID 或其他帳戶的個人資料。
個人資料回應必須符合以下 JSON 結構描述:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
},
"name": {
"type": "string",
"description": "Display name for the authenticated profile."
},
"email": {
"type": "string",
"description": "Email address for display; not used as the profile identity."
},
"nickname": {
"type": "string",
"description": "A useful label that helps users distinguish connected profiles."
}
},
"required": ["id"],
"additionalProperties": false
}
回應必須包含字串 id,其值不得為空或僅含空白字元。顯示欄位則為選用。工具的中繼資料告訴 OpenAI 從何處取得個人資料,而回應則識別目前憑證所代表的個人資料。
結構描述驗證會檢查回應是否具備處理個人資料所需的結構和欄位型別。服務還必須確保 ID 唯一且穩定,並確保憑證只能存取其對應的個人資料。光憑中繼資料或通過結構描述驗證,無法證明服務符合這些行為要求。
視可用資料加入 name、email 和/或 nickname,方便使用者區分不同的個人資料。無法取得的選用值請省略,不要捏造資料或加入無關的個人資訊。請將方便使用者辨識的說明放入 nickname,不要寫入 ID。
以 _meta["openai/profile"]: true 標記工具,並將個人資料回應的結構描述發布為工具的 outputSchema。此標記會告訴 OpenAI 哪個工具提供個人資料,但不會啟用這項功能,也不會授予使用資格。如果省略標記或其值為 false,表示並未透過此機制將工具指定為個人資料來源。字串、數值和 null 都不是有效的標記值。
{
"name": "get_profile",
"description": "Return the profile represented by this request's authenticated credentials. The opaque id is unique within this app and remains unchanged across token refresh, reconnection, and display-metadata changes.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
},
"name": {
"type": "string",
"description": "Display name for the authenticated profile."
},
"email": {
"type": "string",
"description": "Email address for display; not used as the profile identity."
},
"nickname": {
"type": "string",
"description": "A useful label that helps users distinguish connected profiles."
}
},
"required": ["id"],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "oauth2",
"scopes": []
}
],
"_meta": {
"openai/profile": true
}
}
如果存取個人資料需要特定 OAuth 授權範圍,請填入整合功能實際使用的範圍。宣告本身不會執行身分驗證,伺服器仍須驗證憑證並強制執行權限限制。請參閱實作權杖驗證與工具參考文件。
請在 structuredContent 中傳回個人資料,以便依據 outputSchema 進行驗證。為確保相容性,也請將同一份個人資料序列化為 JSON,放入文字內容項目中:
{
"content": [
{
"type": "text",
"text": "{\"id\":\"prf_8d7e4b19\",\"name\":\"Alex Chen\",\"email\":\"alex@example.com\",\"nickname\":\"Alex — Moonwaffle work\"}"
}
],
"structuredContent": {
"id": "prf_8d7e4b19",
"name": "Alex Chen",
"email": "alex@example.com",
"nickname": "Alex — Moonwaffle work"
},
"isError": false
}
請使用單一 JSON 物件,並將個人資料欄位放在最上層。
已經有個人資料工具了嗎? 請保留工具名稱,加入個人資料中繼資料宣告,並傳回標準格式的個人資料回應。如果既有回應的結構不同,可在伺服器端轉換格式,或提供一個符合結構描述的簡單包裝工具。所有應用程式採用標準整合方式時,都使用相同的宣告和回應結構。
具體範例:持久保存 Moonwaffle 個人資料
假設虛構的服務 Moonwaffle 允許 Alex 分別連結兩份個人資料。Moonwaffle 會為每份個人資料儲存不同的不透明 ID。伺服器根據請求的憑證找出其中一份已儲存的個人資料,再由個人資料工具傳回其既有 ID。
已儲存的個人資料範例。 標籤可以變更,但識別碼會保持不變:
Alex — Moonwaffle personal: prf_42a9c6e0
Alex — Moonwaffle work: prf_8d7e4b19
這些範例 ID 不包含個人資料標籤或內部關聯。每份個人資料的 ID 只需儲存一次,之後即使重新連線、更新權杖、變更電子郵件地址或顯示名稱,也會沿用原有 ID。
根據已驗證身分的個人資料建立回應。 這個 TypeScript 範例示範如何撰寫可與 MCP SDK 整合的處理函式。loadAuthenticatedProfile 是應用程式的整合程式碼,負責驗證請求憑證、強制執行其權限限制,並取回對應個人資料已儲存的 ID 和顯示用中繼資料。requestContext 來自伺服器的請求處理流程,並非模型提供的工具引數。
async function getProfile(requestContext: { token: string }) {
// Your auth/provider integration validates credentials and loads
// the existing profile. Auth failures use normal MCP auth handling.
const account = await loadAuthenticatedProfile(requestContext);
const id = account.profileId;
if (typeof id !== "string" || id.trim().length === 0) {
return {
isError: true,
content: [{ type: "text", text: "Profile identity unavailable." }],
};
}
// Return the persisted ID unchanged; do not generate an ID per call.
const profile = {
id,
...(typeof account.name === "string" ? { name: account.name } : {}),
...(typeof account.email === "string" ? { email: account.email } : {}),
...(typeof account.nickname === "string"
? { nickname: account.nickname }
: {}),
};
return {
isError: false,
structuredContent: profile,
content: [{ type: "text", text: JSON.stringify(profile) }],
};
}使用上述中繼資料宣告及輸入、輸出結構描述來註冊這個處理函式。對於代表相同身分的憑證,loadAuthenticatedProfile 必須找出同一份已儲存的個人資料,重新連線後也一樣。不得在每次取得 OAuth 授權或建立工作階段時產生新的個人資料 ID。所有其他工具也必須使用請求的憑證,強制執行同一份個人資料所對應的權限限制。
驗證身分識別行為:
| 測試 | 預期結果 |
|---|---|
| 對 Moonwaffle 的工作用個人資料重複呼叫工具 | 每次都傳回 prf_8d7e4b19 |
| 更新權杖、重新連線或擴大授權範圍後,存取同一份個人資料 | prf_8d7e4b19 |
| 變更電子郵件地址或顯示標籤後,存取同一份個人資料 | prf_8d7e4b19,標籤可以變更 |
| 存取 Moonwaffle 的私人個人資料 | prf_42a9c6e0,與工作用個人資料的 ID 不同 |
| 已儲存的個人資料 ID 遺失或為空白 | 傳回錯誤結果,不得捏造身分或改用其他個人資料 |
所有個人資料都必須符合這些身分識別要求,日後變更整合功能時也一樣。無論顯示用中繼資料、權杖內容或連線生命週期如何變化,都必須維持這項保證。
測試與推出
- 本機測試: 先使用會核發短效權杖的開發用租用戶,以便快速反覆測試。
- 內部試用: 身分驗證可正常運作後,先僅開放給受信任的測試人員,再擴大推出範圍。你可以針對特定工具或整個 MCP 伺服器要求使用者連結帳戶。
- 權杖輪替: 預先規劃如何處理權杖撤銷、更新及授權範圍變更。如果權杖遺失或已失效,伺服器應將請求視為未通過身分驗證,並傳回有助於排解問題的錯誤訊息。
- OAuth 偵錯: 推出前,請使用 MCP Inspector 的身分驗證設定,逐步執行 OAuth 流程,找出發生問題的環節。
完成身分驗證設定後,即可向 ChatGPT 和 Codex 使用者提供其專屬資料及寫入操作。
觸發身分驗證介面
只有當 MCP 伺服器表明可使用或必須使用 OAuth 時,ChatGPT 才會顯示 OAuth 帳戶連結介面。
要觸發個別工具的 OAuth 流程,必須同時提供中繼資料(securitySchemes 及資源中繼資料文件)以及帶有 _meta["mcp/www_authenticate"] 的執行階段錯誤。缺少其中任一項,ChatGPT 都不會顯示該工具的帳戶連結介面。
-
發布資源中繼資料。 MCP 伺服器必須在標準位置的 URL(例如
https://your-mcp.example.com/.well-known/oauth-protected-resource)提供其 OAuth 設定。 -
使用
securitySchemes說明每個工具的身分驗證政策。 為每個工具宣告securitySchemes,即可告訴 ChatGPT 哪些工具需要 OAuth,哪些可以匿名執行。即使整個伺服器採用相同政策,也請逐一宣告。如果只使用伺服器層級的預設值,日後就很難單獨調整各項工具的政策。目前支援兩種驗證方式。你可以同時列出兩者,表示身分驗證為選用:
noauth:工具可匿名呼叫,ChatGPT 可以立即執行。oauth2:工具需要 OAuth 2.0 存取權杖。請列出要向使用者要求的授權範圍,讓同意畫面正確顯示所需權限。
如果完全省略這個陣列,工具會繼承伺服器公布的預設設定。同時宣告
noauth和oauth2,表示 ChatGPT 可以先匿名呼叫工具,連結帳戶後即可使用需要權限的功能。無論向用戶端宣告何種驗證方式,伺服器仍須在每次叫用時驗證權杖、授權範圍及適用對象。TypeScript SDK 範例(公開工具,可選擇進行身分驗證)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; const server = new McpServer({ name: "auth-example", version: "1.0.0" }); server.registerTool( "search", { title: "Public Search", description: "Search public documents.", inputSchema: { q: z.string(), }, outputSchema: {}, _meta: { securitySchemes: [ { type: "noauth" }, { type: "oauth2", scopes: ["search.read"] }, ], }, }, async ({ q }) => { return { content: [{ type: "text", text: `Results for ${q}` }], structuredContent: {}, }; } );TypeScript SDK 範例(必須進行身分驗證)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; const server = new McpServer({ name: "auth-example", version: "1.0.0" }); server.registerTool( "create_doc", { title: "Create Document", description: "Make a new doc in your account.", inputSchema: { title: z.string(), }, outputSchema: {}, _meta: { securitySchemes: [{ type: "oauth2", scopes: ["docs.write"] }], }, }, async ({ title }) => { return { content: [{ type: "text", text: `Created doc: ${title}` }], structuredContent: {}, }; } ); -
在工具處理函式中檢查權杖,並傳回
_meta["mcp/www_authenticate"],讓 ChatGPT 在需要時顯示身分驗證介面。檢查權杖並驗證其簽發者、適用對象、有效期限及授權範圍。如果沒有有效的權杖,請傳回包含_meta["mcp/www_authenticate"]的錯誤結果,並確保其值同時包含error和error_description參數。完成步驟 1 和 2 後,這段WWW-Authenticate內容就會觸發該工具的 OAuth 介面。如果驗證挑戰要求重新授權,身分提供者可在此流程中保留使用者既有的登入狀態。範例
{ "jsonrpc": "2.0", "id": 4, "result": { "content": [ { "type": "text", "text": "Authentication required: no access token provided." } ], "_meta": { "mcp/www_authenticate": [ "'Bearer resource_metadata=\"https://your-mcp.example.com/.well-known/oauth-protected-resource\", error=\"insufficient_scope\", error_description=\"You need to login to continue\"'" ] }, "isError": true } }