MCP Server Sessions

Some MCP clients still speak only spec 2025. Spec 2025 can use sessions, and a session lives in one process. On a deploy with many instances, sessions need sticky routing.

By default, createMCPServer keeps no spec 2025 session, so any instance can answer any request. Set the sessions option only when you need something else:

• 'stateless' (the default): no session. It works on any host.
• 'memory': sessions in the process. The server can ask a spec 2025 client for input or a sample.
• 'reject': spec 2026 only.

Serve spec 2025 without sessions#

You do not have to set anything. A new server answers each spec 2025 request, and no session is kept. A spec 2026 client sends no session id either, so any instance can serve both.

Without a session, the server cannot send a request back to a spec 2025 client. For that client:

• ctx.context.requestInput throws an error that names the sessions option.
• ctx.context.sample calls the sample option of the server. Without that option, it throws.

A spec 2026 client gets requestInput and sample with no session.

Keep sessions for input and sampling#

To ask a spec 2025 client for input or a sample, set sessions to 'memory':

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

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

serveMCPStdio uses 'memory' when you do not set sessions. A stdio process serves one client, so a session costs nothing there.

Route each session to one instance#

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.

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. Use the mcp-session-id header as the key for sticky routing on your load balancer.

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.

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.

Turn spec 2025 off#

To serve spec 2026 only, set sessions to 'reject'. A spec 2025 request then gets the SDK rejection. A client that speaks only spec 2025 cannot use that server.

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

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

Each spec 2025 client now gets the behavior that you chose.