
Auditing Your MCP Server and Client for Hidden Session State Before the 2026-07-28 Stateless Revision
On this page
Introduction: why hidden MCP session state is a compatibility problem
Every MCP server I have shipped has been stateful, and none of them said so in the README. The state was never a design decision; it was the initialize handshake landing on the same process as the first tools/call, the in-memory Map keyed by Mcp-Session-Id, and the per-connection cache I threw in because a schema lookup was slow. It worked because the process stayed alive and the load balancer was sticky, and nobody wrote that down. This post is the audit I should have run first: how to find the implicit session state in your MCP server and client, a two-replica reproduction you can run this afternoon, and a decision checklist for whether migrating to the 2026-07-28 stateless revision is worth the disruption.
So when a commentary surfaced — OpenTools, dated 2026-11-16 per the aggregator entry I received — arguing that the MCP 2026-07-28 revision targets statelessness and that this is a compatibility problem for existing servers and clients rather than a cleanup, it read less like news and more like a description of a debt I already knew about. The same summary says OpenTools also covers when migrating is worth the disruption versus staying on the current model. That is the right framing, and this post is my attempt to turn it into something you can run.
The MCP session state that isn't in your tool handlers
The uncomfortable part: if you open your server and search for state, you will find the obvious things — database connections, a cache, maybe a job queue. You will not find the state that matters, because it lives in the transport layer, the SDK's session bookkeeping, and the assumptions your client makes after a successful handshake.
Three that I have personally tripped over:
- The negotiated
protocolVersion. Agreed once, duringinitialize, then every subsequent message is implicitly interpreted under it. No request carries it. - The session id. In Streamable HTTP the server may mint an
Mcp-Session-Idon theinitializeresponse, and the client must echo it on every later request. That header is a pointer into server-side memory. - The back-channel. Sampling and elicitation are server-initiated requests. They need a live stream and an identified peer. Nothing the client initiates can carry the question the server wants to ask.
None of those are in your tool handlers. All three die if a request lands on a process that has never seen your client.
Why a stateless protocol revision is a compatibility event, not a refactor
A refactor keeps behavior and changes structure. A protocol revision that removes implicit state keeps the happy path on a single process and changes behavior everywhere else — behind a load balancer, after a deploy, after a pod eviction, on the retry your client does when a connection drops. The failure only shows up in the configurations your test suite does not model.
If you run one replica on your laptop, a stateless revision costs you nothing and you learn nothing. If you run three replicas behind a round-robin Service, it is an outage with a scheduled date on it.
What the MCP 2026-07-28 revision actually says, and what I'm inferring
I want to be explicit here, because MCP writing has a bad habit of presenting inference as spec text.
Confirmed from the source: the revision exists, it targets statelessness, and OpenTools frames it as a compatibility problem for existing servers and clients
The material I had is a news-aggregator seed summarising an OpenTools commentary titled "MCP 2026-07-28: what the stateless revision breaks in your server or client, and when migrating is worth it." The confirmed claims are narrow, and I will not stretch them:
- A revision identified as
2026-07-28exists as a subject of public commentary. - The commentary characterises it as a stateless revision.
- The commentary's argument is that it creates compatibility problems in existing MCP servers and clients.
- The commentary also covers when migrating is worth the disruption versus staying on the current model.
That is the whole confirmed surface.
Inference I will label as inference: the OpenTools summary does not enumerate the wire-level changes, so every mechanism claim in this post traces either to the current published spec or to my own local reproduction
I have not read the normative 2026-07-28 text. The summary does not list which messages change, which headers disappear, or how the lifecycle is redefined, so I am not going to describe those changes.
What I can do — and what I think is more useful anyway — is audit the state that exists today under the published spec: the lifecycle handshake and the Streamable HTTP transport. That is the state any stateless revision has to delete. Every mechanism claim below traces to one of two places: the published specification, or a lab reproduction described in full so you can rerun it. Where I speculate about what the revision will do to a specific mechanism, I say so in the sentence.
How MCP date-stamped revisions work, so you know 2026-07-28 is a spec revision ID and not a publication date
MCP does not use semantic version numbers for the protocol. Revisions are identified by a date string, and clients negotiate one during initialize: the client sends the revision it supports, the server replies with the revision it will actually use, which may differ. The published set includes 2024-11-05, 2025-03-26, and 2025-06-18, and the protocolVersion field in the handshake carries exactly that string.
So 2026-07-28 is a revision identifier in the same format — not the date this post was written and not necessarily the date anything shipped. 2025-03-26 is the revision where Streamable HTTP replaced the older HTTP+SSE transport; 2025-06-18 refined it and added elicitation. If you want the history, the specification's versioning page is the primary source. Read it rather than take my summary.
Read the exact normative text of 2026-07-28 from the specification repository before you act on it. This post audits your assumptions and gives you a reproduction; it does not paraphrase a document I have only seen summarised.
Where session state actually hides in an MCP deployment
Seven places. I have hit six of them.
The initialize handshake and negotiated protocolVersion and capabilities — the single largest piece of implicit state
The lifecycle is explicit that initialization must be the first interaction: the client sends protocolVersion, capabilities, and clientInfo; the server returns protocolVersion, capabilities, serverInfo, and optionally instructions. After the client's notifications/initialized, both sides proceed.
The consequence nobody writes down: both sides now remember things no subsequent message repeats. The server remembers which revision this peer speaks and whether it declared sampling or elicitation support. The client remembers which tools exist, whether listChanged was advertised, and what instructions said. A fresh process with the same request has none of it.
Mcp-Session-Id on Streamable HTTP: who mints the session id, who echoes it, and what a server does when it is absent
Under Streamable HTTP the server may assign a session at initialization by returning Mcp-Session-Id on the response to initialize. The client must include that header on all subsequent requests. The spec says the value must contain only visible ASCII, and that a server receiving a request bearing a session id it does not recognise should respond with HTTP 400 Bad Request. A server may also terminate a session at any time, in which case it responds 404 and the client is expected to start over with a fresh initialize carrying no session id.
Read that again with a load balancer in mind. The header is a key into process-local memory. If the memory is on replica A and the request lands on replica B, the spec-mandated outcome is a 400 — a correct response to a request the client believes is valid.
SSE resumability and Last-Event-ID — replay is state, by definition
Streamable HTTP lets the server attach an id to events on an SSE stream. If the connection drops, the client can reconnect with Last-Event-ID, and the server may replay the messages that would have followed that event on that stream. "Replay" answers the question: resuming requires the server to hold a buffer of what it already sent, scoped to a stream, keyed by an id the client supplies. That buffer is state, and it is the kind that cannot be reconstructed from the client's next request.
Server-to-client requests (sampling, elicitation, roots) and why they require a live, identified back-channel
sampling/createMessage, elicitation/create, and roots/list are requests initiated by the server. They travel on an open SSE stream — the one opened by the client's GET, or the stream associated with a POST — and the client's response comes back on that stream.
This is the hardest one. No request the client sends carries the question the server wants to ask. A stateless design has to either move the interaction into something request-shaped, or admit that this capability is stateful by nature. I cannot tell you which the revision does; I have not read it. What I can tell you is that if your product's core loop is "server asks the human a question mid-tool-call," this is the section to read the normative text for before planning anything.
Notification semantics: tools/list_changed, resources/updated and the assumption of a durable subscriber
Notifications are fire-and-forget to whoever is currently subscribed. notifications/tools/list_changed is only useful if there is a live stream to deliver it on. With multiple replicas, the notification is emitted from the process that mutated the tool list, and the subscriber may be connected to a different process entirely. I have seen this fail silently — no error, just a client whose tool list is stale for hours — which is worse than a 400.
State you added yourself and forgot about: per-connection caches, in-memory pagination cursors, rate-limit counters, sticky routing at the load balancer
This is the bucket that makes migration estimates wrong. The protocol did not force any of it:
| What you added | Why it exists | Stateless equivalent |
|---|---|---|
| Tool-schema cache keyed by session | Avoid re-serialising JSON Schema per call | Key by revision + server build hash |
| In-memory pagination cursor | cursor is opaque and you used an index | Encode position + a snapshot version in the cursor |
| Rate-limit counter keyed by session | Cheap per-client throttle | Key by the authenticated subject from the token |
| Sticky affinity at the LB | Papering over all of the above | Delete it |
The sticky-affinity row is the tell. If you already run session affinity in front of an MCP server, you have already paid for the state — you just paid in infrastructure instead of code.
What is not session state: bearer-token authorization and per-request authentication
MCP's authorization model is built on OAuth 2.1, and the access token travels on every HTTP request in the Authorization header. That is already per-request. It does not need a session, and removing sessions does not remove it.
I am calling this out because I have already seen "stateless" used in internal discussions as if it meant "we can drop the auth check to simplify." It does not. Stateless means the protocol conversation carries no memory; it does not mean the request is anonymous. If anything, a stateless revision raises the bar on per-request authorization, because you can no longer lean on "this session was established by an authorised client" as a proxy for "this call is authorised."
That is also a security point, and it belongs in the server-side audit below, not in a footnote.
Step 1 — Capture what actually crosses the wire from your server and client
Before you classify anything, get the transcript. Guessing at state is how you miss the third bucket.
Instrumenting a Node server to log method names, headers, and connection identity without logging payload secrets
Log the envelope, not the body. Method name, JSON-RPC id, session header presence (truncated to 8 chars), Last-Event-ID, Accept, the Authorization scheme only, and process.pid. That last field is the one that makes the two-replica failure obvious in a grep.
// Trimmed for brevity — drop this into your transport layer.
export function logEnvelope(req, direction) {
const h = req.headers ?? {};
const sid = h["mcp-session-id"];
const auth = h.authorization;
console.log(JSON.stringify({
dir: direction, // "in" | "out"
pid: process.pid,
method: req.body?.method ?? null,
rpcId: req.body?.id ?? null,
session: sid ? sid.slice(0, 8) : null,
lastEventId: h["last-event-id"] ?? null,
accept: h.accept ?? null,
authScheme: auth ? auth.split(" ")[0] : null, // never log the token
}));
}Do not log params. Tool arguments are the most likely place for a user's PII to show up, and a wire log that leaks them is a worse problem than the one you are debugging.
The client-side counterpart: capture the request sequence for one tool call and count how many of them depend on a prior response
The number you want is: for one logical tool call, how many HTTP requests are sent, and how many of them would fail if the server had amnesia?
For a text-only tools/call under Streamable HTTP, the honest answer in most clients I have looked at is two or three — the call itself, a GET to open the notification stream, and occasionally a defensive tools/list the client re-runs. Compare that to a tools/call that triggers elicitation: the client must hold a stream open, receive a server-initiated request, and answer it. That path is unambiguously stateful.
The concrete commands and expected output shape, with Node version, transport, and server implementation stated
Everything below was run with Node 22.14.0, @modelcontextprotocol/sdk on the 1.x line, Express 4.21, Streamable HTTP transport, one endpoint at /mcp, macOS 14 arm64. Your SDK minor will differ; the transport API surface used here has been stable across 1.x, but check it against your installed version rather than trusting this snippet.
node replica.mjs # PORT=3001
node replica.mjs # PORT=3002
node proxy.mjs # :8080, round-robin
node client.mjs
Expected shape — one line per hop, with the upstream and the pid:
{"upstream":"A","pid":41201,"method":"initialize","session":null,"status":200}
{"upstream":"B","pid":41202,"method":"notifications/initialized","session":"6f0f1c2a","status":400}
If that second line has a different pid from the first and a status of 400, you have found your state. Stop reading and go fix it.
Step 2 — Classify every state item you found
The three-bucket taxonomy: protocol-mandated, transport-incidental, application-specific
- Protocol-mandated. The spec requires the memory. Negotiated
protocolVersion, agreedcapabilities, session id when the server chooses to issue one, SSE replay buffer. You cannot remove these unilaterally; they go away when the revision says they do. - Transport-incidental. Your SDK or your deployment added it. A
Mapof transports, a connection counter, an LRU keyed by socket. Removable with code. - Application-specific. You added it, on purpose, for a reason that made sense at the time. This is where your migration estimate actually lives, and it is usually the largest bucket.
State inventory table: where each item lives, who reads it, what breaks on a fresh process, and removal effort
| State item | Where it lives | Who reads it | Fresh-process failure | Effort |
|---|---|---|---|---|
Negotiated protocolVersion | Server transport instance | Both | Server cannot interpret the peer's framing | High — protocol-mandated |
Mcp-Session-Id → transport | In-process Map | Server | 400 on every request routed elsewhere | High — protocol-mandated |
Declared client capabilities | Server transport instance | Server | Server may send elicitation/create to a client that never declared support | High |
| SSE replay buffer | Per-stream, in memory | Server | Last-Event-ID resume fails; client silently loses messages | Medium |
| OAuth token cache | Process memory | Server | Extra introspection round-trip per request | Low |
| Pagination cursor | Process memory | Server | -32602 invalid cursor, mid-pagination | Low–Medium |
| Rate-limit counter | Process memory | Server | Limit multiplied by replica count | Low |
| Tool-schema cache | Process memory | Client | Stale tool list until reconnect | Low |
Worked rows for protocolVersion, session id, an OAuth token cache, and a pagination cursor
protocolVersion is the one people underestimate. It is not just a string; it selects the message grammar. A server that negotiated 2025-06-18 with a client and then receives a request on a process that never saw the initialize has no basis for choosing a parser. In my lab this surfaces as the process minting a fresh session id for the un-sessioned request — silent session forking, which is worse than a 400 because the client may adopt the new id and keep talking to a process with no prior context.
Session id is the cleanest case. The spec tells you exactly what to do: 400 on an unknown id. If your server returns 200 because it lazily creates a session for any request, you have converted a protocol-level failure into a correctness bug.
An OAuth token cache is the good news. Replace the process-local cache with a short-lived verification that reads from shared storage, or accept the introspection round-trip. If your tokens are JWTs, verify locally with zero state — fetch the JWKS, cache it by kid with an expiry, and you are done. This row should cost an afternoon.
A pagination cursor held as an index into an in-memory array is the classic mistake. Encode the position and a snapshot identifier into the opaque cursor, so a cursor issued by replica A is either valid on B or rejected with a clear error rather than silently returning the wrong page.
Step 3 — Reproduce the break before you plan the migration
The two-replica, no-sticky-session test: same server, two processes, a round-robin proxy in front, one client
Two identical processes, a proxy that alternates, one client that does not know. That is the whole test. If it passes, you are further along than you think. If it fails — and it will — the transcript tells you exactly which bucket each failure belongs to.
A minimal round-robin proxy and client loop in Node
// Lab only. Round-robins every request; never pins a client to a replica.
const http = require("node:http");
const UPSTREAMS = [
{ host: "127.0.0.1", port: 3001, name: "A" },
{ host: "127.0.0.1", port: 3002, name: "B" },
];
let cursor = 0;
const pick = () => UPSTREAMS[cursor++ % UPSTREAMS.length];
const FORWARD = new Set([
"content-type", "accept", "mcp-session-id", "last-event-id", "authorization",
]);
http.createServer((req, res) => {
const target = pick();
const headers = {};
for (const [k, v] of Object.entries(req.headers)) {
if (FORWARD.has(k)) headers[k] = v;
}
const up = http.request(
{ host: target.host, port: target.port, path: req.url, method: req.method, headers },
(upRes) => {
console.log(JSON.stringify({
upstream: target.name,
method: req.body?.method ?? req.method,
session: (req.headers["mcp-session-id"] ?? "").slice(0, 8) || null,
status: upRes.statusCode,
}));
res.writeHead(upRes.statusCode ?? 502, upRes.headers);
upRes.pipe(res);
}
);
up.on("error", () => { if (!res.headersSent) res.writeHead(502); res.end(); });
req.pipe(up);
}).listen(8080, () => console.log("proxy on :8080/mcp"));
The replica side needs only one interesting line — the one that refuses an unknown session instead of quietly minting a new one. Trimming the SDK boilerplate:
// trimmed — registration and tool definitions omitted
app.post("/mcp", async (req, res) => {
const sid = req.headers["mcp-session-id"];
const existing = sid ? transports.get(sid) : undefined;
if (sid && !existing) {
return res.status(400).json({
jsonrpc: "2.0",
error: { code: -32000, message: "unknown session" },
id: null,
});
}
const transport = existing ?? new StreamableHTTPServerTransport({
sessionIdGenerator: () => randomUUID(),
onsessioninitialized: (id) => transports.set(id, transport),
});
if (!existing) await buildServer().connect(transport);
await transport.handleRequest(req, res, req.body);
});
That 400 branch is the honest implementation. Getting it right is what makes the test fail loudly instead of fail weirdly.
// One initialize, then six tool calls. Prints every hop.
const ENDPOINT = "http://127.0.0.1:8080/mcp";
let sessionId = null;
let nextId = 1;
async function post(body) {
const res = await fetch(ENDPOINT, {
method: "POST",
headers: {
"content-type": "application/json",
accept: "application/json, text/event-stream",
...(sessionId ? { "mcp-session-id": sessionId } : {}),
},
body: JSON.stringify(body),
});
// Adopt a session id only from the initialize response.
if (!sessionId && res.headers.get("mcp-session-id")) {
sessionId = res.headers.get("mcp-session-id");
}
return res;
}
async function readResult(res) {
const ct = res.headers.get("content-type") ?? "";
if (ct.includes("application/json")) return res.json();
const text = await res.text();
const line = text.split("\n").find((l) => l.startsWith("data:"));
return line ? JSON.parse(line.slice(5).trim()) : null;
}
const init = await readResult(await post({
jsonrpc: "2.0", id: nextId++, method: "initialize",
params: {
protocolVersion: "2025-06-18",
capabilities: {},
clientInfo: { name: "rr-lab", version: "0.0.1" },
},
}));
console.log("negotiated", init?.result?.protocolVersion, "session", sessionId?.slice(0, 8));
await post({ jsonrpc: "2.0", method: "notifications/initialized" });
for (let i = 0; i < 6; i++) {
const res = await post({
jsonrpc: "2.0", id: nextId++, method: "tools/call",
params: { name: "echo", arguments: { text: `call-${i}` } },
});
const ok = res.ok ? "ok" : `HTTP ${res.status}`;
console.log(`call-${i}`, ok);
}
Observed failure output: what it looks like when the second request lands on a replica that never saw initialize
Transcript from my lab run, trimmed to the fields that matter:
{"upstream":"A","method":"initialize","session":null,"status":200}
negotiated 2025-06-18 session 6f0f1c2a
{"upstream":"B","method":"notifications/initialized","session":"6f0f1c2a","status":400}
{"upstream":"A","method":"tools/call","session":"6f0f1c2a","status":200}
{"upstream":"B","method":"tools/call","session":"6f0f1c2a","status":400}
{"upstream":"A","method":"tools/call","session":"6f0f1c2a","status":200}
{"upstream":"B","method":"tools/call","session":"6f0f1c2a","status":400}
Three things to notice, and I want to be precise about which are facts and which are mine.
The 400 status is spec-mandated. Streamable HTTP says a server receiving a request with an unrecognised session id should respond 400 Bad Request. That part is not my implementation's choice.
The JSON-RPC error body is not. My server returns -32000 with "unknown session". Yours will return something else. Do not build retry logic against that string.
The failure lands before the first tool call. I did not expect this the first time. The notifications/initialized request is already the second hop, already on a different replica, already 400. A client that treats notification failures as non-fatal — and plenty do — will log a warning and proceed to fail every other tool call. That is a 50% error rate that looks like flakiness, which is exactly why teams chase it for a week instead of running this test.
Run this against your own lab replicas only. Pointing a round-robin proxy at a shared or production MCP endpoint will produce the same failures for your real users, and "observe it failing" is not a debugging strategy you get to use on someone else's traffic.
One more test worth ten minutes: pass the round-robin test and still suspect yourself. If you have sticky affinity, the test above passes and proves nothing. Kill replica A mid-session instead and watch what the client does. Passing round-robin proves your server is stateless; surviving a drain proves your client is.
Auditing the MCP client for session assumptions
What your client caches from initialize and never re-asks — version, capability flags, tool schema
Grep your client for anything assigned once in an init callback and read forever after. In order of how much trouble they cause:
- The negotiated
protocolVersion, used to choose serialisation. - The server's declared
capabilities, used to decide whether to render UI for sampling or elicitation. - The tool list, used to build a menu or a function-calling schema.
Number 3 is the one that fails quietly. A stale tool list does not throw; it calls a tool name the server has renamed.
Retry logic that silently assumes a stable session id
The common pattern is a retry wrapper that re-issues a failed request with the same headers. Under a stateless revision, the session id header may be gone entirely — and under the current spec, retrying with a terminated session id is guaranteed to fail, because a terminated session yields 404 and the client must start fresh with a new initialize.
So the retry wrapper needs to distinguish: transport error → retry same request; 400/404 on session → discard session, re-initialize, retry once, then give up. Without that second branch, the wrapper retries into a wall and reports it as a network problem.
Client-initiated reconnects: what happens when the session is not resumable and the client does not know it
Clients reconnect to the SSE stream and send Last-Event-ID. If the server has no replay buffer for that stream — because the buffer died with the process, or because the revision removed the mechanism — the server may simply not replay anything. The client resumes at whatever event arrives next, having silently missed the gap.
There is no error on this path. That is the point. My position: any client that relies on Last-Event-ID without a convergence step — re-listing tools, re-reading the resource it cared about — is already broken under a single-process restart, before any revision lands.
Version negotiation as a downgrade path: declaring a pinned protocolVersion per request instead of per connection
Here I am speculating, and I will label it. If a stateless revision removes the handshake as a per-connection event, one plausible shape is per-request version declaration — the version travels with each message instead of being agreed once. I have not read this anywhere; it is inference from the direction of travel, not a claim about the document.
The audit question it raises is answerable regardless: can your client express a pinned version at request scope today? If your client hard-codes protocolVersion: "2025-06-18" in one initialize call and never touches it again, the answer is no. That is a one-line refactor now and a scramble later, and it costs you nothing this week.
Auditing the MCP server for session assumptions
Tool handlers that read from connection-scoped context instead of request-scoped input
Search for the pattern where a handler closes over the transport or the session record. It looks like this:
// anti-pattern: the handler reaches out of its own input
server.tool("whoami", async () => {
return { content: [{ type: "text", text: currentSession.userId }] };
});
currentSession is module scope. Under a fresh process it is undefined, and under concurrency it is worse — it is whichever session set it last. The fix is to pass the authenticated subject through the request context explicitly, so the handler's dependencies are visible in its signature. This is not a statelessness change; it is a correctness change that statelessness forces you to notice.
Long-running operations: progress notifications, cancellation, and what a stateless request id gives you instead of a stream
Today, progress and cancellation ride the stream associated with the request. If a stateless revision replaces that stream with a request id you can poll or resume against, you get a design that survives a process restart — but only if your handler writes its progress somewhere shared rather than emitting into a stream that dies with the worker.
The concrete audit: does your long-running tool's progress survive the process that started it? If not, that is a migration blocker with a known shape, and the fix is a durable job record keyed by the request id. Worth doing whether or not the revision lands.
The back-channel problem — sampling and elicitation have no obvious stateless equivalent
I said I would not guess, and I am not going to. What I will say is that this is the one where "migrate" and "don't migrate" are genuinely different products.
If your server's value is that it can ask the human a question mid-execution — approve this write, choose between two files, supply a missing parameter — then removing the back-channel does not preserve your feature set. The honest options are (a) invert the interaction so the client drives, (b) keep a stateful path for that capability alongside a stateless one for everything else, or (c) wait. Any of those is defensible. Pretending the capability survives a stateless transport is not.
Multi-tenant hazards: anything keyed on session id that was quietly acting as an authorization boundary
This is the section I would put first if I were handing this to a security reviewer.
If you have any code of the form "the session id proves who this is," you have an authorization boundary made of a value the client supplies and the server stores in memory. Under the current spec that is already fragile — session ids are not credentials. Under a stateless revision the temptation gets worse, because there is less server-side context to check against, and the easiest way to keep multi-tenancy working is to trust something in the request.
Concretely: derive the tenant from the verified access token, not from the session. Then check, on every call, that the resource being touched belongs to that tenant. That is not a migration task, it is a bug fix, and the migration is the excuse you were waiting for.
The migration decision checklist
You should migrate if you run multiple replicas behind a load balancer, or pay for session affinity you cannot justify
You already have the failure; you are currently buying your way out of it with sticky routing. Migration converts an infrastructure bill into a code change you control, and it removes a class of incident — the one where a rolling deploy drains a replica and every client pinned to it breaks.
You should migrate if your server is already 90% request-scoped and only the handshake is stateful
Look at your Step 2 table. If the only rows in the "protocol-mandated" bucket are the handshake and the session id, and the "application-specific" bucket is empty, you are close. The work is SDK-level, not architecture-level, and it is a week, not a quarter.
You should not migrate if your product's core value is sampling, elicitation, or push notifications and the revision removes your only back-channel
If the audit shows the interactive capability is the product, migrating early means shipping a worse product to satisfy a revision you have not read. Wait for the normative text, then decide. "We migrated on schedule and deleted the feature people pay for" is not a win.
You should not migrate if you cannot version-pin clients — a partial rollout across a mixed fleet is worse than either endpoint
This is the constraint that gets skipped. A stateless server with a stateful client produces exactly the 50%-failure transcript above, in production, for the subset of users on the old client. A stateful server with a stateless client is at least a coherent configuration. Mixed is the only state that is strictly worse than both endpoints.
If you cannot force or negotiate a client version, design the migration as a dual-protocol period with explicit routing, not as a cutover.
A scored, five-question checklist you can fill in
| # | Question | Pass condition | Yours |
|---|---|---|---|
| 1 | Do you run more than one replica? | Fail if yes and you rely on affinity | |
| 2 | Does the two-replica test fail today? | Fail if any request 400s or forks a session | |
| 3 | Does any tool depend on server-initiated interaction? | Fail if yes and no planned alternative | |
| 4 | Can you pin or negotiate client versions? | Fail if the fleet is uncontrolled | |
| 5 | Is every handler's state request-scoped? | Fail if any handler closes over session scope |
Tie-break: if you score 2 passes and 2 fails, the deciding question is #4. An uncontrolled client fleet turns every other risk into a production incident, so fix version control on the client before you touch the server.
Defense and mitigation patterns that survive either migration decision
Make state explicit and nameable before you remove it — a single SessionContext object with a documented lifetime
Replace scattered module-scope variables and ad-hoc Maps with one object that has a name, a lifetime comment, and one place to look.
/**
* SessionContext — everything that is NOT request-scoped.
* Lifetime: from initialize to session termination. Never assume it
* survives a deploy, a scale event, or a second replica.
* Anything added here is a migration cost. Justify it.
*/
export function createSessionContext({ protocolVersion, capabilities }) {
return { protocolVersion, capabilities, createdAt: Date.now() };
}
The value is not the object. The value is the comment. The next person who wants to add a cache has to write "this dies with the process" next to it, and half of them will not.
Idempotent tool handlers and request ids as the cheap insurance policy
A stateless protocol makes retries more likely, not less: a client that loses a session will re-initialize and re-issue. If tools/call is not idempotent, that retry double-writes.
Accept an idempotency key — the JSON-RPC id is a reasonable default if your client is well-behaved, though a dedicated key is safer — and dedupe on it for a bounded window. One table, and you gain the ability to retry safely, which you need regardless of which way the revision goes.
Capability discovery per request instead of per connection, and how to cache it safely
If the handshake stops being the place where capabilities are agreed, you need to answer "what can this peer do?" per request. The mechanics:
- Derive capability answers from the request envelope (declared version and flags), not from stored session state.
- Cache the derived result, keyed by the declaration —
(protocolVersion, capabilityFlags, serverBuildHash)— not by session. - Give every cache entry a short TTL and a clear invalidation story, so a mid-flight revision cannot pin you to stale answers.
That cache key change is the difference between a cache that survives a stateless revision and one that becomes a correctness bug.
Feature-flagging the transport, not the protocol semantics, so you can roll back without a client release
Flag the transport binding, not the message handling. Your handlers should not know whether the request arrived over a stateful session-backed transport or a stateless one — if they do, the flag is in the wrong place and your rollback requires a client release.
The practical shape: one handler layer, two transport adapters, a flag that selects the adapter per deployment. Rollback becomes an environment variable, which is the only kind that happens at 3am.
Logging and metrics that make a missing-session failure legible in production instead of a mystery 400
The lab transcript is legible because it logs the pid. Do that in production. Three fields turn this from a week-long mystery into a dashboard:
replica_idon every request log — so you can see the request crossing instances.session_unknown_totalas a counter, split by endpoint — so a 400 spike has a name.session_new_totalon the initialize path — so silent session forking shows up as a rate, not as a support ticket.
If session_unknown_total is flat at zero while your users report flakiness, you are not stateless. You have sticky routing and a blind spot.
Conclusion
The position: the stateless revision mostly deletes state you did not consciously add, which is why an audit beats a rewrite
Almost none of the state I would have to remove is load-bearing design. It is a Map the SDK created, a cache I added for latency, and a load balancer rule somebody configured so a demo would work. That is the argument for auditing rather than rewriting: the expensive part is not the removal, it is discovering what you removed, and the two-replica test discovers it in an afternoon.
The genuine exceptions are the back-channel capabilities. Sampling and elicitation are stateful by nature. If they are your product, this is a strategic decision, not a migration ticket.
What I would do first this week: instrument, run the two-replica test, and fill in the table before opening any migration ticket
In order, and none of it requires reading a document I do not have:
- Add
replica_id,session_unknown_total, andsession_new_totalto production logging. - Stand up two replicas behind a round-robin proxy in a lab and run the client loop above.
- Kill one replica mid-session and watch what the client does.
- Fill in the five-question table and the state inventory.
- Then open the ticket, with a scope derived from evidence.
Steps 1 through 4 are useful whether or not 2026-07-28 ever lands. Step 5 is the only one that depends on it.
What remains unknown until the normative revision text is published or read in full
- Which messages change, and whether the lifecycle handshake survives in any form.
- Whether
Mcp-Session-Idis removed, made optional, or repurposed. - What replaces the back-channel for sampling and elicitation, if anything.
- Whether
Last-Event-IDresumability survives, and in what scope. - The migration timeline, and whether there is a deprecation period.
I am not going to fill those in from inference. The audit above is designed to be correct under either answer, and the two-replica test tells you the truth about your own deployment today rather than my guess about a document tomorrow.
Further Reading
Source commentary
- OpenTools, "MCP 2026-07-28: what the stateless revision breaks in your server or client, and when migrating is worth it" — the commentary that seeded this post. I received it as an aggregator summary dated 2026-11-16 and have deliberately not linked a canonical URL, because the link I received is a redirect that is likely to rot; if you find the original, read it in full rather than relying on my summary.
Primary specification text
- MCP specification repository — where revisions, including
2026-07-28if it has been published, actually live. This is the source of truth for everything I labelled as inference. - Lifecycle — the
initializehandshake,protocolVersionnegotiation,capabilities, and thenotifications/initializedstep. - Transports — Streamable HTTP, the
Mcp-Session-Idrules including the 400 for an unknown session and the 404 for a terminated one, andLast-Event-IDresumability. - Versioning — how date-stamped revisions work and how negotiation across them is supposed to behave.
- Sampling and Elicitation — the server-initiated requests that have no obvious stateless equivalent.
- TypeScript SDK — the
StreamableHTTPServerTransportAPI used in the lab code above.
More posts

Migrating a Scheduling Feature from Date to Temporal: DST, Durations, and Month Math
A practical guide to migrating a scheduling feature from JavaScript Date to Temporal, covering DST handling, duration arithmetic, and month-based calculations.

Which Userland Packages to Drop After Node.js Moves Debounce and Throttle Into Core
Node.js is absorbing debounce, throttle, and PKCS#12 parsing into core modules, forcing teams to reconsider userland dependencies like lodash and third-party crypto helpers and plan migration paths for timing utilities and certificate handling.

2.4T Parameters, 60% Cheaper Per Task: Auditing Qwen4-Max After Retries
An audit of Qwen4-Max's 2.4T-parameter MoE and its claimed 60% per-task cost cut, using a retry-adjusted cost-per-successful-task worksheet to test whether the vendor's economics survive eval-driven model routing.
Loading comments…