Mit MCP Events kann ChatGPT Updates von deinem MCP-Server abonnieren, etwa neue Nachrichten, Änderungen an Inhalten oder Statusänderungen. Wer ein Abonnement einrichtet, legt fest, was ChatGPT überwachen und wie es auf ein Update reagieren soll.
| Anwendungsfall | Nutzeranfrage | MCP-Ereignis |
|---|---|---|
| Aus Feedback Pull Requests erstellen | Achte in #product-feedback auf Fehlerberichte und eröffne für die gemeldeten Fehler Pull Requests als Entwürfe mit Korrekturen und Tests. | message.created, gefiltert nach channel_id |
| Feedback zu einem Dokument umsetzen | Achte in diesem Dokument auf Review-Kommentare und setze alle darin angeforderten Änderungen um. | comment.created, gefiltert nach document_id |
Bevor du beginnst
MCP Events ist in ChatGPT im Web in Chats im Work-Modus verfügbar. In der Desktop-App kannst du MCP Events in Chats im Work-Modus nutzen, wenn Cloud ausgewählt ist. MCP Events funktioniert auch mit dots. Es gelten die Workspace-Einstellungen für Plugins und ereignisgesteuerte Aufgaben.
ChatGPT unterstützt MCP Events über Streamable HTTP mit initialize oder über MCP 2.0 HTTP (Protokollversion 2026-07-28). Konfiguriere deinen Server in deinem Plugin. Stelle sicher, dass der Server Abonnements dauerhaft speichern und Callback-URLs über ausgehende HTTPS-Verbindungen erreichen kann.
ChatGPT unterstützt die Zustellung per Webhook und die Callback-Verifizierung gemäß dem Entwurf der Spezifikation für MCP Events. Diese Integration unterstützt weder Polling noch Streaming. Auch die im Entwurf vorgesehenen Steuermeldungen gap und terminated werden nicht unterstützt.
So funktioniert es
- Dein Server listet die unterstützten Ereignisse auf.
- Die Person, die das Abonnement einrichtet, sagt ChatGPT, was es überwachen und wie es reagieren soll.
- ChatGPT richtet das Abonnement über deinen MCP-Server ein und übermittelt eine Callback-URL und einen geheimen Signaturschlüssel.
- Dein Server sendet passende Ereignisse an diese URL.
- ChatGPT empfängt das Ereignis in dem Chat, für den das Abonnement gilt, und reagiert gemäß den Anweisungen der Person, die das Abonnement eingerichtet hat.
Ereignisunterstützung bekannt geben
Anhand der vom Server gemeldeten Funktionen erkennt ChatGPT, ob der Server Ereignisse unterstützt. Füge bei MCP-Versionen mit Initialisierung events zu den Funktionen hinzu, die dein Server in der Antwort auf initialize zurückgibt.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": {
"tools": {},
"events": {}
},
"serverInfo": {
"name": "example-server",
"version": "1.0.0"
}
}
}
Füge für MCP 2.0 (Protokollversion 2026-07-28) events zu den Funktionen hinzu, die dein Server in der Antwort auf server/discover zurückgibt.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": {},
"events": {}
}
}
}
Implementiere diese drei Ereignismethoden am selben authentifizierten MCP-Endpunkt wie deine Tools.
| Methode | Verhalten des Servers |
|---|---|
events/list |
Beschreibt verfügbare Ereignisse und ihre Filter. |
events/subscribe |
Erstellt oder verlängert ein Abonnement. |
events/unsubscribe |
Beendet ein Abonnement. |
Ein Ereignis definieren
Eine Ereignisdefinition teilt ChatGPT mit, welche Ereignisse sich abonnieren lassen und welche Filter verfügbar sind. Gib diese Definitionen über events/list zurück. Jede Definition enthält den Ereignisnamen, die unterstützten Zustellarten, die Argumente für das Abonnement und das Schema der Nutzdaten.
{
"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 beschreibt die Argumente, die ChatGPT beim Abonnieren übergibt. payloadSchema beschreibt das data-Objekt jedes zugestellten Ereignisses.
Verwende stabile Ereignisnamen und präzise Beschreibungen. Biete Filter an, etwa nach Dokument-, Projekt- oder Warteschlangen-ID, und wende sie vor der Zustellung auf deinem Server an. Gib nur Ereignisse zurück, die für das verbundene Konto sichtbar sein dürfen.
Wenn sich der Katalog über mehrere Seiten erstreckt, gib nextCursor zurück und akzeptiere diesen Wert als cursor in der nächsten Anfrage an events/list.
Ein Abonnement erstellen
Wenn jemand ChatGPT bittet, ein Ereignis zu überwachen, ruft ChatGPT events/subscribe mit dem Ereignisnamen, den Filterargumenten und dem Webhook-Ziel auf.
{
"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
}
}
Führe die folgenden Schritte aus, bevor du das Abonnement annimmst.
- Prüfe, ob die anfragende Person das angeforderte Ereignis mit den angegebenen Argumenten abonnieren darf.
- Gleiche den Ereignisnamen und die Argumente mit deiner Ereignisdefinition ab. Verlange einen geheimen Signaturschlüssel mit dem Präfix
whsec_, dessen Base64-Wert nach dem Dekodieren 24–64 Byte lang ist. - Validiere und verifiziere die Callback-URL.
- Speichere das Abonnement zusammen mit Angaben dazu, wem es gehört, sowie mit seinen Filtern, der Callback-URL, dem geheimen Signaturschlüssel und dem Ablaufzeitpunkt.
Leite aus der authentifizierten Identität, der Callback-URL, dem Ereignisnamen und den Argumenten eine deterministische Abonnement-ID ab. Gib sie zusammen mit dem vom Server festgelegten Ablaufzeitpunkt zurück.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"id": "sub_123",
"refreshBefore": "2026-10-02T12:00:00Z",
"cursor": null,
"truncated": false
}
}
Setze refreshBefore auf den Ablaufzeitpunkt, den dein Server für das Abonnement festlegt. Gib für Ereignistypen, die keine erneute Wiedergabe unterstützen, cursor: null zurück.
Gestalte das Erstellen von Abonnements idempotent. Wenn ein Abonnement mit derselben Identität bereits existiert, aktualisiere es. Vergleiche die Argumente in kanonischer JSON-Darstellung, damit eine andere Reihenfolge der Objektschlüssel nicht zu doppelten Abonnements führt.
Den Callback verifizieren
Verifiziere den Callback, bevor du Anwendungsdaten sendest. Sende dazu eine signierte Anfrage mit einer neuen, kurzzeitig gültigen Challenge, die sich nur einmal verwenden lässt.
{
"type": "verification",
"challenge": "a-single-use-random-value"
}
Gib der Verifizierungsanfrage eine eindeutige webhook-id, etwa msg_verification_123, und signiere den Anfragekörper mit dem geheimen Schlüssel des Abonnements. Sende die Header webhook-timestamp, webhook-signature und X-MCP-Subscription-Id mit. Bei Erfolg gibt ChatGPT die Challenge unverändert zurück.
{
"challenge": "a-single-use-random-value"
}
Verlange eine 2xx-Antwort und vergleiche die zurückgegebene Challenge in konstanter Zeit mit dem ursprünglichen Wert, bevor du die Zustellung aktivierst. Speichere erfolgreiche Verifizierungen für begrenzte Zeit pro authentifizierter Identität und Callback-URL zwischen. So lösen wiederholte Abonnementanfragen keine weiteren Challenges aus. Schlägt die Verifizierung fehl, gib den JSON-RPC-Fehler -32015 (CallbackEndpointError) zurück und benenne die Fehlerkategorie in data.reason, etwa challenge_failed oder timeout.
Lasse für Callbacks nur HTTPS zu. Löse beim Verbindungsaufbau den Zielhostnamen auf und validiere die Zieladressen. Verbinde dich dann mit der validierten Adresse und verwende für die TLS-Verifizierung weiterhin den ursprünglichen Hostnamen. Sperre private, lokale und andere nicht öffentliche Adressen und folge keinen Weiterleitungen. Führe diese Prüfungen sowohl bei Verifizierungsanfragen als auch bei der Zustellung von Ereignissen durch.
Ein Ereignis senden
Wenn ein neuer Kommentar zu einem aktiven Abonnement passt, sende ein einzelnes Ereignisobjekt per POST an die Callback-URL dieses Abonnements.
{
"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
}
Verwende eine eindeutige Ereignis-ID und behalte sie bei erneuten Zustellversuchen bei. Gib in timestamp den Zeitpunkt des Ereignisses als ISO-8601-Zeitstempel mit Zeitzone an. Der Wert von name muss dem Namen des abonnierten Ereignisses entsprechen. Das data-Objekt muss dessen payloadSchema entsprechen. Lege Anwendungsfelder innerhalb von data ab. Ein Feld type auf der obersten Ebene kennzeichnet eine Steuermeldung des Protokolls.
Sende bei großen Datensätzen eine Zusammenfassung und stelle ein Tool bereit, mit dem sich der vollständige Datensatz abrufen lässt. Behandle Kommentare und andere von Personen verfasste Texte als Daten. Füge den Nutzdaten des Ereignisses keine Anweisungen hinzu, die dem Modell vorgeben, wie es sich verhalten soll.
Die Anfrage signieren
ChatGPT verifiziert Zustellungen mit Standard Webhooks. Sende die folgenden Header mit.
| Header | Wert |
|---|---|
Content-Type |
application/json |
webhook-id |
Derselbe Wert wie eventId im Anfragekörper. |
webhook-timestamp |
Der Signaturzeitpunkt als Unix-Zeit in Sekunden. |
webhook-signature |
Die HMAC-Signatur gemäß Standard Webhooks. |
X-MCP-Subscription-Id |
Die von events/subscribe zurückgegebene ID. |
Signiere Zustellungen gemäß Standard Webhooks mit dem geheimen Signaturschlüssel des Abonnements. Die Signatur umfasst die Ereignis-ID, den Signaturzeitstempel und die exakte Bytefolge des Anfragekörpers. Serialisiere den Anfragekörper daher nur einmal und sende genau diese Bytes.
Ein signiertes Ereignis mit Node.js senden
Installiere die Bibliothek für Standard Webhooks.
npm install standardwebhooks
Übergib eine Funktion webhookFetch mit derselben Schnittstelle wie fetch. Sie muss bei jedem Verbindungsaufbau die Callback-Adressen validieren und Weiterleitungen blockieren.
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 };
}Setze subscription.url und subscription.secret auf die entsprechenden Werte aus dem delivery-Objekt der Abonnementanfrage.
Antworten auf Zustellversuche verarbeiten
Eine 2xx-Antwort bestätigt den Empfang des Webhooks. ChatGPT verarbeitet das Ereignis asynchron.
Sende pro Anfrage ein Ereignis. Der gesamte Anfragekörper darf höchstens 256 KiB (262.144 Byte) groß sein. Je nach den Einstellungen der Aufgabe zur Bündelung von Ereignissen kann ChatGPT separat zugestellte Ereignisse in einem einzigen Aufgabendurchlauf verarbeiten.
Wiederhole die Zustellung bei vorübergehenden Fehlern mit exponentiell wachsenden Wartezeiten und einer begrenzten Anzahl von Versuchen. Behalte die Ereignis-ID bei und erzeuge für jeden Versuch einen neuen Signaturzeitstempel und eine neue Signatur. Wiederhole die Zustellung nicht, wenn die Antwort den Statuscode 410 oder 413 enthält.
Ereignisse können in anderer Reihenfolge eintreffen, als sie aufgetreten sind. Gestalte Tools mit Schreibzugriff idempotent, damit wiederholte Aufrufe Änderungen nicht mehrfach ausführen.
Abonnements verwalten
Speichere den Zustand des Abonnements für die gesamte gewährte Laufzeit, auch über Serverneustarts hinweg. Prüfe während der Laufzeit erneut, ob die Person, die das Abonnement eingerichtet hat, noch zugriffsberechtigt ist. Beende die Zustellung, wenn ihr der Zugriff entzogen wurde.
Ein Abonnement verlängern
ChatGPT verlängert auslaufende Abonnements, indem es events/subscribe vor dem in refreshBefore angegebenen Zeitpunkt aufruft. Dabei verwendet es dieselbe Abonnementidentität und den zuletzt gespeicherten Cursor. Aktualisiere das bestehende Abonnement und gib den neuen Ablaufzeitpunkt in refreshBefore zurück.
Fehlt ttlMs, verwende die Standardlaufzeit deines Servers für Abonnements. Ist der Wert angegeben, bezeichnet er die gewünschte Laufzeit in Millisekunden. Gewähre höchstens diese Laufzeit, es sei denn, du setzt eine Mindestlaufzeit durch, um übermäßig häufige Verlängerungsanfragen zu verhindern.
Mit ttlMs: null wird ein unbefristetes Abonnement angefordert. Gib refreshBefore: null nur zurück, wenn du dieser Anforderung entsprichst. Gib andernfalls einen konkreten Ablaufzeitpunkt zurück und beende die Zustellung, sobald dieser erreicht ist.
Enthält die Verlängerungsanfrage einen neuen geheimen Signaturschlüssel, ersetze den gespeicherten Schlüssel. Signiere während einer kurzen Übergangszeit mit dem alten und dem neuen Schlüssel und trenne die Signaturen gemäß Standard Webhooks durch ein Leerzeichen.
Bei Ereignissen, die sich erneut wiedergeben lassen, verwende den cursor aus der Anfrage, um die Zustellung nach Ablauf eines Abonnements oder nach einem Serverneustart fortzusetzen. Gib in Antworten auf Abonnementanfragen und in den Nutzdaten von Ereignissen einen Cursor zurück, der keine noch ausstehenden Ereignisse überspringt. Gib truncated: true zurück, wenn der angeforderte Verlauf nicht mehr verfügbar ist. Gib für Ereignistypen ohne Wiedergabefunktion cursor: null zurück. Bei einer Unterbrechung verpasste Ereignisse lassen sich in diesem Fall über das Protokoll nicht nachträglich abrufen.
Ein Abonnement beenden
Verarbeite events/unsubscribe anhand des ursprünglichen Ereignisnamens, der ursprünglichen Argumente und der ursprünglichen Callback-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"
}
}
}
Beende die Zustellung von Ereignissen für das passende Abonnement und gib ein leeres Ergebnis zurück.
{
"jsonrpc": "2.0",
"id": 3,
"result": {}
}
Gestalte das Beenden eines Abonnements idempotent und prüfe, ob das verbundene Konto dazu berechtigt ist.
In ChatGPT testen
Sobald du die Ereignismethoden und die Zustellung per Webhook implementiert hast, verbinde deinen MCP-Server über ein Plugin mit ChatGPT und teste den gesamten Lebenszyklus eines Abonnements.
-
Prüfe, ob dein Server
eventsüberinitializeoderserver/discoverals unterstützte Funktion meldet, anschließendevents/listempfängt und die erwarteten Ereignisdefinitionen zurückgibt. -
Prüfe, ob deine Ereignisse auf der Plugin-Seite neben deinen Tools erscheinen. Lass deinen MCP-Server jedes Mal neu scannen, wenn du seine Tools oder Ereignisse änderst.
Plugin-Ereignisse. Erkannte Ereignisse erscheinen neben den Tools auf der Plugin-Seite.
-
Starte in der Webversion von ChatGPT einen Chat im Work-Modus oder wähle in der Desktop-App Work und Cloud aus. Bitte ChatGPT, eines deiner Ereignisse zu abonnieren, und gib an, was es tun soll, wenn ein Ereignis eintrifft. Du kannst den Test auch mit einem dot durchführen.
-
Prüfe, ob dein Server
events/subscribemit dem erwarteten Ereignisnamen und den erwarteten Argumenten empfängt. -
Prüfe, ob die Callback-Verifizierung erfolgreich ist und der Server das Abonnement speichert.
-
Löse in deiner App ein passendes Ereignis aus und prüfe, ob der Server für die Webhook-Zustellung eine
2xx-Antwort erhält. -
Prüfe, ob ChatGPT die erwarteten Ereignisdaten empfängt und wie angewiesen reagiert.
-
Löse bei einem Abonnement mit Filtern ein Ereignis aus, das die Filterkriterien nicht erfüllt. Prüfe, ob die Zustellung für dieses Abonnement wie erwartet ausbleibt.
-
Beende die Überwachung in ChatGPT. Prüfe, ob dein Server
events/unsubscribeverarbeitet und die Zustellung beendet.
Teste auch wiederholte Abonnementanfragen, das Ablaufen und Verlängern von Abonnements über einen Serverneustart hinweg, das Trennen der Kontoverbindung und den Entzug von Zugriffsrechten für eine abonnierte Ressource. Teste außerdem ungültige Signaturen, doppelte Zustellungen und viele kurz hintereinander eintreffende Ereignisse sowohl mit aktivierter als auch mit deaktivierter Bündelung. Wenn die angeforderte Aktion Daten in der Quell-App ändert, prüfe, dass die daraus entstehenden Ereignisse keine Rückkopplungsschleife auslösen.
Protokollreferenz: Entwurf für MCP Events.