MCP Server Sessions

A spec 2025 client opens a session, then sends the same session id on each later request. On a deploy with more than one instance, a later request can reach an instance that did not open the session. That request gets 404.

Route each session to one instance. Use the mcp-session-id header as the key for sticky routing on your load balancer. If you cannot route by header, turn sessions off.

Where a session lives#

A spec 2025 session keeps a live connection object. That object stays in the process that opened the session. Another process cannot read it.

• The client sends the session id on the mcp-session-id header.
• A request with an unknown session id gets 404 Session not found.
• A spec 2026 client sends no session id. Any instance can serve a spec 2026 request.

When a session closes#

A session closes in two cases:

• The client sends DELETE with its session id.
• The session gets no request for 30 minutes.

The server checks for idle sessions when a request comes in. After a session closes, the client must open a new session.

The server has no limit on the number of open sessions. Each session stays in memory until it closes, which can take 30 minutes. On a public server, set auth, or limit new sessions at your proxy.

Turn sessions off#

On Cloudflare Workers, and on other hosts with many instances, a request can reach any instance. Sticky routing by header is not always possible. Set sessions to 'reject'. The server then opens no session, and a spec 2025 request gets the SDK rejection. A spec 2026 request works as before.

import { createMCPServer } from '@tanstack/ai-mcp/server'

const server = createMCPServer({
  name: 'weather',
  version: '1.0.0',
  sessions: 'reject',
})

A client that speaks only spec 2025 cannot use that server.

Sessions and auth#

When the server has auth, the session belongs to the caller that opened it: the clientId of the token plus its sub claim. A request from another caller gets 404, the same as an unknown id. MCP Server Auth shows how the verifier sets them.

A client on one instance opens a session, sends its requests, and gets its answers from that same instance.