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

模型上下文協定

將 ChatGPT 和 Codex 連接到你的工具與資訊來源。

模型上下文協定(MCP)讓 ChatGPT 和 Codex 能使用其他系統的工具與資訊。MCP 伺服器會說明有哪些工具可用,並處理工具收到的請求,例如查詢工單或擷取文件。

依照你的任務選擇做法:

範例:在團隊的客服系統中查詢工單。

外掛程式會將 MCP 連線封裝起來,供 ChatGPT 使用。外掛程式也可以包含技能,讓你重複使用同一套指示。如果你只需要指示,請參閱建立外掛程式。

使用 Plugin Creator 和工作站建立 MCP 外掛程式

使用 Plugin Creator 建立及編輯外掛程式,並透過工作站代管 MCP 伺服器。

開始之前

先查看外掛程式目錄。如果需要建立新的連線,請備妥系統的 API 文件,並確認可採用哪種已核准的連線方式。如需協助,請洽系統擁有者。

以下範例會建立一個客服工單查詢外掛程式。請將 [ticketing system] 替換成你的系統名稱。

你使用的是 ChatGPT Enterprise 嗎?

請工作區擁有者或管理員前往工作區設定 → 權限與角色,確認下列權限:

  • 使用外掛程式:可建立、編輯及使用外掛程式。編輯時還需要該外掛程式的編輯權限。
  • 工作站:需要此存取權才能建立及發布工作站。
  • 上傳外掛程式和使用 MCP 建立外掛程式:發布 MCP 外掛程式的工作站擁有者需要這兩項權限。

使用外掛程式權限預設為開啟,兩項 MCP 發布權限則預設為關閉。請參閱工作站存取權和外掛程式權限。

1. 建立外掛程式

在工作模式中開始新任務,選取 @Plugin Creator,並附上 API 文件。接著說明任務內容:

建立外掛程式
請根據隨附的 [ticketing system] API 文件建立客服工單查詢外掛程式,並在工作站上代管 MCP 伺服器。讓我可以依工單編號查詢狀態、負責人和最新進度。請設為唯讀,並告訴我建立連線需要準備什麼。

還在申請 API 存取權嗎?你可以請 Plugin Creator 先使用範例資料。

2. 連接你的系統

在同一段對話中,請 Plugin Creator 將伺服器連接到系統的 API,並引導你完成登入。請使用組織核准的驗證方式,切勿在對話中提供密碼、API 金鑰或其他機密資訊。

需要協助嗎?請將你與 Plugin Creator 的對話和 API 文件提供給系統擁有者或開發人員,讓他們協助設定存取權。

連線與代管詳情

工作站會處理 ChatGPT 與 MCP 伺服器之間的登入。伺服器仍需透過核准的方式連接到系統 API。伺服器能存取哪些記錄、執行哪些操作,取決於這項 API 連線。

如果使用其他主機,請先按照建立 MCP 伺服器的步驟操作,再連接並測試外掛程式。如需設定登入,請參閱驗證指南。

3. 發布並安裝

請 Plugin Creator 保留目前的存取設定,透過工作站發布伺服器,並提供外掛程式連結。要為工作站建立外掛程式,必須由工作站擁有者發布。如果你是編輯者,請擁有者完成這個步驟。

  1. 開啟外掛程式卡片,或前往外掛程式 → 個人 → 你建立的項目找到它。
  2. 依序選取安裝和連線,並完成必要的登入步驟。

4. 使用外掛程式

在工作模式中開始新任務,使用 @ 選取外掛程式,然後詢問 「123 號工單目前的狀態是什麼?」,並將編號換成系統中的實際工單編號。在同一段對話中,你可以搭配使用這個外掛程式的工具和其他外掛程式。

分享或編輯外掛程式

如果使用 Business 或 Enterprise 方案,你可以透過外掛程式的分享設定邀請團隊成員。你需要分享外掛程式權限。如果要將外掛程式列入工作區目錄,還需要將外掛程式發布至工作區權限。請參閱分享權限。

團隊成員需要有權存取外掛程式及其應用程式,且至少要有工作站的檢視權限。每位成員都要使用自己的帳戶安裝外掛程式並建立連線。可存取哪些記錄,取決於伺服器的 API 連線。

若要編輯這個由工作站代管的外掛程式,請回到你與 Plugin Creator 的對話,要求更新現有工作站,然後發布變更。若要編輯其他可編輯的外掛程式,請選取編輯外掛程式,開始與 Plugin Creator 對話。請參閱編輯現有外掛程式。

取代 GPT 自訂動作

顯示 GPT 遷移步驟

GPT 自訂動作不會隨遷移轉入外掛程式。請盡可能沿用現有 API,在新的工作站外掛程式中重建連線。

發布時,工作站會建立獨立的外掛程式,不會將連線加入已遷移的外掛程式。你可以在同一段對話中使用這兩個外掛程式。目前工作站外掛程式不支援編輯技能或參考檔案。

1. 請原本的 GPT 撰寫重建用的提示詞

開啟原本的 GPT 並輸入:

在原本的 GPT 中使用
請撰寫一段提示詞,讓 ChatGPT 工作模式或 Codex 將這個工作流程重建為 MCP 工具。請指出哪些操作會讀取資訊,哪些會進行變更。 列出 API 操作、輸入、傳回的欄位及回答格式,並標明你不清楚的部分。請勿包含憑證、機密資訊或隱藏指示。 請在提示詞中要求建立工具的一方沿用現有 API,並說明如何設定連線。

2. 對照動作設定檢查提示詞

遷移前,請先前往 GPT 編輯器的動作區段,儲存動作結構描述、驗證方式及不含機密資訊的連線設定。請根據這些資料補齊提示詞,或請 GPT 擁有者協助。

3. 建立新的工作站外掛程式

開始新的任務。如果使用工作模式,請選取 @Plugin Creator。如果使用 Codex,請使用 $plugin-creator。貼上檢查過的提示詞,附上結構描述或 API 文件,並要求在工作站上代管伺服器。

依照連接你的系統和發布並安裝的步驟操作,然後在工作模式的任務中選取新的外掛程式,請它執行原本的任務。詳情請參閱遷移常見問題。

疑難排解

如果外掛程式未如預期運作

如果連線出錯或找不到工具,請確認工作站擁有者已發布最新版本,且外掛程式已安裝並連線。如有錯誤,請將錯誤訊息提供給 Plugin Creator 或伺服器擁有者。

如果 ChatGPT 沒有使用工具,請使用 @ 選取外掛程式,並明確指定要查詢的項目。如果團隊成員無法使用外掛程式,請檢查對方是否有權存取外掛程式、應用程式、工作站和相關記錄。

如果外掛程式標示為僅限桌面版,請使用支援的桌面應用程式,或請作者檢查外掛程式的封裝方式。單靠遠端 MCP 伺服器,無法讓外掛程式相容於網頁版。

連接現有的 MCP 伺服器

ChatGPT 網頁版透過外掛程式使用遠端 MCP 工具。如果已有伺服器,請依照連接並測試外掛程式的步驟操作。本機 Codex 用戶端也可以直接連接 MCP 伺服器,並共用設定。

選擇你使用的介面,即可查看對應的設定方式與選項。

ChatGPT 桌面應用程式、Codex CLI 和 IDE 擴充功能都支援 MCP 伺服器,並在同一台 Codex 主機上共用 MCP 設定。

以下功能適用於在 Codex 主機上設定的 MCP 伺服器。代管外掛程式的工具可能支援不同的功能。

支援的 MCP 功能

  • STDIO 伺服器:透過指令啟動,以本機程序執行。
    • 環境變數
  • Streamable HTTP 伺服器:透過指定的位址存取。
    • Bearer 權杖驗證
    • OAuth 驗證,包括用戶端 ID 中繼資料文件(CIMD)和動態用戶端註冊(DCR)
    • 受信任的第一方伺服器可使用 ChatGPT 工作階段驗證
  • 伺服器指示:Codex 會讀取 MCP 伺服器在初始化期間傳回的 instructions 欄位,並在使用該伺服器的工具時,將其中的內容當作適用於整台伺服器的指引。

如果你為 Codex 建置或維護 MCP 伺服器,請使用 instructions 說明跨工具的工作流程,以及整台伺服器適用的限制與速率限制。請讓前 512 個字元構成一段完整、可獨立理解的說明,讓 Codex 在決定如何使用伺服器時就能取得最重要的指引。

將 Codex 連接到 MCP 伺服器

Codex 會將 MCP 設定與其他 Codex 設定一併儲存在 config.toml 中。預設路徑為 ~/.codex/config.toml。你也可以在 .codex/config.toml 中設定僅適用於特定專案的 MCP 伺服器(僅限受信任的專案)。

ChatGPT 桌面應用程式、Codex CLI 和 IDE 擴充功能會共用這些設定。設定好 MCP 伺服器後,你可以在這些用戶端之間切換,無須重新設定。

在 ChatGPT 桌面應用程式中設定

  1. 開啟設定,然後選取 MCP 伺服器。
  2. 選取新增伺服器。
  3. 輸入名稱,選擇 STDIO 或 Streamable HTTP,然後輸入伺服器的啟動指令或 URL。
  4. 儲存伺服器設定,然後選取重新啟動。

伺服器清單會顯示哪些伺服器已啟用、哪些需要 OAuth。需要登入 OAuth 伺服器時,請選取驗證。在撰寫工具中輸入 /mcp 即可查看已連線的伺服器。

使用 config.toml 設定

如需更細緻的控制,請編輯 ~/.codex/config.toml 或專案專用的 .codex/config.toml。設定參考列出所有支援的 MCP 選項,並提供搜尋功能。

請在設定檔中為每台 MCP 伺服器建立一個 [mcp_servers.<server-name>] 資料表。

STDIO 伺服器

  • command(必填):啟動伺服器的指令。
  • args(選填):要傳給伺服器的引數。
  • env(選填):要為伺服器設定的環境變數。
  • env_vars(選填):允許轉送給伺服器的環境變數。
  • cwd(選填):啟動伺服器時的工作目錄。

env_vars 的項目可以是單純的變數名稱,也可以是指定來源的物件:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

字串項目和指定 source = "local" 的項目都會從 Codex 的本機環境讀取變數值。指定 source = "remote" 時,則會從遠端執行器環境讀取,且必須使用遠端 MCP stdio。

Streamable HTTP 伺服器

  • url(必填):伺服器位址。
  • auth(選填):Codex 嘗試已設定的 Bearer 權杖和授權標頭後,接著要嘗試的驗證方式。使用 oauth(預設值)會採用已儲存的 MCP OAuth 憑證。使用 chatgpt 時,若來源是受信任的第一方 ChatGPT 來源,會採用目前的 ChatGPT 工作階段,並以已儲存的 OAuth 憑證作為備用方式。
  • bearer_token_env_var(選填):儲存 Bearer 權杖的環境變數名稱。權杖會透過 Authorization 標頭傳送。
  • http_headers(選填):標頭名稱與固定值的對應表。
  • env_http_headers(選填):標頭名稱與環境變數名稱的對應表,標頭值取自環境變數。
  • http_headers_helper(選填):輸出 JSON 物件的本機指令。物件包含標頭名稱及對應的字串值,例如 {"X-Auth": "temporary-token"}。此選項適用於從本機環境建立的 HTTP MCP 連線,不適用於 stdio 伺服器或透過遠端執行環境建立的連線。

Codex 會為該連線快取輔助指令提供的標頭。同源 POST 請求傳回 401 或 403 後,Codex 會重新取得一次標頭,且只有在輔助指令傳回的值有所變更時才會重試。明確指定的 Bearer 權杖和 OAuth 憑證優先於輔助指令提供的 Authorization 標頭。如果 OAuth 的 403 回應指出授權範圍不足,Codex 就不會透過輔助指令重新取得標頭。

如果無法從任何來源取得憑證,Codex 可以在未驗證的情況下連接伺服器。若要啟動 MCP OAuth 登入流程,請另外執行 codex mcp login <server-name>。

其他設定選項

  • environment_id 指定 stdio 或 Streamable HTTP 伺服器使用的環境,預設值為 local。若要透過遠端執行器連線,請使用該執行器已註冊的環境 ID。
  • startup_timeout_sec(選填):等待伺服器啟動的逾時秒數。預設值為 10。
  • tool_timeout_sec(選填):等待伺服器執行工具的逾時秒數。預設值為 60。
  • enabled(選填):設為 false 可停用伺服器,無須刪除設定。
  • 設定 required = true 後,如果這台已啟用的伺服器尚未就緒,Codex 就會啟動失敗。依預設,startup_readiness = "connection" 要求先建立連線。若設為 startup_readiness = "catalog",只要快取的工具目錄有效,Codex 就能在伺服器建立連線期間完成啟動。實際呼叫工具時仍需要有效連線。
  • enabled_tools(選填):允許使用的工具清單。
  • disabled_tools(選填):禁止使用的工具清單,在 enabled_tools 之後套用。
  • default_tools_approval_mode(選填):這台伺服器所提供工具的預設核准方式。支援的值為 auto、prompt、writes 和 approve。使用 writes 模式時,未標示為唯讀的工具都會要求核准。
  • tools.<tool>.approval_mode(選填):覆寫個別工具的核准方式。
  • tools.<tool>.output_token_limit(選填):單一工具的輸出 Token 上限,必須為正數,且不含序列化時按標準額外預留的 20%。此值會覆寫模型對該工具預設的輸出截斷上限。

頂層設定 mcp_optional_startup_grace_ms 決定 Codex 建立初始工具目錄時,要等候選用 MCP 伺服器多久。預設值為 1000 毫秒。設為 0 時,會改用各伺服器的 startup_timeout_sec 決定等候時間。必要伺服器仍使用各自的啟動逾時設定。

OAuth 用戶端註冊與回呼

如果授權伺服器要求使用預先註冊的 OAuth 用戶端,請在新增 MCP 伺服器時提供用戶端 ID:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

如果是機密用戶端,還要傳入 --oauth-client-secret。請從環境變數讀取用戶端密鑰:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

使用此選項時,用戶端 ID 和密鑰皆不得為空。Codex 會以 mcp_servers.example.oauth.client_secret 為設定鍵,將密鑰儲存在 config.toml 中。請限制該檔案的存取權,並避免將其納入版本控制。

請註冊 codex mcp add 顯示的回呼 URL,位址必須完全相符。如果授權伺服器宣告支援簽發者識別,CLI 可以顯示下列 URL:

OAuth callback URL: http://127.0.0.1/callback

對於本例中的公開用戶端,Codex 會將回呼 URL 與用戶端 ID 一併儲存在 config.toml 中,以供日後登入使用:

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

對於新加入的預先註冊用戶端,只有在授權伺服器宣告 authorization_response_iss_parameter_supported: true,並在中繼資料中提供 issuer 時,才會使用固定的回呼 URL。如果伺服器未宣告支援簽發者識別,Codex 會在 URL 末尾加上伺服器專屬的回呼 ID,例如 http://127.0.0.1/callback/XuuuHAzzHOni。既有用戶端若未儲存回呼 URL,仍會使用其回呼 ID 專屬的重新導向位址。

登入時,Codex 會根據 OAuth 設定和授權伺服器的中繼資料選擇回呼:

OAuth 設定 是否支援簽發者識別 使用的回呼
已設定 callback_url,未設定 client_id 支援 使用設定的回呼 URL 註冊用戶端。
已設定 callback_url,未設定 client_id 不支援 在設定的回呼 URL 末尾加上伺服器專屬的回呼 ID,再用來註冊用戶端。
已設定 client_id 和 callback_url 支援 沿用設定的回呼 URL。授權回應必須包含相符的 iss。
已設定 client_id,且 callback_url 以正確的回呼 ID 結尾 不支援 直接沿用設定的回呼 URL。
已設定 client_id,但 callback_url 缺少正確的回呼 ID 不支援 Codex 會忽略設定的回呼 URL,改用 mcp_oauth_callback_url,若未設定則使用 http://127.0.0.1/callback,並在末尾加上回呼 ID。
已設定 client_id,未設定 callback_url 支援或不支援 使用全域或預設回呼 URL,並在末尾加上伺服器專屬的回呼 ID。

使用備用回呼不會修改已儲存的回呼 URL。Codex 會根據 MCP 伺服器的 URL(包含路徑和查詢字串)產生回呼 ID。自動登入與手動啟動登入均適用相同的選擇規則。

如果需要自訂回呼路徑或遠端 Devbox 的入口 URL,請設定 mcp_oauth_callback_url。如果提供者支援簽發者識別,新加入的預先註冊用戶端會直接使用該 URL。否則,會在設定的 URL 末尾加上伺服器專屬的回呼 ID。註冊時,請務必完整照錄 codex mcp add 顯示的回呼 URL。

對於未明確指定連接埠的 http://127.0.0.1 回呼,Codex 顯示及儲存的 URL 會省略監聽連接埠,並在授權時填入目前使用的監聽連接埠。此替換方式不適用於 localhost、IPv6 主機、HTTPS URL 或已包含連接埠的回呼。依據 RFC 8252 第 7.3 節,授權伺服器必須接受可變動的回送連接埠。

設定 mcp_oauth_callback_port 可指定固定的全域監聽連接埠,也可以透過 mcp_servers.<server-name>.oauth.callback_port 為個別伺服器覆寫這項設定。在回呼 URL 中明確指定連接埠並不會設定監聽連接埠。若要使用直接回送的回呼,請使用不含連接埠的 http://127.0.0.1,或明確將回呼 URL 與監聽器設為相同的連接埠。透過代理伺服器轉送回呼時,可以刻意讓對外 URL 使用不同於本機監聽器的連接埠。本機回呼 URL 會繫結至本機介面,非本機回呼 URL 則會繫結至 0.0.0.0。

Codex 會在交換授權碼前驗證回應傳回的 iss。如果 iss 不符,一律拒絕該回應。如果伺服器已宣告支援簽發者識別,但回應缺少 iss,也會拒絕該回應。這兩種情況下,Codex 都不會交換授權碼,也不會改用其他回呼。如果回呼 URL 格式錯誤,或伺服器宣告支援簽發者識別卻未在中繼資料中提供簽發者,流程同樣會直接失敗。請參閱驗證使用者身分。

若要指定伺服器的 OAuth 授權範圍,請將 mcp_servers.<server-name>.scopes 寫入 config.toml。若要針對單次登入覆寫這些範圍,請執行 codex mcp login <name> --scopes read,write。如果兩者皆未設定,Codex 會請求伺服器在初始 WWW-Authenticate 驗證挑戰中列出的授權範圍。如果該挑戰未列出範圍,而受保護資源的中繼資料有宣告授權範圍,Codex 就會使用中繼資料中宣告的範圍。

即使清單為空(scopes = []),OAuth 程式庫仍可自行選擇授權範圍。如果授權伺服器支援 offline_access,程式庫也可以加入這個範圍。

OAuth 用戶端註冊

Codex 支援 OAuth 用戶端 ID 中繼資料文件(CIMD)和動態用戶端註冊(DCR)。依預設,如果授權伺服器宣告 client_id_metadata_document_supported: true、將 none 列入 token_endpoint_auth_methods_supported,且回呼使用支援的回送 URL,Codex 就會自動選擇 CIMD。否則,如果 DCR 可用,就會採用 DCR。已設定的 OAuth 用戶端 ID 一律優先使用,此時會略過用戶端註冊。

如果使用 CIMD,但授權回應未繫結至簽發者,Codex CLI 會使用由 ChatGPT 代管、專供該 MCP 伺服器使用的中繼資料文件:

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex 會根據 MCP 伺服器 URL 產生 <callback_id>,並將其加入回送重新導向 URI,例如 http://127.0.0.1:<port>/callback/<callback_id>。中繼資料文件會註冊相符的回送 URI,但不含連接埠。依據 RFC 8252,授權伺服器必須接受登入時選定的連接埠,並確認主機與路徑完全相符。若要自訂回呼主機、路徑或查詢參數,必須使用 DCR 或設定 OAuth 用戶端 ID。

Codex CLI 也支援固定的共用 CIMD 文件:

https://chatgpt.com/oauth/codex/client.json

Codex CLI 會在下列條件都成立時,使用這份固定文件與共用的 /callback 路徑:授權伺服器宣告 authorization_response_iss_parameter_supported: true、在中繼資料中提供有效的 issuer,並在授權回應中包含相符的 iss。如果伺服器的回應未繫結至簽發者,則會使用該回呼專屬的文件。

若要為單次 CLI 登入指定註冊方式,請使用 --oauth-client-registration:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

預設值為 auto。所選的註冊方式僅適用於本次登入,不會儲存到 config.toml 中。

config.toml 範例

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

外掛程式提供的 MCP 伺服器

已安裝的外掛程式可以透過其資訊清單隨附 MCP 伺服器。這些伺服器由外掛程式啟動,因此其傳輸指令不由使用者設定檔指定。你仍可在使用者設定檔的 plugins.<plugin>.mcp_servers.<server> 下啟用或停用伺服器,以及設定工具政策。

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

外掛程式提供的 HTTP MCP 伺服器也可以在 .mcp.json 中宣告 OAuth 設定。外掛程式資訊清單使用小駝峰式命名的欄位 clientId、callbackUrl 和 callbackPort:

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

外掛程式提供的 MCP 伺服器與其他 MCP 伺服器適用相同的回呼選擇規則。如果外掛程式提供 clientId、其提供者不支援繫結至簽發者的回呼,且 callbackUrl 缺少伺服器專屬的回呼 ID,Codex 在登入時會忽略該 URL,改用 mcp_oauth_callback_url,若未設定則使用 http://127.0.0.1/callback,並在末尾加上回呼 ID。已設定的 callbackUrl 不會變更。

外掛程式的 oauth.callbackPort 會覆寫全域的 mcp_oauth_callback_port。如果兩者皆未設定,Codex 會選擇臨時連接埠。callbackUrl 中的連接埠不會決定監聽器使用哪個連接埠。若要在直接回送的回呼中使用固定連接埠,請將這兩個值設為相同的連接埠:

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

如果使用遠端入口或其他代理伺服器,只要代理伺服器會將請求轉送至設定的監聽器,就可以刻意讓回呼 URL 與本機監聽器使用不同的連接埠。

實用的 MCP 伺服器範例

可用的 MCP 伺服器持續增加。以下是幾個常見的選擇: