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.

[rozzilla]

1. Redis can change task results
   The new JSON conversion can turn empty arrays ([]) into objects ({}) and round large numbers. Clients could receive data different from what the tool produced. Preserve the original result when updating task metadata

2. client input can be lostRedis accepting a message does not guarantee the worker received it. If the worker is disconnected, the server still deletes the saved input and reports success. Retrying cannot recover it, leaving the task stuck. Keep the input until the worker confirms receipt.

3. Resumed tasks lose their saved state
   A handler can save information in InputRequired.state before asking the client for input. The task path drops that information, so the handler resumes without the context it needs. Pass the saved state back through context.requestState.

[mcollina]

@rozzilla thanks for the review. All three points are addressed in de26c71.

1. Redis can change task results. The task outcome, input requests and pending responses are now stored in Redis as JSON strings. The Lua scripts pass them through without decoding, so cjson never re-encodes tool or client data. Status, rounds and the other bookkeeping fields are still read in Lua as before. Records written by the old code still decode. New test in test/redis-task-store.test.ts: empty arrays, nested empty arrays, a 16-digit number and 0.1 + 0.2 survive status updates, staged input and completion unchanged.

2. Client input can be lost. tasks/update still publishes, but it no longer acknowledges the outbox. The worker acknowledges it once it has the answers. While waiting, the worker also checks the outbox for its current round every poll interval, so a publication the broker accepted but never delivered is recovered without the client retrying. Late broker copies are deduplicated by delivery id, and leftovers are scoped to their round so they can't reach a later one. New test: the first publication is dropped, tasks/update still succeeds, and the task completes from the outbox.

3. Resumed tasks lose their saved state. InputRequired.state is now handed back as context.requestState on the next task round, as in a direct MRTR retry. It stays on the server, so it isn't sealed. New test: a handler that saves { step: 2, cart: [] } gets it back after tasks/update.

Each new test fails on the previous commit. The full suite, Redis included, passes locally.

[mcollina]

I ran an adversarial review of this PR against the 2026-07-28 spec in spec/. Five reviewers covered transport, versioning and caching, MRTR and elicitation, subscriptions and server features, and the tasks extension. Every finding was checked against the spec text and, where possible, reproduced. All findings in this PR's scope are fixed in four commits, each with tests. The full suite passes locally, Redis included.

3d44648: transport and subscriptions

• 2026-07-28 now works over stdio. Previously every modern stdio request failed with -32020, because stdio has no header layer. The stdio transport proves itself with a per-process token an HTTP client cannot forge.
• A modern batch body is rejected with -32600 instead of being accepted with 202 as a notification and dropped. Malformed messages (id: null, missing jsonrpc or method) are rejected too.
• An unsupported version is reported before the 2026 required fields, on every method including subscriptions/listen.
• Raw non-ASCII bytes in Mcp-Name / Mcp-Param-* are rejected, and integer headers must be plain decimal, so 0x2A and 4.2e1 no longer equal 42.
• A tool with a broken x-mcp-header annotation is reported as unknown rather than as a client header mismatch.
• The listen filter is validated, and the acknowledgement only agrees to types the server's capabilities declare (listChanged / subscribe).
• Server teardown of a listen stream, including a slow consumer that overflows, sends notifications/cancelled (MUST in cancellation.md) followed by the graceful empty response with serverInfo (SHOULD in subscriptions.md).

9922d96: MRTR input, tool output, envelopes

• Form elicitation is refused for URL-only clients, and sampling with tools / includeContext needs the matching sub-capability.
• Input requests with unsupported methods or invalid URLs are never forwarded.
• Sealed state records which input keys were issued. Only those answers reach the handler, and non-object inputResponses is -32602.
• State is bound to the OAuth client and issuer as well as the user, and signed under a domain prefix. Empty or short (< 32 bytes) secrets are rejected at startup. The docs now say the state is signed, not encrypted.
• An unidentified caller that needs input gets a correlated error instead of a 500 with id: null.
• MRTR retries carry ttlMs: 0, cacheScope: 'private' instead of no hints.
• resultType cannot be overridden by a handler.
• A failed resources/read is a JSON-RPC error on the modern path, never cacheable content.
• structuredContent is enforced against outputSchema (tools.md: MUST), using a non-mutating validator.
• Non-object tools/call arguments and invalid caching config are rejected, and completions / logging are no longer advertised on server/discover.
• Legacy errors no longer serialize thrown values, including InputRequired state, into error.data.

ea4065f: tasks

• A task resumes only once every key of its input round is answered. Previously answering {a, b} one key at a time failed the task.
• A key the handler asks for again gets a fresh wire key, mapped back to the handler's key, instead of failing the task.
• A fully answered task moves to working atomically in both stores.
• A state-only InputRequired resumes the task at once.
• A parked worker is released when its task ends, including through legacy tasks/cancel, which now publishes the cancellation.
• Stale status messages are cleared, and completed results carry the synchronous envelope.
• No unreachable tasks are created for unidentified callers.
• New taskMaxConcurrent option (default 1000), with synchronous fallback for optional tasks. The Redis task index is pruned on a schedule.
• execution.taskSupport is no longer shown to 2026-07-28 clients.

d209416: cancellation

• Handlers get context.signal. It aborts when a 2026-07-28 client disconnects before the response (cancellation.md: MUST), and on tasks/cancel for task handlers. It never aborts on the legacy path, where a disconnect is not a cancellation.

Behaviour changes worth noting

• Listen only acknowledges types the server declares, so a server configured with just tools: {} no longer acknowledges toolsListChanged.
• requestStateSecret must be at least 32 bytes.
• Invalid caching values throw at startup instead of being clamped.

Not changed: the -32022 supported list still includes legacy versions, because versioning.md's own example does that, and it is how a dual-era client learns it can fall back to initialize.

Already on main, tracked separately: #207 (resource_metadata URL with a path), #208 (audience validation opt-in), #209 (Origin validation off by default), #210 (prompts/get errors as success), #211 (validateJsonSchemaInputs mutates arguments), plus the existing #179 (template reads) and #182 (scope on the first 401).

[rozzilla]

lgtm

[mcollina]

Second adversarial review round, against spec/ (2026-07-28). This time five reviewers covered the round-1 fix commits, legacy-path regressions (main's own test suite run against this branch), multi-instance behaviour on a real Redis with 2–3 instances and kill -9, the client/stdio/progress/types surface, and security/DoS. Everything in scope is fixed in six commits with tests; the full suite passes locally, Redis included.

39262ae: regressions from round 1

• Mcp-Method is compared literally again. Only Mcp-Name and Mcp-Param-* may use the Base64 sentinel, so an encoded method can no longer bypass a gateway that routes on the header.
• context.signal aborts only when the connection closes while the request is still being handled. Previously every stdio and mcpClient request looked cancelled.
• outputSchema checking:
  • It applies only from 2025-06-18, since older revisions have no structuredContent.
  • It validates the JSON the client receives, so a Date passes a string schema.
  • A non-2020-12 $schema is refused at registration.

b6a6572: task ownership and lifecycle

• Tasks are bound to user + OAuth client + issuer in both eras, matching sealed request state. Another app acting for the same user can no longer read or approve a task's input requests.
• Legacy and modern tasks/* only see tasks of their own era.
• Worker leases are timed by Redis TIME. A task whose worker crashed is reported failed when next read, instead of staying working until its TTL and then vanishing.
• Graceful shutdown drains running tasks for taskShutdownTimeoutMs (default 5s, below Fastify's pluginTimeout). It then aborts them and records the real reason, instead of a false "Timed out".
• Handlers are aborted at their TTL, freeing their slot. The concurrency slot is reserved before awaiting the store, so taskMaxConcurrent holds under concurrency.
• Lease renewal also catches a cancellation whose broker message was lost.
• Task records moved to the mcp:task:v2: keyspace, so mixed-version fleets never misread each other.
• Strings are made well-formed before they reach Lua.

782e519: limits

• taskMaxPerPrincipal (100), subscriptionMaxStreamsPerPrincipal (10, HTTP 429), subscriptionMaxStreams (1000) and subscriptionMaxResourceUris (1000). These limits are per instance.
• The memory store evicts finished tasks first.
• Instances only buffer early task answers for tasks they run, instead of holding every client answer for an hour.

d965356: stdio

• subscriptions/listen streams to stdout as it happens.
• notifications/cancelled aborts the handler and suppresses its output.
• Modern batches get -32600; unparseable lines get -32700.

d0416fc: progress and logging on the modern path

• context.sendProgress() / context.log() stream notifications/progress / notifications/message on the request's response, only when it carries progressToken / logLevel. Requests that never report still get JSON.
• logging is advertised on discover again.
• Client: accepts SSE responses, rejects unknown resultType, and takes extra _meta on callTool.

6035708: the rest

• mcpCallTool reports denied tools as not-found, as on main.
• Defaults and startup:
  • Default capabilities declare listChanged, and resources.subscribe once a subscribe handler is set.
  • redis without requestStateSecret is refused at startup.
  • cacheScope: 'public' combined with per-caller results logs a warning.
• Sealed state:
  • It is bound to the server name.
  • Deeply nested params fail verification instead of returning a 500.
• Telemetry uses the _meta version and the stdio trust token.
• Nullable x-mcp-header parameters are accepted.
• tasks/update / tasks/cancel succeed once stored, even if the publish fails.
• resources/read handler errors stay out of responses.
• The Redis index cleanup is pipelined and jittered.
• The README gains docs for all of the above plus a Breaking changes in 3.0.0 section. This should ship as a major; the version bump is left for the release.

Already on main, tracked separately: #212 (Redis broker drops username/tls/sentinels) and #213 (RedisTaskStore.get() deletes on the local clock).

Intentionally unchanged:

• Tool errors keep their message: tools.md wants them informative so the model can recover.
• The client leaves the SHOULD retries (-32022, -32020) to callers; this is now documented.