feat: implement MCP 2026-07-28 alongside the handshake revisions

[mcollina]

Summary

Implements the MCP 2026-07-28 specification, released 28 July 2026.

This is a much bigger change than a version bump — 2026-07-28 makes MCP stateless. It removes the initialize handshake, protocol-level sessions (Mcp-Session-Id), the standalone SSE GET endpoint, Last-Event-ID resumability, ping, logging/setLevel and resources/subscribe, and replaces server-initiated requests entirely.

All of those are load-bearing for current users of @platformatic/mcp, so rather than break them this implements the spec's dual-era server. Both protocols are served on the same /mcp endpoint:

• A request carrying _meta['io.modelcontextprotocol/protocolVersion'] → served statelessly under 2026-07-28
• Anything else → the existing initialize path, unchanged

Existing users need no changes. The handshake path and its 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 behaviour are untouched.

Business logic is shared between the eras: the modern dispatcher calls the same tool, resource and prompt handlers and only changes the envelope.

What's new

Feature	Notes
server/discover	Supported versions, capabilities and identity in one request
Per-request negotiation	Version + capabilities in _meta; no handshake
Multi round-trip requests	Handlers throw InputRequired, read context.inputResponses on the retry
subscriptions/listen	Long-lived notification stream with per-type opt-in and acknowledgement
Cacheable results	ttlMs / cacheScope on discover, the four lists and resources/read
Header routing	Mcp-Method / Mcp-Name / Mcp-Param-* reconciled against the body, incl. the =?base64?…?= sentinel and x-mcp-header
Tasks extension	io.modelcontextprotocol/tasks: tasks/get polling replaces blocking tasks/result, plus tasks/update

New modules

src/modern/
├── request-meta.ts     per-request _meta parsing; looksModern() era switch
├── headers.ts          header/body reconciliation
├── handlers.ts         modern dispatch, resultType envelope, caching, tasks extension
├── input-required.ts   handler-facing MRTR API (InputRequired, elicitForm, …)
├── request-state.ts    HMAC-sealed requestState
├── subscriptions.ts    subscriptions/listen streams
└── task-inputs.ts      delivers tasks/update responses to a running task
src/schema-2026.ts      types introduced or reshaped by the revision

Two things reviewers should weigh in on

requestState needs a shared secret in multi-instance deployments

MRTR state travels through the client, so the spec treats it as attacker-controlled and requires integrity protection. It's sealed with HMAC-SHA256 and bound to the authenticated principal, an expiry, and a digest of the originating request — tampered, expired, cross-principal and cross-request state are all refused.

The default is a per-process random key, which is correct for a single instance but means a retry landing on another replica is refused. Deployments behind a load balancer must set requestStateSecret. Replay is bounded, not eliminated; single-use semantics remain the handler's job, as the spec notes.

Caching defaults to off

{ ttlMs: 0, cacheScope: 'private' } — spec-compliant and always safe, but clients never cache until you opt in per operation. I chose this over guessing a TTL because cacheScope: 'public' lets shared proxies serve one caller's response to another even from an authenticated endpoint.

Behaviour changes

• negotiateProtocolVersion falls back to 2025-11-25 rather than the newest revision — a client sending initialize cannot, by definition, speak 2026-07-28
• mcpBroadcastNotification no longer requires enableSSE, since subscriptions/listen is core to the modern protocol (legacy SSE delivery is still gated by the flag)
• Status codes now follow the revision, because dual-era clients use them to detect which era a server speaks:
  • 400 — HeaderMismatch (-32020), MissingRequiredClientCapability (-32021), UnsupportedProtocolVersion (-32022)
  • 404 + -32601 — removed or unknown methods
  • 200 — application failures (unknown tool, missing resource)

Testing

npm run ci passes: 472 tests (was 369), including the Redis-backed suites.

New coverage:

• test/spec-2026-07-28.test.ts — end-to-end: discovery, metadata validation, header validation, removed methods, MRTR (including tampering and replay), subscriptions, tasks extension, and dual-era interleaving
• test/modern-units.test.ts — header encoding, request-state sealing, subscription filters, _meta parsing

Not included

• spec/ is refreshed to the 2026-07-28 documents
• Package version not bumped — this is additive and non-breaking, so 2.2.0 seems right, but that's a maintainer call

🤖 Generated with Claude Code

https://claude.ai/code/session_01TdN2reiRNd6xsvtJVjHPCG

[mcollina]

Adversarial review — findings and fixes

Ran a hostile review pass over this branch. It found real defects that the green suite missed; 5364406 fixes them. Every new test was verified to fail against the unfixed code.

Fixed

Sev	Finding	Fix
Critical	Header/body mirroring was bypassable. Era detection keyed only off _meta[protocolVersion] in the body, so modern Mcp-Method/Mcp-Name headers + a body omitting _meta dropped onto the legacy path and skipped header validation entirely — calling one tool while a gateway routing on Mcp-Name saw another	isModernRequest treats a modern MCP-Protocol-Version header as era-determining
High	Graceful subscription closure never sent. closeAll() ran in onClose, which Fastify runs after shutting the server down	Moved to preClose
High	tasks/update lost across instances. Wake-up was process-local while answers were written to the shared store and inputRequests cleared — success ack, task never resumes, unrecoverable	Delivery over the message broker, plus a bounded early-arrival buffer
Med-high	A reused input key could never be answered. answeredInputKeys accumulated across rounds	Cleared when a new round is issued
Medium	MRTR retries carried caching hints, which spec/caching.md forbids — a cross-user leak with cacheScope: "public"	Hints suppressed when inputResponses/requestState present
Medium	URL-mode elicitation sent to form-only clients	Mode checked against elicitation.url/.form separately
Medium	Legacy revisions named in _meta were served a modern envelope	Refused with -32022; full list still advertised
Low-med	Mcp-Name not enforced when the body omitted name/uri	Required for the three named methods regardless
Low-med	requestState bound to undefined principal matched any other identity-less caller	Refuses when authorization is enabled, matching assertTaskAccess

One shipped test asserted the critical bug as correct behaviour — replaced.

Not acted on

• completion/complete advertised but 404s — the review said the legacy path implements it; it does not. This is the user's own capabilities config echoed back, same as on legacy initialize. Pre-existing, not a regression.
• digestRequest collisions — stableStringify can collide ['a','b'] with {"0":"a","1":"b"}, but the reviewer could not turn it into a replay (every MRTR method needs an object params with a string name/uri, and the method is bound separately). Theoretical.
• collectHeaderParams unbounded recursion — server-authored schemas only, not attacker-controlled. Worth memoizing later.
• DELETE /mcp returns 404 rather than 405 when SSE is off — cosmetic.

Note on the deadlock claim

The review reported app.close() hanging on open SSE streams. I could not reproduce the hang on this Fastify version — but the substantive half is real and now tested: the graceful-closure response was never sent. Confirmed by reverting the fix (that test fails, the hang test does not).

Behaviour change worth flagging for release notes

LATEST_PROTOCOL_VERSION now means 2026-07-28. Sending it as the MCP-Protocol-Version header commits a request to the modern path, so existing code that hardcodes it needs LATEST_LEGACY_PROTOCOL_VERSION instead. Five legacy test suites needed exactly this change, which is decent evidence real users will too. Documented in the migration section.

484 tests pass (was 472), npm run ci green.

🤖 Generated with Claude Code

[rozzilla]

Modern requests can still enter the legacy SSE GET /mcp handler, which creates a session and broker subscription. This contradicts the stateless 2026-07-28 protocol and allows unnecessary session allocation. We should reject modern GET/DELETE requests before creating or terminating a legacy session.

[mcollina]

Fixed in f498df5. GET and DELETE on /mcp now return 405 Method Not Allowed (with Allow: POST) for 2026-07-28 requests, as the transport spec asks for traffic aimed at the removed GET stream and sessions. The check runs before any session is created, subscribed or terminated. Since GET has no body, the era comes from the MCP-Protocol-Version header. New tests cover both methods, including that a modern DELETE leaves a legacy session untouched.

[rozzilla]

When a task asks the client for more information, the server does not check whether the client supports that interaction.
For example, a task can request elicitation, while the client only declares support for tasks. The task is still stored with an elicitation request that the client may not understand or answer, so it can remain stuck until timeout.
Please reuse the capability checks from the direct multi-round-trip path before storing inputRequests, and reject or fail the task when the required capability is missing.

[mcollina]

Fixed in f498df5. This thread is anchored on routes/mcp.ts, but the fix is in src/modern/handlers.ts. The capability check from the direct MRTR path is now a shared missingInputCapabilities() helper, and the task path calls it before moving to input_required. If a capability is missing, the task fails right away with the same missing-required-client-capability error instead of parking an unanswerable request. Test: a task asking for elicitation from a client that only declares the tasks extension fails and never reports input_required.

[rozzilla]

Each task input round gets the full task TTL, even though the TTL should cover the task’s total lifetime.
For example, with a 60-second TTL, a task created at 12:00:00 should expire at 12:01:00. If the client answers the first question at 12:00:50, this code waits another 60 seconds for the next answer, keeping the task alive until around 12:01:50.
Please calculate the remaining time from the original task expiry before each wait, rather than starting a new full TTL for every round.

[mcollina]

Fixed in f498df5. The task records its expiry (createdAt + ttl) once, and each input round waits only for the time left. If none is left, it fails immediately instead of starting a fresh full TTL. The test answers the first round after 300ms and checks that the second wait is at most ttl - 300ms.