如果外掛程式的使用案例需要即時資料、身分驗證、受控操作,或需要在你管理的基礎架構上執行程式碼,就加入 MCP 伺服器。伺服器會定義 ChatGPT 和 Codex 可以使用哪些工具,無須傳回自訂使用者介面。
先從使用案例清單中列出的支援目標著手。每項工具都應協助使用者達成明確的目標,並且只提供達成該目標所需的資料和操作。
先建立工具。確認伺服器在沒有自訂使用者介面的情況下也能正常運作後,即可針對需要視覺互動的工作流程,為 MCP 伺服器加入使用者介面。
選擇 MCP 軟體開發套件
官方軟體開發套件提供建立結構描述的輔助工具、伺服器程式骨架,以及可串流的 HTTP 傳輸機制:
- TypeScript SDK 的套件名稱為
@modelcontextprotocol/sdk。 - Python SDK 的套件名稱為
mcp。
依照伺服器採用的技術安裝對應的 SDK:
# TypeScript
npm install @modelcontextprotocol/sdk zod
# Python
pip install mcp
建立伺服器
建立 MCP 伺服器,並指定穩定的名稱和版本:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "acme-projects",
version: "1.0.0",
});MCP 伺服器也可以在初始化時傳回 instructions 欄位。ChatGPT 和 Codex 會搭配工具的中繼資料使用這些指示。
在伺服器指示中說明多項工具都需要遵循的規則,例如工具的必要呼叫順序或共用的速率限制。將最重要的資訊放在前 512 個字元內。不要逐一重述工具說明,也不要試圖改變模型的個性。
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Before updating a project, call get_project to confirm its ID and current status.",
}
);根據使用者目標定義工具
針對外掛程式必須支援的每種操作,各建立一項工具。優先設計用途明確的操作,例如 list_projects、get_project 和 update_project,避免將許多互不相關的模式集中在同一項工具中。
每項工具都需要具備:
- 能表明操作內容的名稱,以及易於理解的標題。
- 指出何時應使用這項工具的說明。
- 明確的輸入結構描述。
- 輸出結構描述(若工具會傳回結構化資料)。
- 準確的安全性註解。
- 負責檢查請求權限並在授權範圍內執行操作的處理函式。
模型會根據這些中繼資料判斷是否呼叫工具,以及如何呼叫。名稱、說明、結構描述和註解都會影響使用者實際體驗到的外掛程式行為。
// Local example data; replace this with your application data.
const projects = [
{ id: "project-1", name: "Website", status: "active" },
{ id: "project-2", name: "Launch", status: "archived" },
];
async function listProjects({ status }: { status?: string }) {
return projects.filter((project) => !status || project.status === status);
}
import { z } from "zod";
server.registerTool(
"list_projects",
{
title: "List projects",
description:
"Use this when the user wants to find or review projects in their Acme workspace.",
inputSchema: {
status: z.enum(["active", "archived"]).optional(),
},
outputSchema: {
projects: z.array(
z.object({
id: z.string(),
name: z.string(),
status: z.string(),
})
),
},
annotations: {
readOnlyHint: true,
openWorldHint: false,
destructiveHint: false,
},
},
async ({ status }) => {
const projects = await listProjects({ status });
return {
structuredContent: { projects },
content: [
{
type: "text",
text: `Found ${projects.length} projects.`,
},
],
};
}
);在沒有使用者介面的情況下傳回有用的結果
工具結果可以包含:
structuredContent:精簡的資料,供模型檢視並用於後續呼叫。content:文字或其他 MCP 內容,協助模型回答使用者的問題。_meta:供特定用戶端使用、模型無法看見的資料。
傳回足夠的資訊,讓模型無須介面元件也能完成工作流程。在結構化結果中使用穩定的識別碼,讓後續呼叫的工具能參照同一筆記錄。
不要在工具結果中包含機密資訊、存取權杖或不必要的個人資料。模型看不到 _meta 中的資料,但這個欄位不能取代授權機制或安全的儲存空間。
驗證身分並檢查請求權限
如果工具會讀取私人資料或代使用者執行操作,就應加入身分驗證機制。MCP 伺服器必須逐一檢查每個請求的權限,絕不能依賴模型判斷使用者是否具有存取權。
如需瞭解 OAuth 探索、安全性配置及授權挑戰,請參閱驗證使用者身分。
為方便使用者操作多個帳戶,請提供一項需要身分驗證的唯讀帳戶資料查詢工具,並加上 _meta["openai/profile"]: true 標記。OpenAI 會使用這些資料一致地識別已連線的帳戶,協助使用者區分各帳戶。請根據請求中已驗證的憑證取得對應的帳戶資料,並將每次工具呼叫限制在該憑證允許的範圍內。即使沒有帳戶資料查詢工具,使用者仍可連線至多個帳戶。如需結構描述與實作範例,請參閱支援多個帳戶。
工具註解與使用者資訊徵詢
請依據工具的實際行為設定註解:
readOnlyHint:只有在工具無法變更狀態時才設為true。destructiveHint:如果工具可能造成無法或難以復原的結果,請設為true。openWorldHint:如果工具會存取公用網際網路,或存取範圍不固定的外部資源,請設為true。這也包括網頁搜尋等唯讀操作。如果工具只能存取範圍明確的私人帳戶或工作區,即使服務託管於外部,也可以設為false。
註解有助於 ChatGPT 和 Codex 判斷何時需要確認,以及應採取哪些安全措施。伺服器仍須自行執行授權檢查、資料驗證和確認程序。
如果原始工具呼叫未提供伺服器所需的結構化資訊,請透過 MCP 的資訊徵詢機制向使用者詢問。只詢問使用者可合理提供的資訊。不要用這項機制收集機密資訊或繞過正常的身分驗證流程。
支援公司知識功能
公司知識功能可以使用 MCP 伺服器提供的唯讀工具。若要讓外掛程式符合公司知識來源的資格,請實作 search 和 fetch 工具的標準輸入結構描述,並為其他唯讀工具加上 readOnlyHint: true 標記。
對於模型應引用的來源,請傳回使用者可以開啟的絕對網址。內部文件識別碼應放在結果的 id 欄位中。如需必要的結構描述和結果格式,請參閱為 ChatGPT 和 API 整合建立 MCP 伺服器。
在本機執行與測試
提供可串流的 HTTP 端點(通常位於 /mcp),再使用 MCP Inspector 檢查端點:
npx @modelcontextprotocol/inspector
在 Inspector 介面中選取 Streamable HTTP,然後輸入 http://localhost:3000/mcp。
使用 Inspector 執行以下檢查:
- 確認初始化成功。
- 檢閱伺服器指示,以及伺服器列出的可用工具。
- 分別使用具代表性的輸入和無效輸入呼叫每項工具。
- 驗證結構描述、結果、錯誤和註解。
- 確認伺服器會對私人資料存取和寫入操作執行授權檢查。
接著,將自訂 MCP 伺服器連線至 ChatGPT,並逐一執行使用案例清單中的直接請求、間接請求、邊界情況請求,以及超出支援範圍的請求。
部署端點
若要提交外掛程式供公開發布,請將 MCP 伺服器部署在穩定且可公開存取的 HTTPS 端點。安全 MCP 通道可讓 ChatGPT 連線至私人 MCP 伺服器,但這種連線方式不符合公開提交的要求。
正式環境的端點必須符合以下要求:
- 支援 MCP 的可串流 HTTP 傳輸機制。
- 能在固定網址回應請求,網址通常以
/mcp結尾。 - 符合外掛程式工作流程對延遲和可用性的要求。
- 能連線至必要的服務和資料儲存區。
- 維持身分驗證與授權的界線。
- 在初始化或工具呼叫失敗時產生記錄與指標。
如果 MCP 伺服器必須維持私有,請部署公開的 HTTPS 代理伺服器,將 MCP 請求轉送至私人伺服器。使用 OpenAI 代管的 mTLS 驗證 ChatGPT 的 MCP 用戶端身分。如果外掛程式需要驗證使用者身分,請使用 OAuth 2.1。如果網路要求設定 IP 允許清單,請使用已公布的 ChatGPT 連接器 IP 範圍,並自動更新允許清單。IP 允許清單不能取代身分驗證或授權。
公開端點必須持續開放存取,以便進行外掛程式審查和網域驗證。公開提交時,不可僅使用安全 MCP 通道,也不可使用臨時通道或本機端點。
選擇基礎架構
你可以將 MCP 伺服器部署在無伺服器、容器、邊緣運算或傳統應用程式基礎架構上。選擇平台時,請考量以下因素:
- 對執行環境與相依套件的支援。
- 平台處理串流回應的方式。
- 冷啟動延遲與請求延遲。
- 能否透過網路存取必要的服務。
- 資料駐留與法規遵循要求。
- 機密資訊管理。
- 記錄、追蹤與警示功能。
- 是否支援版本管理與回復至舊版。
如果伺服器也託管選用的使用者介面資源,請將這些資源部署在穩定的來源,並確認元件的內容安全性政策允許這些來源。
設定正式環境的端點
部署前:
- 透過主機的機密資訊管理系統設定正式環境的憑證。
- 設定授權伺服器,以及允許的重新導向行為。
- 對資源耗用量大或操作效果對外可見的工具設定逾時與速率限制。
- 移除偵錯用的回應和不必要的個人資料。
- 確認記錄中沒有存取權杖或敏感的工具結果。
部署後,使用 MCP Inspector 呼叫正式環境的端點。驗證初始化、伺服器指示、工具、結構描述、註解、身分驗證、結果和錯誤。
規劃更新
已發布的工具名稱與結構描述應保持回溯相容。新增欄位或工具時,請維持既有的介面契約。如果中繼資料有變更,請重新整理自訂 MCP 伺服器的連線,並在提交前重新執行整組評估案例。
如果提供選用的使用者介面,且 HTML、JavaScript 或 CSS 的變更可能導致快取中的元件無法正常運作,請為資源識別碼加上版本資訊。
加入 MCP 擴充功能
OpenAI MCP 擴充功能可將外掛程式連接至 ChatGPT 的側邊欄、撰寫工具和檔案檢視器。如需範例與設定方式,請參閱外掛程式擴充功能。
安全性提醒
- 將所有工具輸入視為不可信任的資料。
- 在伺服器端驗證參數並執行授權檢查。
- 執行可能造成重大影響的寫入操作前,必須要求確認。
- 不要在工具的中繼資料和結果中包含機密資訊或敏感資料。
- 記錄足夠的上下文以供調查失敗原因,但不要記錄憑證或不必要的個人資料。
- 對資源耗用量大或效果對外可見的操作設定速率限制。