Complete Modern client-facing dispatch: listen + pagination

[JAORMX]

Summary

Why. vMCP's Modern (2026-07-28) dispatcher had two client-facing gaps that together made it unusable for a real SDK client. Both are exposed the moment vMCP serves Modern unconditionally (#6033); neither was introduced by it.

Delivered as one larger PR per the CLAUDE.md large-PR exception — these are the two halves of "Modern client-facing dispatch works".

Refs #5959, #6033, #5743

Part 1 — subscriptions/listen

Modern removed the standalone HTTP GET stream, making subscriptions/listen the revision's only server→client push channel. dispatchModern had no case for it, so it answered -32601. That made vMCP unreachable for any go-sdk v1.7 client: Connect is Modern-first, and once server/discover succeeds it opens a listen stream whenever a list-changed handler is registered — which mcpcompat's Initialize does unconditionally. The -32601 failed Connect outright and tore the session down.

• The honored set is computed by intersecting the client's requested types against the capability advertisement server/discover publishes — extracted as newModernCapabilities so the two cannot drift.
• Two-frame SSE response: the mandatory notifications/subscriptions/acknowledged first, then a terminating result, both tagged io.modelcontextprotocol/subscriptionId and keyed by the listen request's own JSON-RPC id (Modern has no sessions).
• Ungated, same bucket as the list verbs and server/discover.

No push delivery exists, and this PR does not add any. Every push flag in newModernCapabilities is deliberately false — dispatchModern creates no session, so the per-session list_changed machinery never runs for a Modern client, and backend resources/updated is not forwarded even on Legacy. The honored set is therefore always empty, and the acknowledgement says so explicitly. That is the spec's own mechanism for declaring unsupported types, not a silent no-op: nothing is reported as subscribed and then quietly dropped. Real delivery is #5743.

Part 2 — nextCursor pagination for the list verbs

The four Modern list verbs returned the full aggregated set and never emitted nextCursor, so a client could not page and any cursor it sent was ignored. On Legacy the SDK's session-scoped feature store does this split; the Modern dispatcher bypasses the SDK.

Modern is stateless, so a cursor may not denote server-held iteration state. The draft pagination page (not the 2025-11-25 one — they differ) makes cursors opaque to clients, which is precisely what lets the server encode position into the token instead of remembering it.

• Keyset pagination, the same scheme go-sdk's own server uses.
• Collision-safe. The cursor carries how many items sharing the last key were already delivered, so a page resumes inside a run of equal keys. Only Tool.Name is unique (ResolveToolConflicts keys a map); resource URIs, template strings and prompt names are plain-appended across backends with no de-duplication, so collisions are ordinary.
• Aggregation needs no per-backend positions — the cursor encodes a position in the aggregated ordering and never names a backend.
• End-of-results omits nextCursor entirely. The draft states an empty string is a valid cursor and MUST NOT be treated as the end of results, so emitting "" would make a conformant client loop on page one.
• Invalid, over-length, and wrong-verb cursors are rejected -32602.

Ordering note: keyset paging needs a deterministic total order and the aggregator's fan-out order is not stable, so Modern list results are now sorted by key. Legacy ordering is unchanged.

Type of change

• New feature

Test plan

• Unit tests (task test) — only the three known environmental failures (TestNewServer_ReadTimeoutConfigured, TestSecurityHeaders, TestCompositeProvider_RealProviders), all pre-existing on main and all passing in CI, which has a container runtime.
• Linting (task lint) — 0 issues. go vet ./... and go build ./... run separately: clean.
• Manual testing — measured against Replace vMCP Modern kill-switch with a capability gate #6033 by cherry-picking all five commits onto fd3b6a9b.
• E2E tests — not run locally; require a container runtime unavailable in this environment.

Measured effect on #6033

#6033 state	test/integration/vmcp	pkg/vmcp/server forwarding	total
as-is	15 fail	5 fail	20
+ subscriptions/listen	1 fail	5 fail	6
+ pagination and fixes	0 fail	5 fail	5

test/integration/vmcp is fully green, TestRegression_Over1000Tools_CompleteSetReceived included.

The remaining 5 are the forwarding tests and are not addressable here: they exercise server-initiated elicitation/sampling, which 2026-07-28 removes outright — go-sdk's assertServerInitiatedRequestAllowed refuses them on protocol version alone, never consulting client capabilities. Progress and logging are not subscribable types under SEP-2575. Those need the MRTR work.

Duplicate-key walk counts (H1)

corpus	before	after
1100, run straddling the page boundary	1097	1100
1001, same shape	1000	1001
2000, same shape	1997	2000

API Compatibility

• This PR does not break the v1beta1 API.

No CRD or api/v1* type is touched. Legacy behaviour is unchanged; every change is confined to the Modern dispatch path, except the newModernCapabilities extraction, a pure refactor of what server/discover already emitted.

Does this introduce a user-facing change?

Yes, reachable once vMCP serves Modern (still behind the kill-switch on main, removed by #6033):

• A Modern client can complete Connect instead of having its session torn down, and receives an explicit acknowledgement that no notification subscriptions are honored.
• Modern list verbs paginate: a client with more than 1000 tools/resources/templates/prompts receives the complete set across cursors rather than a silently truncated first page.

Special notes for reviewers

Things that are correct and easy to mistake for bugs — please don't re-flag these; each was checked against the draft spec:

• No SSE prime/close event and no id: field. The draft explicitly drops resumability: "Resumable SSE streams via Last-Event-ID are not supported", and instructs servers to ignore the header. Emitting id: would imply a resumability we don't offer.
• The event: message name is not mandated. The draft specifies the content type and stream lifecycle but never an SSE event name. It's kept for symmetry with go-sdk's framing.
• Forcing SSE for this one method is required, not stylistic — two JSON-RPC messages must travel on one response, which a single JSON body cannot express.
• resultType: "complete" on the listen result is required by Result in schema/draft/schema.ts ("Servers implementing this protocol version MUST include this field").
• {} for an empty honored set is the spec's way to say "I honor none of these", not an omission.
• The 202-for-notifications guard is load-bearing. Without it notifications/cancelled would fall to default: → -32601 → 404 → dead session.
• ping returns a bare {}. ping does not exist in 2026-07-28 (absent from the draft schema; go-sdk lists it among removed methods), so answering it at all is deliberate leniency, not conformance — and the bare {} also omits resultType. Left as-is because it is a pre-existing path and inert (a go-sdk Modern client never pings); the comment now says -32601 is the conformant answer for whoever tightens it.

Where to push back:

1. Is Part 1's empty honored set acceptable, or a stub? The case that it isn't: it makes a truthful negative declaration matching what the same dispatcher advertises, it is the spec's designated mechanism, and go-sdk's reference server does the same. The honest counter-argument: go-sdk's client ignores the acknowledgement (callSubscriptionsAckHandler returns (nil, nil)), so against that client the declaration is not observable in behaviour. It is still correct on the wire, and the alternative — holding a stream open forever delivering nothing — is strictly worse.
2. Part 1 deliberately diverges from go-sdk on one point. go-sdk blocks on the request context once it has honored a subscription; this does not, because holding a socket open with no delivery mechanism is the same silent no-op with extra steps. Close-plus-WARN fails loud where blocking fails silent. The branch is unreachable today, and the WARN exists so a future capability flip without delivery is loud in logs rather than an idle subscription.
3. No reuse of serverStreamRegistry. dispatcher_streams.go suggests it as the fan-out seam. With an empty honored set there is no fan-out, so adapting an unexported registry from another package would add an abstraction with zero consumers (vMCP anti-pattern Start simple hardcoded registry #8). It stays the right seam for delivery; the doc now says so.
4. modernPageSize is a hand-copy of go-sdk's DefaultPageSize. The Modern side is pinned behaviourally (1001 → 1000 + 1); the matching Legacy assertion is not, because pinning a client to Legacy needs a negotiation-pinning harness this package lacks (mcpcompat cannot request a protocol version, Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911). Stated in the constant's doc comment as an invariant maintained by review, not CI. Follow-ups: re-export the constant from mcpcompat, and add the Legacy twin alongside the MRTR work.

Known property introduced by pagination: backend-chosen names now influence page-1 membership. 1000 tools named aaa_* will fill the first page and push others to page 2, where previously everything arrived at once. Only affects clients that ignore nextCursor; noting it because it did not exist before this change.

Follow-up filed upstream: go-sdk's ClientSession.SetLoggingLevel omits injectRequestMeta while still sending the MCP-Protocol-Version: 2026-07-28 header, so a conformant server must reject it -32020 and a Modern go-sdk client cannot call logging/setLevel at all — modelcontextprotocol/go-sdk#1116.

Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 77.07317% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.25%. Comparing base (57e681f) to head (1588e6a).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/vmcp/server/modern_subscriptions.go	62.19%	23 Missing and 8 partials ⚠️
pkg/vmcp/server/modern_dispatch.go	76.74%	7 Missing and 3 partials ⚠️
pkg/vmcp/server/modern_pagination.go	90.76%	3 Missing and 3 partials ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #6050    +/-   ##
========================================
  Coverage   72.24%   72.25%            
========================================
  Files         722      724     +2     
  Lines       75125    75317   +192     
========================================
+ Hits        54277    54423   +146     
- Misses      16985    17018    +33     
- Partials     3863     3876    +13     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jhrozek]

Went through this in detail (protocol-compliance, Go quality, architecture/docs, and test coverage) plus checked it against the vmcp anti-pattern list separately. Overall this is solid -- no correctness or spec issues that need to hold up merging. Left a handful of inline notes below, plus two things that don't fit as inline comments because they're not touched by this diff:

• docs/arch/10-virtual-mcp-architecture.md (~line 340-342) still says vMCP "does not implement" subscriptions/listen yet -- worth a follow-up correcting that to describe the ack-only, zero-capability handler this PR adds (the list_changed-is-Legacy-only conclusion there is still accurate, just the premise needs a tweak).
• docs/arch/03-transport-architecture.md's "Forward-compatibility note" (~line 680-689) still frames a Modern subscriptions/listen handler as future work and floats serverStreamRegistry as the fan-out seam for it. Might be worth a short update now that the handler exists and deliberately doesn't reuse that registry (empty honored-set today, no fan-out consumer yet).

Neither blocks this PR, just flagging so they don't get lost.

[JAORMX]

@jhrozek all six of your inline notes are applied, plus both doc items from your review body. Consolidating here since the threads are marked outdated against the current head (e9463fea); I replied in place on the first one because part of it could not be done as asked.

Your note	Resolution
modern_subscriptions.go:169 — pre-write errors could return -32603 rather than an empty 200	Applied via your suggested shape: buildModernListenFrames split out, both marshal failures route through writeModernListError, log-and-return reserved for the genuine mid-stream failure. Partial — see the thread reply; the flushability check is gone rather than routed, because http.ResponseController has no predicate and the old type assertion never actually detected unflushability.
modern_subscriptions.go:265 — missing X-Accel-Buffering: no	Applied.
modern_pagination.go:166 — sort.Search instead of the linear resume scan	Applied (slices.BinarySearchFunc); a full walk is now O(n log n) rather than O(n²).
modern_pagination_test.go:290 — pin the wrong-verb guarantee at dispatch level, not just against the codec	Applied, and widened: TestDispatchModernList_CursorNotReplayableAcrossVerbs mints a real page-1 cursor per verb through dispatchModern and replays it against all three others — 12 combinations, of which your tools/list → resources/list case is one. The fixture's resource Names now also collide (URIs distinct), so keying on Name instead of URI is detectable.
modern_pagination.go:209 — cmpString duplicates the stdlib	Applied; removed in favour of strings.Compare (no new import).
modern_pagination.go:200 — malformed params envelope silently falls back to page 1	Applied; now -32602. Your read was right that it wasn't reliably rejected upstream: {"cursor": 42} is well-formed JSON with a field type error, so nothing upstream inspected it. A related detail that settled it — with a duplicate key, {"cursor":42,"cursor":"<valid>"}, Go's unmarshal populates the field with the valid value and returns an error, so the discard was throwing away a cursor it had already decoded.
Review body — 10-virtual-mcp-architecture.md still says subscriptions/listen is not implemented	Fixed here rather than deferred, along with a served-capabilities row and a new client-facing pagination section.
Review body — 03-transport-architecture.md still frames the handler as future work	Fixed; serverStreamRegistry is reframed as the seam for delivery rather than for the handler, since that's the part still outstanding (#6065).

Two things your questions led to that are worth recording, because both closed gaps we could not otherwise verify:

Your X-Accel-Buffering note turned out to sit exactly where our own spec verification had failed. An earlier pass reported docs/specification/draft/basic/transports.mdx unreachable and downgraded its SSE conclusions to "resting on corroborating sources". The page hadn't gone — the draft split it into a directory, at transports/streamable-http.mdx. Your header is a SHOULD there, verbatim. Finding it also settled two open questions: the SSE event: name is not mandated (so ours is kept for go-sdk symmetry and documented as optional), and omitting id: is correct with a citation — "Resumable SSE streams via Last-Event-ID are not supported".

A blocking defect was found after your review and is fixed here, so it's worth flagging since you reviewed the earlier tree: the paginator assumed item keys were unique, citing the aggregator's conflict resolver. That holds for tools only — default_aggregator.go plain-appends resources, templates and prompts under // no conflict resolution for these yet. A duplicate at a page boundary permanently dropped every item sharing that key (1100 in, 1097 out). The cursor now carries (LastKey, Delivered) and resumes inside a run of equal keys; 1100→1100, 1001→1001, 2000→2000. Root cause filed as #6060.

Happy to take anything else. Note the merge is currently blocked on these conversations being resolved.

[ChrisJBurns]

/retest

[ChrisJBurns]

@JAORMX I have a feeling the e2e tests failure is real as it's failed on 2 retries