Repository navigation
Conversation
First commit
Willy's feedback
josevalim
reviewed
Sep 30, 2026
| - `cursor` is opaque to the client. The client stores it and passes it back on the next poll. In the request, `null` means "start from now" — the server returns no events and provides a fresh cursor for subsequent polls. In the response, the server MAY return `cursor: null` for an event type that does not support replay; the client then has nothing to persist and always polls with `null` (see *Cursor Lifecycle*). | ||
| - `eventId` enables client-side deduplication across polls (e.g., after a crash/restart). It is **server-assigned**: when the upstream source provides a stable event identifier (Stripe `evt_*`, GitHub delivery GUID, Kafka offset, Gmail message ID), the server SHOULD use that value as `eventId` so that the same upstream event surfaced via multiple paths (e.g., webhook emit and poll backfill) carries the same `eventId` and dedup works. The SDK auto-generates an `eventId` only when the author supplies none. | ||
| - `maxEvents` is an optional cap on the number of events returned. If more events are available than the limit, the server returns a partial batch with an intermediate cursor and sets `hasMore: true`. The client SHOULD poll again immediately (ignoring `nextPollMs`) to drain the backlog. If omitted, the server uses its own default limit. | ||
| - `waitMs` is an optional non-negative integer specifying how long the client permits the server to hold the request while waiting for matching events. When omitted or set to `0`, the server responds immediately. When greater than `0`, the server MAY hold the request for up to the requested duration. The server MUST respond as soon as one or more matching events become available and MUST initiate a response no later than the requested duration. The server MAY impose a lower implementation-defined maximum. Absent such a constraint, the server SHOULD NOT return an empty `events` array before `waitMs` elapses — accepting `waitMs` while routinely returning early empty results would behave like short polling despite advertising a long poll; a genuine implementation or transport constraint (e.g. a proxy or connection timeout) is a valid reason to return earlier. |
There was a problem hiding this comment.
I'd tighten this a bit:
- The server may want to collect/batch events before replying to reduce network pressure, so we should not impose immediate return. This alongside
nextPollMsgives plenty of control on how to do that - There is a bit of duplication in "the server MAY hold the request for up to the requested duration" and "The server MAY impose a lower implementation-defined maximum"
- We should acknowledge that, although empty events MUST be returned, the client must consider failures as an attempt to reconnect rather than a permanent failure
Suggested change
| - `waitMs` is an optional non-negative integer specifying how long the client permits the server to hold the request while waiting for matching events. When omitted or set to `0`, the server responds immediately. When greater than `0`, the server MAY hold the request for up to the requested duration. The server MUST respond as soon as one or more matching events become available and MUST initiate a response no later than the requested duration. The server MAY impose a lower implementation-defined maximum. Absent such a constraint, the server SHOULD NOT return an empty `events` array before `waitMs` elapses — accepting `waitMs` while routinely returning early empty results would behave like short polling despite advertising a long poll; a genuine implementation or transport constraint (e.g. a proxy or connection timeout) is a valid reason to return earlier. | |
| - `waitMs` is an optional non-negative integer specifying how long the client permits the server to hold the request while waiting for matching events. When omitted or set to `0`, the server responds immediately. When greater than `0`, the server MAY hold the request for up to the requested duration. The server MUST initiate a response with one or more matching events no later than the requested duration. In case there are no matching events, an empty `events` array MUST be returned. However, the client MUST prepare for the cases the connection is closed with no response, due to proxies, connection losses, and other external factors. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an optional waitMs parameter to events/poll, turning it into a bounded long poll instead of a plain immediate request/response. Also fixes a few normative inconsistencies found in review (MUST/SHOULD wording, scope of the "no notifications" rule, nextPollMs floor interaction).
Motivation and Context
This extends MCP to support ONVIF camera semantics, giving agents access to video surveillance devices. Surveillance events are infrequent but must be delivered promptly, and camera networks often sit behind routers/firewalls that drop idle connections. Long polling is the mechanism our industry has found most robust for this: it keeps the connection active while waiting, avoiding idle timeouts, without needing push/webhook infrastructure.
How Has This Been Tested?
Design-sketch document, not an implementation. ONVIF plans to have a hackthon in November, if the solution is accepted.
Breaking Changes
None
Types of changes
Checklist
Additional context
Poll stays response-only per subscription: events go only in the events/poll response, never as notifications on that connection — other subscriptions (push/webhook) are unaffected. The 1000ms nextPollMs floor now applies only after an immediate/premature empty poll, not after a completed long poll, avoiding a spurious blind interval.