MCP 2026-07-28: what changed and how to build a stateless server
The 2026-07-28 MCP revision removed sessions and the initialize handshake. Here is what changed, what it means for your server, and how to keep state across tool calls without a session.
MCP revision 2026-07-28 made the protocol stateless. There is no initialize handshake and no Mcp-Session-Id: every request carries its own protocol version, client identity, and capabilities. State that has to span several tool calls now travels in a handle the server mints and the client passes back as an ordinary tool argument.
This guide summarizes the changes and builds the handle pattern with the repository's stateless HTTP example.
What changed in MCP 2026-07-28?
The official changelog lists the full set. These are the changes that affect how you build a server:
| Area | 2025-11-25 | 2026-07-28 |
|---|---|---|
| Connection setup | initialize handshake before any request | No handshake. Each request carries version, identity, and capabilities |
| Sessions | Mcp-Session-Id header on Streamable HTTP | Removed. Cross-call state uses server-minted handles passed as tool arguments |
| Discovery | Capabilities learned during initialize | server/discover returns supported versions, capabilities, and identity |
| Asking the user | Server-initiated elicitation/create | The tool returns an input_required result and the client retries |
| Change notices | resources/subscribe and a GET stream | One subscriptions/listen stream |
| Caching | No freshness hints on listings | ttlMs and cacheScope on listings and resource reads |
| Results | No result type field | Every result has resultType: complete or input_required |
| HTTP headers | MCP-Protocol-Version | Mcp-Method and Mcp-Name are also required on POSTs |
| Broken streams | Resume with Last-Event-ID | Resumability removed. Send the request again with a new ID |
| Tasks | Experimental, in the core specification | Moved to the io.modelcontextprotocol/tasks extension |
The revision also deprecates Roots, Sampling, and Logging, the old HTTP+SSE transport, and OAuth Dynamic Client Registration in favor of Client ID Metadata Documents. Deprecated features keep working during a deprecation window of at least 12 months.
What does a stateless protocol mean for my server?
Any instance of your server can answer any request. A request does not depend on one that came before it, so there is no session store to share between instances and nothing to lose when a process restarts or a serverless function goes cold.
It also means two habits stop working:
- Remembering the client. You cannot read the client's name or capabilities from an earlier
initialize. They arrive with each request. - Remembering the conversation. You cannot keep a cart, a draft, or a cursor in memory keyed by session ID. There is no session ID.
xmcp's HTTP transport builds a fresh server for each request, so an xmcp server does not need a rewrite. What changes is how you design tools that need state.
How do I keep state across tool calls without a session?
Return a handle from one tool and accept it as an argument in the next. The model passes it along like any other value.
The example is a shopping cart. create-cart returns a handle, add-item takes a handle and returns a new one, and view-cart reads it:
Say what to do with the handle in the tool's description and in the argument's description. That is what tells the model to thread it through.
A handle comes back from the client, so treat it as untrusted input. Here the handle holds the cart itself, signed with an HMAC so it cannot be edited:
The key comes from CART_HANDLE_SECRET, and every instance needs the same value. That shared secret is what lets any instance verify a handle after a restart or a cold start. The example refuses to sign without it instead of falling back to a key that only one process knows.
There are two ways to back a handle:
| Handle holds | Good for | Requires |
|---|---|---|
| The state itself | Small values, no infrastructure | A signing secret shared by every instance |
| A database key | Large or sensitive state | A database, and a check that the caller owns the record |
A signed handle is readable by the client. Do not put secrets in it.
How does the server know who is calling?
The client sends its identity with each request, under io.modelcontextprotocol/clientInfo in the request's _meta. In xmcp, read it with getRequestContext():
A request that omits its identity gets null. Nothing is recovered from an earlier request. Client identity is supplied by the client and is not authentication; use OAuth or an API key to know who the user is.
Does my server still work with older clients?
Yes, with xmcp. The same HTTP endpoint serves both protocol generations: requests with the 2026-07-28 envelope are handled natively, and clients that start with the classic initialize handshake are served through a stateless fallback. Neither path issues an Mcp-Session-Id.
A 2026-07-28 request looks like this:
A 2025-11-25 client can call the same tool without the envelope, and repeat its identity in x-mcp-client-name and x-mcp-client-version headers when a tool needs it.
What do I need to change in an xmcp server?
For most servers, upgrading to xmcp v1 or later is the whole migration. Tools, prompts, and resources keep working. Check these four things:
- State. Replace anything keyed by session with a handle, as above.
- User input.
extra.elicit()relies on server-initiated requests and only works on 2025-era connections. ReturninputRequired()to serve both generations. See Human-in-the-loop MCP tools. - Custom CORS. xmcp adds
mcp-method,mcp-name, and the other MCP headers to anhttp.cors.allowedHeadersarray for you. Only a string value is used as written, so list them yourself in that case. - Deprecated features. Sampling and MCP log notifications still work but are deprecated. Plan to call your model provider directly and to log on the server.
Run the example
Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:
The secret here is a local demo value. Send the request above, copy structuredContent.cart from the result, and pass it to add-item and view-cart. The example's README has each request. Edit one character of the handle and the call fails with Cart handle was not issued by this server.
Common questions
Is Mcp-Session-Id still part of MCP?
No. The 2026-07-28 revision removed Mcp-Session-Id from Streamable HTTP. State that spans calls uses handles the server mints and the client passes back as tool arguments.
What replaced the initialize handshake?
Two things. Each request carries the protocol version, client identity, and client capabilities in its _meta. And server/discover lets a client ask for the server's supported versions, capabilities, and identity before it sends anything else.
Where should I store state if not in a session?
In a handle. For small state, sign the state and use it as the handle. For larger state, store it in a database and hand out a key. Either way the handle is an ordinary tool argument, so any instance can serve the next call.
Do the tool, prompt, and resource listings still vary per connection?
No. Without sessions, tools/list, prompts/list, and resources/list do not vary per connection. They can still vary per caller when you authorize components from the request's authentication.
What happens when a streamed response disconnects?
The in-flight request is lost. SSE resumability and Last-Event-ID were removed, so the client sends the request again with a new request ID.
When is the next MCP specification release?
March 30, 2027. The maintainers announced a six-month release schedule in November 2026, with releases generally on the last Tuesday of March and September.
Next steps
- xmcp v1 is here for how xmcp moved to the 2026-07-28 revision.
- Transports for HTTP options, subscription limits, and CORS.
- Request context for everything a handler can read about the current request.
