Skip to content

MCP Events client with poll delivery (SEP-3415) - #1076

Draft
olaservo wants to merge 21 commits into
evalstate:mainfrom
olaservo:feat/mcp-events-poll
Draft

olaservo wants to merge 21 commits into
evalstate:mainfrom
olaservo:feat/mcp-events-poll

Conversation

@olaservo

@olaservo olaservo commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Draft PR for feedback. Adds client support for the MCP Events Extension (SEP-3415, io.modelcontextprotocol/events) with poll delivery. An agent can subscribe to event types a server offers, and the events reach the model as untrusted data before its next model call. A subscription can opt in to waking an idle agent, so fast-agent go can sit at the prompt and start a turn when an event arrives.

Push (events/stream) and webhook delivery are not included.

What is in it

  • Discovery and requests. The client advertises the extension, and events/list and events/poll are available on the aggregator for servers that declare it. The wire models are local (mcp/events_extension.py), because the Python SDK has no events support on main.
  • Subscriptions (mcp/events_subscriptions.py). One poll task per subscription. It follows the server's nextPollMs with a 1 s floor, polls again at once on hasMore, drops duplicate eventIds and reports truncated as a gap. NotFound re-lists once and resubscribes from now, Forbidden ends the subscription, and other errors back off and keep the cursor. Subscriptions live in memory for the life of the process.
  • Delivery to the model. ToolRunner drains the inbox before each model call and appends one user message that marks the payloads as untrusted data. Server text is escaped, so an event cannot close its wrapper.
  • /events in the TUI. list, subscribe <server> <event> [key=value ...] [--wake], poll <id> and unsubscribe <id>|all, plus an event count in the toolbar.
  • Wake. Opt-in per subscription. When a wake subscription has an event, the idle prompt ends and a turn starts with the event message as its input. Text typed so far comes back in the next prompt. From code, wait_for_wake() does the same job for a driver loop.
  • Declared subscriptions. An events: list on a server's settings, also accepted in AgentCard mcp_connect entries. They start when the server is attached. Detaching a server ends its subscriptions.
  • Docs and example. docs/docs/mcp/events.md, and examples/mcp/events/ with a small jobs server and a driver that runs one turn per wake. The example runs with the passthrough model.

Choices you may want to push back on

  • Wake is off unless a subscription asks for it. A subscribed server can put text in front of the model, and with wake it can do that while nobody is watching. The docs page says so.
  • Nothing persists. A stored subscription would resume in later sessions and inject events into an unrelated conversation. Saving subscriptions with the session would avoid that. It is not built.
  • Local wire models. python-sdk#3822 adds poll and webhook support to the SDK. If it merges, these models and the poll loop should be compared with it and probably replaced.
  • TUI only. /events is not on ACP, and fast-agent serve is not woken.
  • events/list is read when subscribing. A changed event type is noticed only when a poll fails.

Validation

Windows 11, Python 3.14.

  • scripts/format.py --check, scripts/lint.py, and the CPD and internal-resources checks pass. scripts/typecheck.py reports 62 diagnostics, the same as main on this machine.
  • Unit suite: many POSIX-only tests fail on main on Windows. The branch's failing set contains nothing that passes on main.
  • The events unit tests pass, and so do the two integration tests in tests/integration/mcp_2026/test_modern_events.py, which attach the example's jobs server over stdio.
  • Real use, on earlier commits of this branch:

Not yet run: Events with programmatic tool calling on (the example turns it off). The last five commits have not been tested with real servers yet.

(Generated by Claude Code and edited by me)

olaservo and others added 18 commits November 12, 2026 05:36
Adds local wire models for SEP-3415 events/list and events/poll, since
the pinned MCP SDK has no Events types. The client now advertises
io.modelcontextprotocol/events in its capabilities.

MCPClientConnection and MCPAggregator gain list_events and poll_events.
The aggregator rejects both for servers that did not declare the
extension. Poll requests send the Mcp-Name header the SEP requires.

Push and webhook delivery are not implemented.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
EventSubscriptionManager runs one events/poll loop per subscription. It
follows nextPollMs with a 1000 ms floor, polls again at once on hasMore,
drops repeated event ids, and reports truncation as a gap. NotFound and
Unsupported trigger one re-list and resubscribe. Forbidden ends the
subscription. Other failures back off and keep the cursor.

Delivered events wait in an inbox. The tool loop appends them to the
next model call as a user message that marks the payload as untrusted
data. A subscription's saved cursor advances only when its events have
been consumed, so a restart replays anything still in the inbox.

Each MCPAggregator owns a manager, reached through `aggregator.events`.
JsonEventSubscriptionStore can persist subscriptions, but nothing
configures a store path yet.

Adds a poll-only events test server built on the SDK server Extension
API, and an integration test that drives it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
/events shows current subscriptions. `/events list [server]` shows the
event types attached servers offer, with their argument names.
`/events subscribe <server> <event> [key=value ...]` starts a poll
subscription, and `/events unsubscribe <id>|all` stops one. Arguments
may also be given as one JSON object.

Each event that reaches the inbox adds to an "event" count in the
prompt toolbar.

The command is TUI-only, like /process. Subscriptions stay in memory
and end with the process.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A subscription made with wake=True marks its arrivals for
EventSubscriptionManager.wait_for_wake(), which a host awaits to start a
turn in an idle agent. The flag is off by default because event payloads
are untrusted. It is saved with the subscription and restored with it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
examples/mcp/events/event_loop.py subscribes with wake set, waits on
wait_for_wake() and starts a turn for each arrival. Its defaults play a
Forge seat through forge-mcp-server. Run against the events test server
with the passthrough model.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
--export runs `fast-agent export latest` when the loop stops. Usage is
logged after each turn from the agent's usage accumulator.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A provider failure comes back from send() as a reply on the error
channel, so the turn was lost and the agent waited for an event that
had already been delivered. The loop now retries such a turn with a
backoff and drops the wake-up after the last attempt.

Also: --stop-count for a match of several games, --finish for a closing
turn, export by session id, and with --fresh the export is every turn's
messages, since clearing the conversation empties the saved session.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The loop waited for events that could not arrive, because the opening turn is what joins the server-side session. Observed with a 402 from the provider on every attempt.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LjQQxDUxmGXpywANoTFyuC
GLM-5.3-Flash and some other models default it on under POSIX. Events were built and tested with direct tool calls.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LjQQxDUxmGXpywANoTFyuC
poll_now(key) polls a subscription at once from the cursor it holds. It ends the wait between polls, including an error backoff of up to 300 seconds.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An event from a subscription with wake set ends the idle prompt and starts a turn whose input is the event message. Text typed so far is put back in the next prompt. Only the agent shown in the prompt is woken.

/events subscribe takes --wake, /events shows the flag, and /events poll <id> calls poll_now.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A server entry takes an events list of name, arguments and wake. The aggregator subscribes when the server is attached, at startup or at runtime. AgentCard mcp_connect entries accept the same list. A declared event type the server does not offer is logged and skipped.

Provider-managed servers reject the field, since the client does the polling.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Nothing called JsonEventSubscriptionStore or restore(), since subscriptions stay in memory. With no store, the separate consumed cursor has no reader, so a subscription keeps one cursor, the one its next poll resumes from.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An eventId or timestamp containing a quote could add attributes to the <mcp-event> tag, and a payload string containing </mcp-event> closed the wrapper early. Attribute values and detail text are now HTML-escaped, and </ in the JSON body is written as <\/.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The poll loops of a detached server kept running and backed off for ever.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The driver defaulted to a Forge server on a fixed local port. It now defaults to a small jobs server beside it, started over stdio by the example config, and wakes on the subscriptions that config declares. --stop-kind becomes --stop-on key=value and the wake prompt is neutral, with --wake-prompt to set it.

The jobs server is the one the integration tests used, moved here. The tests attach it over stdio, so they no longer start a server process, pick a port, or replace the aggregator's subscription manager.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@olaservo olaservo changed the title Feat/mcp events poll MCP Events client with poll delivery (SEP-3415) Nov 14, 2026
olaservo and others added 3 commits November 15, 2026 14:48
Every agent that attached a server subscribed to the events its settings declare, at load. Observed with five AgentCards attaching one server and one agent in use: the server saw five polls per event, and the four unused agents queued events nothing would read.

Declared subscriptions now start at the agent's first turn, or when its prompt first waits for input. A host that needs them before its first turn calls start_configured_events(), as the example does. A server attached after that subscribes on attach, as before.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The usage line gave the context size and a running total that was None when any model call lacked a count, and --fresh reset it at each wake-up. Each turn now logs its own input, cached and output tokens with the model and tool call counts, and the loop logs the run total when it stops. --usage writes both as JSON.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A subscription keeps polling while its agent is idle, and the inbox had
no limit. When the inbox is full the oldest item is dropped. The next
drain starts with a gap notice for each subscription that lost items.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

1 participant