Skip to content

uwuclxdy/agenticat / skills/mcp-stateless

mcp-stateless

Verified

MCP knowledge pack for the stateless 2026-07-28 revision.

MCP Stateless

The Model Context Protocol went stateless in revision 2026-07-28. It is the largest break since launch: the initialize handshake, the session id, the standalone SSE stream, and server-initiated requests are all gone. Every request now carries everything a server needs to answer it.

Model training data predates this revision. An MCP server written from memory speaks the 2025-11-25 protocol and will be rejected by a modern client. The failure is not a compile error and often not a runtime error either: a handshake-era server and a modern client fail in ways that read like a config problem. Work from the reference files here, and check anything version-sensitive against the live spec.

Hard Rules

  1. Never write MCP wire code from memory. Read references/wire.md first. If a claim here is older than the revision you are targeting, the live spec wins.
  2. State is a lie the connection tells you. A server MUST NOT infer anything from a previous request on the same connection: not the protocol version, not capabilities, not client identity, not conversation continuity. One stdio process is not one session. A client may interleave unrelated requests on it.
  3. State that must span requests gets an explicit server-minted handle passed back as an ordinary parameter. There is no session to hang it on.
  4. A server MUST answer server/discover. It is the only way left to advertise what the server supports, and it is how a dual-era client tells a modern server from a legacy one.
  5. Every result carries resultType. Omitting it marks the server as legacy. A result with no resultType MUST be read as "complete".
  6. Servers never send JSON-RPC requests. Sampling, elicitation, and roots all run through multi round-trip requests: the server answers with input_required, the client retries. Read references/mrtr.md before wiring any of the three.
  7. requestState comes back from the client unverified. Sign or encrypt it. A stateless server that trusts an echoed blob has handed the client its internal state machine.
  8. Verify with a live handshake against the real binary. A green build proves nothing about protocol conformance, and the old smoke-test recipe (pipe an initialize frame) now tests a method that no longer exists. Recipe in references/sdks.md.

What Changed

2025-11-25 and earlier2026-07-28Silent-failure risk if you keep the old shape
initialize + notifications/initializedRemoved. Per-request _meta carries version, capabilities, identityHigh. A modern client gets an implementation-defined error, or worse, silence
Mcp-Session-Id header, DELETE to end a sessionRemoved. Servers ignore the header and never mint oneHigh. Session-keyed caches and per-session state silently serve the wrong tenant
Capabilities exchanged once at connectserver/discover (servers MUST implement), plus per-request io.modelcontextprotocol/clientCapabilitiesHigh. A server reading capabilities from a remembered handshake reads nothing
Results had no discriminatorEvery result MUST carry resultType: "complete" or "input_required"Medium. Clients treat a missing field as "complete", so a real MRTR reply gets mis-parsed
Server sends sampling/createMessage, elicitation/create, roots/list as requestsMRTR: server returns InputRequiredResult, client retries the original request with inputResponsesHigh. The old pattern is explicitly no longer supported
Standalone HTTP GET SSE stream; resources/subscribe / unsubscribesubscriptions/listen: one long-lived POST-response stream, client opts into notification typesMedium. A modern-only server SHOULD answer GET with 405
Last-Event-ID resumption, SSE event idsRemoved. A broken stream loses the in-flight request; the client re-issues with a new request idMedium. Resumption code silently never fires
ping, logging/setLevel, notifications/roots/list_changedRemoved from the core protocolMedium. Kept in SDKs only for legacy sessions
Log verbosity set once per sessionPer-request io.modelcontextprotocol/logLevel in _meta. A server MUST NOT emit notifications/message for a request that omitted itMedium. Log notifications stop arriving and nothing reports an error
List results were plaintools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover MUST carry ttlMs + cacheScopeLow. Clients default to "immediately stale" and re-fetch every time
Streamable HTTP POST carried no routing metadataMcp-Method + Mcp-Name headers REQUIRED, validated against the body; mismatch is 400 + -32020High on HTTP. A gateway routing on headers and a server executing the body is the vulnerability this closes
Tasks were experimental coreThe io.modelcontextprotocol/tasks extension. tasks/list and tasks/result are goneMedium. No compatibility shim
Resource-not-found was -32002-32602 (Invalid Params). Accept -32002 inbound from older serversLow

Deprecated, Not Yet Removed

Still in the spec, still functional. New code SHOULD NOT adopt them. The removal clocks differ per feature, so read the column rather than assuming one date.

FeatureMigrate toEarliest removal
RootsDirectories or files as tool parameters, resource URIs, or server configurationFirst revision on or after 2027-07-28
SamplingThe LLM provider's API directlyFirst revision on or after 2027-07-28
Loggingstderr on stdio; OpenTelemetry for structured observabilityFirst revision on or after 2027-07-28
OAuth Dynamic Client RegistrationClient ID Metadata DocumentsFirst revision on or after 2027-07-28
includeContext: "thisServer" / "allServers"Omit the field, or "none"Follows Sampling
HTTP+SSE transport (the 2024-11-05 one)Streamable HTTPThree months after SEP-2596 reaches Final, which may already have elapsed

The specification now runs a formal feature lifecycle (Active, Deprecated, Removed) with a minimum twelve-month deprecation window and a published registry, so a feature disappearing without notice is no longer the failure mode. Checking the registry before adopting anything is.

Files

Load the one matching the task. Do not load them all.

Task touchesFile
Wire shapes: _meta keys, server/discover, resultType, error codes, HTTP headers, caching, subscriptions, transportsreferences/wire.md
Sampling, elicitation, roots, InputRequiredResult, requestState and its securityreferences/mrtr.md
Porting an existing server or client, supporting both eras, what breaks silentlyreferences/migrate.md
Which SDK version speaks which revision, per-SDK API shape, how to smoke-test a built serverreferences/sdks.md

What This Skill Does Not Cover

  • Server design: which tools to expose, how to carve a large API surface, deployment model, bundling for local install. That is a product question, and the official mcp-server-dev plugin (anthropics/claude-plugins-official) runs a discovery interview for it. Check its pinned versions before trusting its protocol claims; as of 2026-08 its version-pin file records the MCP spec claims as last verified 2026-03, which is the 2025-11-25 era.
  • MCP Apps / UI widgets beyond how the extension is negotiated.
  • Authorization in depth. The revision tightened OAuth (issuer validation, credentials keyed by issuer, application_type on registration, Client ID Metadata Documents over DCR). references/migrate.md lists what changed; the auth spec pages are the authority.

Live Docs on Demand

The spec ships agent-readable markdown: append .md to any spec URL.

NeedURL
Page indexhttps://modelcontextprotocol.io/llms.txt
Revision changeloghttps://modelcontextprotocol.io/specification/2026-07-28/changelog.md
Statelessness, _meta, error codes.../specification/2026-07-28/basic/index.md
Version negotiation, extensions, dual-era matrix.../specification/2026-07-28/basic/versioning.md
Deprecated-features registry.../specification/2026-07-28/deprecated.md
Full schema reference.../specification/2026-07-28/schema.md

Fetch the schema page before asserting any field name. Field names in this skill were read from the spec; field names in a model's memory were not.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall