通过 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 2.0 HTTP(协议版本 2026-07-28)使用 MCP 事件。请在插件中配置服务器,持久化存储订阅,并确保服务器可以通过 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 和服务器为订阅设定的到期时间:
{
"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 事件设计草案。