Skip to main content

What are stateless MCP servers?

A stateful MCP server keeps a connection or an Mcp-Session-Id for each client, so the server knows which requests belong together. A stateless server keeps nothing between requests: each request is an independent HTTP call, and often a new server instance handles it. This makes horizontal scaling simple, and the MCP protocol version of 2026-07-28 makes stateless servers the standard. AgentCat needs no stateless option in any SDK. The same tracking code works on stateless HTTP, stateful HTTP, and stdio.

Track each server instance

A stateless server often creates a new server object for each request, in a factory function that your MCP library calls. Each track() call tracks one instance, so the call goes inside that factory. This is the TypeScript example from its setup page:
The SDKs share one event queue among all tracked instances of a process, so a track() call for each request costs little. Some SDKs need no extra code: in C#, WithAgentCat() tracks each server that stateless HTTP builds, and the PHP framework bridges track every server that they build.

How sessions work without server state

AgentCat does not depend on the transport to group calls into sessions. It adds a session_id parameter to each tool:
  1. On the first call of a task, the agent sends start (or no value). The result starts with a text block that gives the agent a new ses_ ID.
  2. The agent sends that ID on its later calls, so the calls of one task share a session, whichever server instance answers them.
  3. AgentCat removes the parameter before your tool runs, so your code never sees it.
If your server already has its own task or conversation ID, a resolveSessionId hook (named for the style of each language) can give it to AgentCat instead. AgentCat then derives a fixed session from your value and adds no session_id parameter.

Why identifying users matters

Sessions tell you which calls belong to one task. Identity tells you which user each session belongs to, so that you can follow one user across many tasks. On a stateless server, the identify hook runs on each tool call of each instance, so we recommend a hook that reads the request or a cheap cache. See Identifying Users.

Stateless servers in your language

Each setup page shows where the tracking code goes in a stateless server, and each reference page describes the transport details: