MCP 事件可讓 ChatGPT 訂閱 MCP 伺服器的更新,例如新訊息、內容更新或狀態變更。使用者可以指定要監控的項目,以及 ChatGPT 收到更新時應執行的動作。
| 使用情境 | 使用者要求 | MCP 事件 |
|---|---|---|
| 根據意見回饋建立 Pull Request | 監控 #product-feedback 頻道中的錯誤回報,並建立包含修正與測試的草稿 Pull Request。 | message.created,依 channel_id 篩選 |
| 根據審閱意見修改文件 | 留意這份文件的審閱意見,並依照其中的要求修改文件。 | comment.created,依 document_id 篩選 |
開始之前
你可以在 ChatGPT 網頁版的工作模式對話中使用 MCP 事件。在桌面應用程式中,請在工作模式對話中選取雲端。你也可以搭配 dot 使用 MCP 事件。工作區對外掛程式與事件觸發任務的控管設定同樣適用。
ChatGPT 支援透過 Streamable HTTP 搭配 initialize 使用 MCP 事件,也支援透過 MCP 2.0 HTTP(通訊協定版本 2026-07-28)使用。在外掛程式中設定伺服器,並確保伺服器能持久儲存訂閱資料,以及透過 HTTPS 對外連線至回呼 URL。
ChatGPT 支援MCP 事件規格草案中的 webhook 傳送與回呼驗證機制。此整合不支援輪詢、串流,也不支援草案中的 gap 和 terminated 控制通知。
運作方式
- 伺服器列出支援的事件。
- 使用者告訴 ChatGPT 要監控哪些項目,以及該如何回應。
- ChatGPT 透過 MCP 伺服器訂閱事件,並提供回呼 URL 和簽署密鑰。
- 伺服器將符合訂閱條件的事件傳送至該 URL。
- ChatGPT 在訂閱該事件的對話中收到事件,並依照使用者的指示回應。
宣告支援事件功能
用戶端會先查看伺服器宣告的能力,以探索可用事件。若 MCP 版本使用初始化流程,請將 events 加入 initialize 回應所列的能力:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": {
"tools": {},
"events": {}
},
"serverInfo": {
"name": "example-server",
"version": "1.0.0"
}
}
}
若使用 MCP 2.0(通訊協定版本 2026-07-28),請將 events 加入 server/discover 回應所列的能力:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": {},
"events": {}
}
}
}
請在工具使用的同一個 MCP 端點上實作以下三個事件方法。該端點須要求身分驗證:
| 方法 | 伺服器行為 |
|---|---|
events/list |
說明可用的事件及其篩選條件。 |
events/subscribe |
建立或更新訂閱。 |
events/unsubscribe |
停止訂閱。 |
定義事件
事件定義讓 ChatGPT 知道使用者可以訂閱哪些事件,以及有哪些篩選條件可用。透過 events/list 傳回這些定義,其中須包含事件名稱、支援的傳送模式、訂閱引數和承載資料的結構描述。
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"events": [
{
"name": "comment.created",
"description": "A new review comment was added to the specified document.",
"delivery": ["webhook"],
"inputSchema": {
"type": "object",
"properties": {
"document_id": {
"type": "string",
"description": "ID of the document to monitor for new review comments."
}
},
"required": ["document_id"],
"additionalProperties": false
},
"payloadSchema": {
"type": "object",
"properties": {
"document_id": { "type": "string" },
"comment_id": { "type": "string" },
"text": { "type": "string" },
"url": { "type": "string" }
},
"required": ["document_id", "comment_id", "text", "url"],
"additionalProperties": false
}
}
]
}
}
inputSchema 描述 ChatGPT 訂閱時傳入的引數,payloadSchema 則描述每個傳送事件中的 data 物件。
請使用穩定的事件名稱,並提供具體的說明。提供文件 ID、專案 ID 或佇列 ID 等篩選條件,並在伺服器傳送事件前套用這些條件。只傳回目前連線的帳戶有權探索的事件。
若事件清單分成多頁,請傳回 nextCursor。伺服器必須接受這個值作為 cursor,以處理下一個 events/list 請求。
建立訂閱
使用者要求監控某個事件時,ChatGPT 會呼叫 events/subscribe,並提供事件名稱、篩選引數和 webhook 目的地:
{
"jsonrpc": "2.0",
"id": 2,
"method": "events/subscribe",
"params": {
"name": "comment.created",
"arguments": {
"document_id": "doc_123"
},
"delivery": {
"mode": "webhook",
"url": "https://receiver.example.com/mcp-events/callback_123",
"secret": "whsec_<base64-encoded-signing-key>"
},
"cursor": null
}
}
接受訂閱前,請完成下列步驟:
- 確認使用者有權以指定的引數訂閱所要求的事件。
- 依據事件定義驗證事件名稱與引數。簽署密鑰必須以
whsec_開頭,其後的 base64 值解碼後的長度必須為 24 至 64 位元組。 - 檢查回呼 URL 並驗證其端點。
- 儲存訂閱及其擁有者、篩選條件、回呼 URL、簽署密鑰和到期時間。
根據已通過驗證的主體、回呼 URL、事件名稱和引數產生訂閱 ID,確保相同輸入一律產生相同 ID。傳回該 ID 及伺服器核定的到期時間:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"id": "sub_123",
"refreshBefore": "2026-10-02T12:00:00Z",
"cursor": null,
"truncated": false
}
}
將 refreshBefore 設為伺服器核定的到期時間。對於不支援重播的事件類型,請傳回 cursor: null。
建立訂閱的操作必須具備冪等性。若識別資訊與現有訂閱相符,就更新該訂閱。請使用正規化的 JSON 比對引數,避免因物件鍵的順序不同而建立重複訂閱。
驗證回呼
傳送應用程式資料前,請先傳送已簽署的請求來驗證回呼。每次都要在請求中附上新產生的驗證值,並限制該值只能在短時間內使用一次:
{
"type": "verification",
"challenge": "a-single-use-random-value"
}
為驗證請求指定唯一的 webhook-id,例如 msg_verification_123,並使用該訂閱的密鑰簽署請求本文。請求須包含 webhook-timestamp、webhook-signature 和 X-MCP-Subscription-Id。驗證成功時,ChatGPT 會在回應中原樣傳回驗證值:
{
"challenge": "a-single-use-random-value"
}
必須收到 2xx 回應,並以固定時間比對確認傳回的驗證值與送出的值相符,才能開始傳送事件。依已通過驗證的主體和回呼 URL 快取成功的驗證結果,並為快取設定有效期限,避免重複的訂閱請求觸發多次驗證。若驗證失敗,請傳回 JSON-RPC 錯誤 -32015(CallbackEndpointError),並以 data.reason 指出錯誤類別,例如 challenge_failed 或 timeout。
回呼必須使用 HTTPS。建立連線時,請解析並驗證目的地位址,再連線至已驗證的位址,同時保留原始主機名稱以供 TLS 驗證。請封鎖私有、本機及其他非公開位址,且不得跟隨重新導向。驗證請求與事件傳送都必須執行這些檢查。
傳送事件
若新留言符合有效訂閱的條件,請以 POST 將一個事件物件傳送至該訂閱的回呼 URL:
{
"eventId": "evt_456",
"name": "comment.created",
"timestamp": "2026-10-01T12:05:00Z",
"data": {
"document_id": "doc_123",
"comment_id": "comment_456",
"text": "Can we add the rollout dates to this section?",
"url": "https://docs.example.com/doc_123#comment_456"
},
"cursor": null
}
每個事件都要使用唯一的事件 ID,重試時沿用該 ID。將 timestamp 設為事件發生時間,使用含時區的 ISO 8601 時間戳記。name 必須與訂閱的事件名稱相符,data 物件必須符合該事件的 payloadSchema。請將應用程式欄位放在 data 內。最上層的 type 用於識別通訊協定的控制通知。
對於大型記錄,請傳送摘要,並提供讀取工具以便擷取完整記錄。請將留言及其他由使用者撰寫的文字視為資料。不要在事件的承載資料中加入指示模型如何行動的內容。
簽署請求
ChatGPT 使用 Standard Webhooks 驗證傳入的事件。請傳送以下標頭:
| 標頭 | 值 |
|---|---|
Content-Type |
application/json |
webhook-id |
與請求本文中的 eventId 相同。 |
webhook-timestamp |
簽署時的 Unix 時間戳記,以秒為單位。 |
webhook-signature |
Standard Webhooks 的 HMAC 簽章。 |
X-MCP-Subscription-Id |
events/subscribe 傳回的 ID。 |
傳送事件時,請依照 Standard Webhooks 規格,使用訂閱的簽署密鑰簽署請求。簽章涵蓋事件 ID、簽署時間戳記,以及請求本文的確切位元組內容,因此請只將本文序列化一次,並傳送簽署時使用的同一組位元組。
使用 Node.js 傳送已簽署的事件
npm install standardwebhooks
傳入 webhookFetch 函式,其介面須與 fetch 相同。該函式必須在每次建立連線時驗證回呼位址,並封鎖重新導向。
import { Webhook } from "standardwebhooks";
export async function sendEvent(
subscription: { id: string; url: string; secret: string },
event: { eventId: string },
webhookFetch: typeof fetch
) {
const body = JSON.stringify(event);
if (Buffer.byteLength(body, "utf8") > 256 * 1024) {
throw new Error("Event payload exceeds 256 KiB");
}
const signedAt = new Date();
const signer = new Webhook(subscription.secret);
const response = await webhookFetch(subscription.url, {
method: "POST",
redirect: "error",
signal: AbortSignal.timeout(10_000),
headers: {
"Content-Type": "application/json",
"webhook-id": event.eventId,
"webhook-timestamp": String(Math.floor(signedAt.getTime() / 1000)),
"webhook-signature": signer.sign(event.eventId, signedAt, body),
"X-MCP-Subscription-Id": subscription.id,
},
body,
});
return { accepted: response.ok, status: response.status };
}請將 subscription.url 和 subscription.secret 設為訂閱請求中 delivery 物件的對應值。
處理傳送後的回應
2xx 回應表示 ChatGPT 已收到 webhook 請求。ChatGPT 會以非同步方式處理事件。
每個請求只傳送一個事件,完整的請求本文不得超過 256 KiB(262,144 位元組)。ChatGPT 可依任務的批次處理設定,將分別傳送的多個事件合併在同一次任務執行中處理。
遇到暫時性錯誤時,請採用指數退避策略重試,並限制嘗試次數。每次嘗試都要沿用原本的事件 ID,並產生新的簽署時間戳記和簽章。若傳送請求收到 410 或 413 回應,請勿重試。
事件的抵達順序可能與發生順序不同。寫入工具應具備冪等性,以免重複呼叫時重複套用變更。
管理訂閱
在伺服器核定的有效期間內保留訂閱狀態,即使伺服器重新啟動也要保留。在訂閱有效期間內重新檢查使用者的存取權。若存取權遭撤銷,請停止傳送事件。
更新訂閱
ChatGPT 會呼叫 events/subscribe 更新即將到期的訂閱。呼叫會在 refreshBefore 指定的時間之前發出,並使用相同的訂閱識別資訊和上次儲存的游標。請更新現有訂閱,並在 refreshBefore 中傳回新的到期時間。
若省略 ttlMs,請使用伺服器預設的訂閱有效期間。若有提供,該值表示要求的有效期間,以毫秒為單位。核定的有效期間不得超過要求的期間,除非伺服器為避免更新請求過於頻繁而強制設定最短有效期間。
ttlMs: null 表示要求建立不會到期的訂閱。只有在同意該要求時才傳回 refreshBefore: null。否則,請傳回明確的到期時間,並在到期時停止傳送事件。
若更新請求提供新的簽署密鑰,請以新密鑰取代已儲存的密鑰。在短暫的密鑰輪替期間內,請同時使用新舊密鑰簽署請求,並依 Standard Webhooks 格式以空格分隔兩個簽章。
對於可重播的事件,請在訂閱到期或伺服器重新啟動後,使用請求中的 cursor 接續傳送。在訂閱回應和事件承載資料中,傳回的游標不得略過任何尚待傳送的事件。若要求的歷史記錄已無法取得,請傳回 truncated: true。對於不支援重播的事件類型,請傳回 cursor: null。中斷期間錯過的事件無法透過此通訊協定補回。
停止訂閱
處理 events/unsubscribe 時,請使用原始事件名稱、引數和回呼 URL:
{
"jsonrpc": "2.0",
"id": 3,
"method": "events/unsubscribe",
"params": {
"name": "comment.created",
"arguments": {
"document_id": "doc_123"
},
"delivery": {
"mode": "webhook",
"url": "https://receiver.example.com/mcp-events/callback_123"
}
}
}
停止向相符的訂閱傳送事件,並傳回空的結果物件:
{
"jsonrpc": "2.0",
"id": 3,
"result": {}
}
取消訂閱的操作必須具備冪等性,並須確認目前連線的帳戶有權取消該訂閱。
在 ChatGPT 中測試
實作事件方法與 webhook 傳送功能後,請透過外掛程式將 MCP 伺服器連線至 ChatGPT,並測試訂閱的完整生命週期:
-
確認伺服器在宣告支援
events時使用initialize或server/discover,接著確認伺服器收到events/list並傳回預期的事件定義。 -
確認外掛程式頁面同時列出事件和工具。每次變更工具或事件後,都要重新掃描 MCP 伺服器。
外掛程式事件。 外掛程式頁面會一併列出探索到的事件和工具。
-
在 ChatGPT 網頁版中以工作模式開始對話,或在桌面應用程式中選取工作和雲端。請 ChatGPT 訂閱其中一個事件,並指定收到事件時應執行的動作。你也可以使用 dot 進行測試。
-
確認伺服器收到
events/subscribe,且請求包含預期的事件名稱與引數。 -
確認回呼驗證成功,且伺服器已儲存訂閱。
-
在應用程式中觸發符合訂閱條件的事件,並確認傳送事件的 webhook 請求收到
2xx回應。 -
確認 ChatGPT 收到預期的事件資料,並依指示回應。
-
若訂閱設有篩選條件,請觸發不符合條件的事件,並確認伺服器未將該事件傳送給此訂閱。
-
在 ChatGPT 中停止監控。確認伺服器已處理
events/unsubscribe並停止傳送事件。
也請測試下列情況:重複提出訂閱請求、伺服器重新啟動前後的訂閱到期與更新、帳戶中斷連線、對已訂閱資源的存取權遭撤銷、簽章無效,以及重複傳送事件。請分別在啟用和停用批次處理時測試短時間內大量事件湧入的情況。若使用者要求的動作會變更來源應用程式中的資料,請確認該變更所產生的事件不會反覆觸發同一動作而形成回饋迴圈。
通訊協定參考資料:MCP 事件設計草案。