Skip to content

Support long polling in events/poll via waitMs - #5

Open
ocampana wants to merge 3 commits into
modelcontextprotocol:mainfrom
ocampana:onvif-proposal
Open

ocampana wants to merge 3 commits into
modelcontextprotocol:mainfrom
ocampana:onvif-proposal

Conversation

@ocampana

Copy link
Copy Markdown

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

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

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.

@ocampana ocampana closed this Sep 11, 2026
@ocampana ocampana reopened this Sep 11, 2026
@ocampana
ocampana requested a review from a team September 11, 2026 09:39
- `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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd tighten this a bit:

  1. The server may want to collect/batch events before replying to reduce network pressure, so we should not impose immediate return. This alongside nextPollMs gives plenty of control on how to do that
  2. 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"
  3. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants