# MCP 2026-07-28: what changed and how to build a stateless server (/blog/mcp-2026-07-28-stateless-migration)

Published: 2026-11-20

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](https://github.com/basementstudio/xmcp/tree/main/examples/stateless-http).

## What changed in MCP 2026-07-28?

The [official changelog](https://modelcontextprotocol.io/specification/2026-07-28/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:

```typescript title="src/tools/add-item.ts"
import { z } from "zod";
import type { InferSchema, ToolMetadata } from "xmcp";
import { mintCartHandle, readCartHandle } from "../lib/cart-handle";
import { SKUS } from "../lib/catalog";

export const schema = {
  cart: z.string().describe("The cart handle returned by the previous call"),
  sku: z.enum(SKUS).describe("The product to add"),
  quantity: z.number().int().min(1).max(10).describe("How many to add"),
};

export const metadata: ToolMetadata = {
  name: "add-item",
  description:
    "Add a product to a cart. Returns a new cart handle that replaces the one passed in.",
};

export default function addItem({
  cart,
  sku,
  quantity,
}: InferSchema<typeof schema>) {
  const items = [...readCartHandle(cart), { sku, quantity }];
  return { structuredContent: { cart: mintCartHandle(items), items } };
}
```

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:

```typescript title="src/lib/cart-handle.ts"
import { createHmac, timingSafeEqual } from "node:crypto";

export interface CartItem {
  sku: string;
  quantity: number;
}

function signingKey() {
  const secret = process.env.CART_HANDLE_SECRET;
  if (!secret) {
    throw new Error("Set CART_HANDLE_SECRET to sign cart handles");
  }
  return secret;
}

function sign(payload: string) {
  return createHmac("sha256", signingKey()).update(payload).digest("base64url");
}

export function mintCartHandle(items: CartItem[]) {
  const payload = Buffer.from(JSON.stringify(items)).toString("base64url");
  return `${payload}.${sign(payload)}`;
}

export function readCartHandle(handle: string): CartItem[] {
  const [payload, signature] = handle.split(".");
  if (!payload || !signature) {
    throw new Error("Malformed cart handle");
  }
  const expected = Buffer.from(sign(payload));
  const received = Buffer.from(signature);
  if (
    expected.length !== received.length ||
    !timingSafeEqual(expected, received)
  ) {
    throw new Error("Cart handle was not issued by this server");
  }
  return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
}
```

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()`:

```typescript title="src/tools/describe-caller.ts"
import { getRequestContext, type ToolMetadata } from "xmcp";

export const metadata: ToolMetadata = {
  name: "describe-caller",
  description: "Report the client identity sent with the current request",
  annotations: { readOnlyHint: true },
};

export default function describeCaller() {
  const { clientInfo, http } = getRequestContext();
  return {
    structuredContent: {
      client: clientInfo ?? null,
      requestId: http?.id ?? null,
    },
  };
}
```

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](/docs/guides/authentication) 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:

```bash
curl http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: create-cart' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create-cart","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"stateless-guide","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
```

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:

1. **State.** Replace anything keyed by session with a handle, as above.
2. **User input.** `extra.elicit()` relies on server-initiated requests and only works on 2025-era connections. Return `inputRequired()` to serve both generations. See [Human-in-the-loop MCP tools](/blog/mcp-input-required-human-in-the-loop).
3. **Custom CORS.** xmcp adds `mcp-method`, `mcp-name`, and the other MCP headers to an `http.cors.allowedHeaders` array for you. Only a string value is used as written, so list them yourself in that case.
4. **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](/blog/mcp-server-observability-tracing).

## Run the example

Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:

```bash
pnpm install
pnpm build
pnpm --filter stateless-http build
CART_HANDLE_SECRET=local-demo-secret pnpm --filter stateless-http start
```

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](/blog/mcp-tool-permissions-rbac) 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](https://blog.modelcontextprotocol.io/posts/mcp-release-cycle/) 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](/blog/xmcp-v1) for how xmcp moved to the 2026-07-28 revision.
* [Transports](/docs/configuration/transports) for HTTP options, subscription limits, and CORS.
* [Request context](/docs/core-concepts/request-context) for everything a handler can read about the current request.
