如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
總覽 智慧體存取權 ChatGPT 與 Codex 使用者文件 使用案例

建立 MCP 伺服器

為外掛程式加入即時資料與可控的工具。

如果外掛程式的使用案例需要即時資料、身分驗證、受控操作,或需要在你管理的基礎架構上執行程式碼,就加入 MCP 伺服器。伺服器會定義 ChatGPT 和 Codex 可以使用哪些工具,無須傳回自訂使用者介面。

先從使用案例清單中列出的支援目標著手。每項工具都應協助使用者達成明確的目標,並且只提供達成該目標所需的資料和操作。

先建立工具。確認伺服器在沒有自訂使用者介面的情況下也能正常運作後,即可針對需要視覺互動的工作流程,為 MCP 伺服器加入使用者介面。

選擇 MCP 軟體開發套件

官方軟體開發套件提供建立結構描述的輔助工具、伺服器程式骨架,以及可串流的 HTTP 傳輸機制:

依照伺服器採用的技術安裝對應的 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 執行以下檢查:

  1. 確認初始化成功。
  2. 檢閱伺服器指示,以及伺服器列出的可用工具。
  3. 分別使用具代表性的輸入和無效輸入呼叫每項工具。
  4. 驗證結構描述、結果、錯誤和註解。
  5. 確認伺服器會對私人資料存取和寫入操作執行授權檢查。

接著,將自訂 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 伺服器部署在無伺服器、容器、邊緣運算或傳統應用程式基礎架構上。選擇平台時,請考量以下因素:

  • 對執行環境與相依套件的支援。
  • 平台處理串流回應的方式。
  • 冷啟動延遲與請求延遲。
  • 能否透過網路存取必要的服務。
  • 資料駐留與法規遵循要求。
  • 機密資訊管理。
  • 記錄、追蹤與警示功能。
  • 是否支援版本管理與回復至舊版。

如果伺服器也託管選用的使用者介面資源,請將這些資源部署在穩定的來源,並確認元件的內容安全性政策允許這些來源。

設定正式環境的端點

部署前:

  1. 透過主機的機密資訊管理系統設定正式環境的憑證。
  2. 設定授權伺服器,以及允許的重新導向行為。
  3. 對資源耗用量大或操作效果對外可見的工具設定逾時與速率限制。
  4. 移除偵錯用的回應和不必要的個人資料。
  5. 確認記錄中沒有存取權杖或敏感的工具結果。

部署後,使用 MCP Inspector 呼叫正式環境的端點。驗證初始化、伺服器指示、工具、結構描述、註解、身分驗證、結果和錯誤。

規劃更新

已發布的工具名稱與結構描述應保持回溯相容。新增欄位或工具時,請維持既有的介面契約。如果中繼資料有變更,請重新整理自訂 MCP 伺服器的連線,並在提交前重新執行整組評估案例。

如果提供選用的使用者介面,且 HTML、JavaScript 或 CSS 的變更可能導致快取中的元件無法正常運作,請為資源識別碼加上版本資訊。

加入 MCP 擴充功能

OpenAI MCP 擴充功能可將外掛程式連接至 ChatGPT 的側邊欄、撰寫工具和檔案檢視器。如需範例與設定方式,請參閱外掛程式擴充功能。

安全性提醒

  • 將所有工具輸入視為不可信任的資料。
  • 在伺服器端驗證參數並執行授權檢查。
  • 執行可能造成重大影響的寫入操作前,必須要求確認。
  • 不要在工具的中繼資料和結果中包含機密資訊或敏感資料。
  • 記錄足夠的上下文以供調查失敗原因,但不要記錄憑證或不必要的個人資料。
  • 對資源耗用量大或效果對外可見的操作設定速率限制。