如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

MCP 事件

为您的 MCP 服务器实现事件订阅和 webhook 投递。

通过 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 控制通知。

工作原理

  1. 您的服务器列出它支持的事件。
  2. 用户告诉 ChatGPT 要监控什么,以及如何响应。
  3. ChatGPT 通过您的 MCP 服务器订阅事件,并提供回调 URL 和签名密钥。
  4. 您的服务器将符合订阅条件的事件发送到该 URL。
  5. 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
  }
}

接受订阅前,请完成以下检查和操作:

  1. 确认用户有权使用请求中的参数订阅该事件。
  2. 根据事件定义校验事件名称和参数。签名密钥必须以 whsec_ 开头,其 base64 编码部分解码后必须为 24 至 64 字节。
  3. 校验并验证回调 URL。
  4. 保存订阅及其所有者、筛选条件、回调 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 发送已签名的事件

安装 Standard Webhooks 库:

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,并测试订阅的完整生命周期:

  1. 确认服务器声明支持 events,且该声明包含在 initialize 或 server/discover 的响应中。然后确认服务器收到 events/list 请求并返回预期的事件定义。

  2. 确认插件页面同时列出了您的事件和工具。每次更改工具或事件后,都要重新扫描 MCP 服务器。

    插件详情页同时列出了 message.created 和 comment.created 事件以及 MCP 工具。

    插件事件。 插件页面会同时列出已发现的事件和工具。

  3. 在 ChatGPT 网页版中以工作模式开始聊天,或在桌面应用中选择工作和云端。让 ChatGPT 订阅您的一个事件,并指定收到事件后应执行的操作。您也可以使用 dot 进行测试。

  4. 确认服务器收到的 events/subscribe 请求包含预期的事件名称和参数。

  5. 确认回调验证成功,且服务器已保存订阅。

  6. 在您的应用中触发符合订阅条件的事件,并确认 webhook 投递请求收到 2xx 响应。

  7. 确认 ChatGPT 收到预期的事件数据,并按指令响应。

  8. 对于设有筛选条件的订阅,触发一个不符合条件的事件,确认服务器没有向该订阅投递此事件。

  9. 在 ChatGPT 中停止监控。确认服务器处理了 events/unsubscribe 请求并停止投递。

还应测试以下情况:重复发起订阅请求、服务器重启前后的订阅到期与刷新、账号断开连接、用户对已订阅资源的访问权限被撤销、签名无效、重复投递,以及启用和禁用批处理时短时间内大量事件涌入。如果用户请求的操作会更改源应用中的数据,请确认由此产生的事件不会形成反馈循环。

协议参考:MCP 事件设计草案。