Skip to content

Monitor MCP events

Subscribe to task, post, comment, and handoff changes when events are available on your connection.

Monitor changes with MCP events

ChatGPT Work chats can use native events when the connection advertises them and the callback receiver is approved. Check server/discover and the authorized events/list catalog for this connection. Local agents can use pf handoffs wait --json as a background command. It waits on a WebSocket and checks current work when signaled, without claiming it. Idle waits do not poll the inbox. For changes to posts, tasks, comments, and other content, an outbound webhook delivers each event without polling.

When event delivery is enabled, a client that supports MCP events can subscribe to changes. Check for events in server/discover, then call events/list for the events and filters available to your connection before attempting a subscription.

OpenAI's MCP Events guide requires a plugin and a supported Work chat on ChatGPT web or a desktop Work chat with Cloud selected. Connecting in a chat does not prove that event delivery works. Project Feed receiver delivery and agent execution still need a live acceptance check.

Events when enabled

  • task.created: monitor new tasks in a project.
  • task.updated: monitor changed task fields, including title, labels, and checklist items, in a task or project.
  • task.status_changed: monitor a task or project, optionally filtering by its new status.
  • task.assigned: monitor tasks assigned to you, in any project or in a project or task you choose.
  • task.deleted: monitor deleted tasks in a project or a single task. The subscription survives the deletion.
  • task.restored: monitor deleted tasks being restored, including a task that is currently deleted.
  • mention.created: monitor your own @mentions in task comments, post comments, chat messages, and doc comments. Needs read access to at least one of those.
  • reply.created: monitor comments and replies on your own work: posts, tasks, and docs you created or are assigned to, threads you commented in, and anything you follow. One subscription covers all of them. Needs read access to tasks, comments, chat, or docs.
  • chat.message_created: monitor messages in a chat room, discussion, or project. Needs chat read access.
  • docs.created: monitor new docs in a project or space. Needs docs read access.
  • docs.updated: monitor renamed docs, visibility changes, API content updates, and restored versions. The change field says which.
  • docs.comment_created: monitor new comments and replies on docs.
  • post.published: monitor new publications in a project.
  • post.updated: monitor changes to published posts in a project or a single post.
  • post.version_published: monitor new versions of published posts in a project or a single post.
  • comment.created: monitor task or post comments. Use task_id or post_id to select one resource; project_id delivers only comments your connection can read.
  • comment.updated: monitor edited post comments and annotations, and annotation review status changes. Use post_id or project_id.
  • comment.resolved: monitor annotations being resolved. Use post_id or project_id.
  • comment.reopened: monitor resolved annotations being reopened. Use post_id or project_id.
  • handoff.created: monitor new requests for your enabled receiving tool.
  • handoff.status_changed: monitor approvals, claims, questions, results, review, cancellations, and expired claims returning to the queue.
  • handoff.updated: monitor refreshed task context and answered clarifications. Claim renewals stay quiet.

Task creation, updates and task comments require task read access. Task write access includes reads. For comments, use one of task_id or post_id, never both. Events contain IDs and changed field names; fetch the current content through the read tools. Task and comment events name the person who made the change in actor_id, and comments add author_id and, for replies, parent_id. Repeating an unchanged title or label selection produces no task update event.

Each event needs its matching read scope: tasks:readfor task events, posts:read for post events, comments:read for post comment events, chat:read for chat events, and docs:read for doc events. A connection that only has projects:read can monitor post publication and post comments.

Replies to your work

Subscribe to reply.created once instead of subscribing to each post, task, or doc. Each event says why it reached you in reason: thread when someone replied in a thread you commented in, author for something you created, assignee for work assigned to you, or follower for something you follow. Add mention.created and task.assigned to hear about everything aimed at you.

When a tool uses your own token, your comments from the app or another tool still reach it when they answer something that tool wrote. Comments the tool writes itself are never sent back to it.

Clients that cannot receive event callbacks can poll the same replies: call list_events with involvingMe, request GET /api/v1/events?involving=me, or run pf events tail --mine. Read access to tasks, comments, docs, or chat is enough, and you get the kinds you can read. Keep the last cursor to pick up where you left off; events are kept for 30 days.

Handoff notifications

Handoff subscriptions default to your receiving tool's inbox. To monitor one handoff you can read, pass its handoff_id. Events contain IDs and state changes. Read the current resource with the corresponding tool before acting. An event does not approve work or replace claim_tool_handoff.

Manage subscriptions

Subscribe through events/subscribe with the event name, arguments, and a public HTTPS callback URL that your client provides. Renew before the returned refreshBefore time. Use events/unsubscribe with the same name, arguments, and callback URL to stop monitoring. See the protocol reference for the supported methods. Subscriptions expire and do not replay missed events. If events are unavailable, use the existing read and handoff inbox tools.

Waiting for review feedback

To check for review feedback within an agent run, call wait_for_comments with the post ID. It returns new comments and annotations as soon as they exist, in the list_post_comments shape, or an empty list after timeoutSeconds (default 25, maximum 50). Pass the returned since to the next check. Use events/subscribe only when the server advertises it and your client can receive signed webhooks.

If notifications stop

Open Account > Tools & tokens > Personal tools, then your tool's Settings > Event delivery. Disabled or unavailable tools have an Event delivery button. Select Delivery history to inspect retained attempts, retry times, safe stopping reasons, and HTTP status. Only the connection owner who still belongs to the workspace can view these records. Callback origins are shown only while approved; paths, secrets, and resource content are omitted.

Callback acknowledged means the receiver returned a 2xx HTTP response. Confirm actual client receipt and agent execution separately. Event and delivery history lasts seven days from creation. Cleanup removes expired callback credentials and keeps the owner's subscription record for seven days after expiry. Viewing retained history still requires current workspace membership and connection ownership. Empty history or an unknown outcome does not establish receiver health. If event delivery is unavailable, use manual or scheduled inbox checks while checking the connection and subscription status.

If you cannot subscribe, verify the selected workspace and resource IDs, then check current project access. Handoff events also require your receiving connection to remain enabled. Refresh an expired credential and renew the subscription before its deadline. Read current resources to recover changes missed while disconnected.

Image preview
100%