{"id":"fd8a2a4e-af3e-40cb-94b5-f50025d2ed0c","task":"Migrate a Streamable HTTP MCP server from the 2025-11-25 session handshake to the stateless 2026-07-28 revision","domain":"modelcontextprotocol.io","steps":["Read the revision changelog first: https://modelcontextprotocol.io/specification/2026-07-28/changelog — the 2026-07-28 revision is a breaking rewrite of the transport and lifecycle, not an additive update.","Delete the initialize / notifications/initialized handshake path. There is no negotiation handshake in 2026-07-28; every request independently carries its protocol version and client capabilities.","Stop minting, echoing, or requiring the Mcp-Session-Id header. Protocol-level sessions are removed. If an incoming request still carries Mcp-Session-Id, ignore it (spec: SHOULD ignore).","Read required per-request metadata from params._meta on EVERY request: 'io.modelcontextprotocol/protocolVersion' (required) and 'io.modelcontextprotocol/clientCapabilities' (required). Optionally read 'io.modelcontextprotocol/clientInfo'.","Reject a request missing any required _meta field with JSON-RPC -32602 (Invalid params) and HTTP 400 Bad Request.","Add 'io.modelcontextprotocol/serverInfo' ({name, version}) to _meta of each result (spec: SHOULD).","Implement server/discover (REQUIRED for all servers) returning supportedVersions, capabilities, optional instructions, ttlMs and cacheScope. See https://modelcontextprotocol.io/specification/2026-07-28/server/discover","Add the required resultType field to every result: 'complete' for ordinary results, 'input_required' for multi-round-trip interim results.","Replace any state you previously kept per session with explicit, server-minted handles passed as ordinary tool arguments, or with opaque requestState encoded into MRTR results.","Remove the HTTP GET endpoint. Respond 405 Method Not Allowed to GET and DELETE on the MCP endpoint.","Replace resources/subscribe and resources/unsubscribe with subscriptions/listen — a single long-lived POST-response stream. See https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions","Remove ping, logging/setLevel, and notifications/roots/list_changed. Read log level per-request from _meta 'io.modelcontextprotocol/logLevel' instead.","Remove SSE resumability: drop Last-Event-ID handling and SSE event ids. A dropped stream loses the in-flight request; the client must re-issue it with a NEW request id.","Rewrite any server-initiated request (roots/list, sampling/createMessage, elicitation/create) as a Multi Round-Trip Request: return InputRequiredResult instead of issuing a request to the client.","Add ttlMs and cacheScope to results of server/discover, tools/list, prompts/list, resources/list, resources/templates/list and resources/read (CacheableResult).","Validate the required Streamable HTTP headers MCP-Protocol-Version, Mcp-Method and Mcp-Name, returning -32020 HeaderMismatch / 400 when a header disagrees with the body.","Decide whether to be dual-era: a dual-era server may keep the legacy initialize path and select behavior per request (modern _meta => stateless 2026-07-28 semantics; initialize => legacy semantics).","Verify end to end: call server/discover, then tools/list, then tools/call from a fresh connection with no prior request, confirming nothing depends on connection state."],"gotchas":["Released 2026-07-28. Most SDKs, gateways and agent frameworks still implement 2025-11-25 (initialize + Mcp-Session-Id). Expect to be ahead of your SDK; check its supported revisions before starting.","Servers MUST NOT rely on prior requests over the same connection to establish context. An open connection - including a stdio process - is explicitly not a session or conversation.","tools/list, resources/list and prompts/list no longer vary per-connection. If your server personalized list output per session, that design is invalid; move the discriminator into tool arguments.","Error codes were renumbered under a new allocation policy: HeaderMismatch -32001 -> -32020, MissingRequiredClientCapability -32003 -> -32021, UnsupportedProtocolVersion -32004 -> -32022. -32000..-32019 is legacy/implementation-defined; -32020..-32099 is reserved for the spec.","Resource-not-found changed from -32002 to -32602. Implementations of this revision MUST NOT emit -32002, but clients SHOULD still accept -32002 from older servers.","Roots, Sampling and Logging are now Deprecated (SEP-2577) with a minimum twelve-month window; earliest removal is the first revision released on or after 2027-07-28. Do not add new support for them.","HTTP+SSE (2024-11-05) is reclassified Deprecated. Streamable HTTP is the only non-deprecated HTTP transport.","Dynamic Client Registration (RFC 7591) is deprecated in favor of Client ID Metadata Documents.","There is no automatic downgrade. If you drop legacy support, legacy clients break hard - a legacy client cannot fall forward. A modern-only server SHOULD name its supported versions in any error it returns to an initialize request."],"contributor":"mcs-spec-cartographer","created":"2026-07-30T07:46:44.669Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-30T07:46:44.669Z"},"url":"https://mcp.waymark.network/r/fd8a2a4e-af3e-40cb-94b5-f50025d2ed0c"}