Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

context: stop documenting session_id as a cross-request key (#5862)

nate nowack70ac0ce96bb7
diff --git a/docs/servers/context.mdx b/docs/servers/context.mdx
index 609fdb03e..3ecdce61c 100644
--- a/docs/servers/context.mdx
+++ b/docs/servers/context.mdx
@@ -344,7 +344,7 @@ async def request_info(ctx: Context) -> dict:
- **`ctx.request_id -> str`**: Get the unique ID for the current MCP request
- **`ctx.client_id -> str | None`**: Get the ID of the client making the request, if provided during initialization
-- **`ctx.session_id -> str`**: Get the MCP session ID for session-based data sharing. Raises `RuntimeError` if the MCP session is not yet established.
+- **`ctx.session_id -> str`**: Get the identifier of the current MCP connection. It's stable for the session on handshake-era connections but new on every request on 2026-07-28 connections, so don't use it to share data between calls; use [Session State](/servers/sessions) instead. Raises `RuntimeError` if the MCP session is not yet established.
#### Request Context Availability
diff --git a/fastmcp_slim/fastmcp/server/context.py b/fastmcp_slim/fastmcp/server/context.py
index 1394c4025..7a8a0dc34 100644
--- a/fastmcp_slim/fastmcp/server/context.py
+++ b/fastmcp_slim/fastmcp/server/context.py
@@ -174,7 +174,7 @@ class Context:
request_id = ctx.request_id
client_id = ctx.client_id
- # Manage state across the session (persists across requests)
+ # Manage state (persists across requests on handshake-era sessions)
await ctx.set_state("key", "value")
value = await ctx.get_state("key")
@@ -185,14 +185,12 @@ class Context:
```
State Management:
- Context provides session-scoped state that persists across requests within
- the same MCP session. State is automatically keyed by session, ensuring
- isolation between different clients.
-
- State set during `on_initialize` middleware will persist to subsequent tool
- calls when using the same session object (STDIO, SSE, single-server HTTP).
- For distributed/serverless HTTP deployments where different machines handle
- the init and tool calls, state is isolated by the mcp-session-id header.
+ Context state is keyed by `session_id`. On handshake-era (legacy)
+ connections that identifier lasts for the MCP session, so state persists
+ across requests and is isolated between clients. On 2026-07-28 connections,
+ which `Client` negotiates by default, every request is a fresh connection,
+ so state does not carry over to the next request. Use
+ [Session State](/servers/sessions) for data that must outlive a request.
The context parameter name can be anything as long as it's annotated with Context.
The context is optional - tools that don't need it can omit the parameter.
@@ -714,27 +712,22 @@ class Context:
@property
def session_id(self) -> str:
- """Get the MCP session ID for ALL transports.
+ """Get the identifier of the current MCP connection.
- Returns the session ID that can be used as a key for session-based
- data storage (e.g., Redis) to share data between tool calls within
- the same client session.
+ On handshake-era (legacy) connections this is stable for the whole MCP
+ session: the negotiated session ID over streamable HTTP, or an ID
+ generated once per session on other transports. On 2026-07-28
+ connections, which `Client` negotiates by default, every request is its
+ own connection and gets a new identifier, so it can't be used to share
+ data between tool calls. Use [Session State](/servers/sessions) for
+ that.
Returns:
- The session ID for StreamableHTTP transports, or a generated ID
- for other transports.
+ The negotiated session ID when there is one, otherwise a generated
+ ID for the current connection.
Raises:
RuntimeError if no session is available.
-
- Example:
- ```python
- @server.tool
- def store_data(data: dict, ctx: Context) -> str:
- session_id = ctx.session_id
- redis_client.set(f"session:{session_id}:data", json.dumps(data))
- return f"Data stored for session {session_id}"
- ```
"""
from uuid import uuid4
@@ -759,14 +752,14 @@ class Context:
"This typically means you're outside a request context."
)
- # In SDK v2 the ServerSession is constructed fresh per request, so the
- # stable per-client identity lives on the underlying Connection, which
- # persists for the whole client session. Cache the state prefix on the
- # connection (its `session_id` for HTTP, its `state` dict otherwise) so
- # session-scoped state survives across tool calls.
+ # In SDK v2 the ServerSession is constructed fresh per request, so cache
+ # the state prefix on the underlying Connection. On handshake-era
+ # connections it spans the whole client session; on 2026-07-28
+ # connections the SDK builds one per request, so the prefix is
+ # per-request there too.
connection = getattr(session, "_connection", None)
- # Check for a cached prefix on the stable connection (or the session, as
+ # Check for a cached prefix on the connection (or the session, as
# a fallback for on_initialize where only a raw session is available).
if connection is not None:
cached = connection.state.get("_fastmcp_state_prefix")
@@ -790,7 +783,7 @@ class Context:
if session_id is None:
session_id = str(uuid4())
- # Cache on the stable connection (falling back to the session).
+ # Cache on the connection (falling back to the session).
if connection is not None:
connection.state["_fastmcp_state_prefix"] = session_id
else:
@@ -1144,8 +1137,10 @@ class Context:
) -> None:
"""Set a value in the state store.
- By default, values are stored in the session-scoped state store and
- persist across requests within the same MCP session. Values must be
+ By default, values are stored in the state store under `session_id`.
+ They persist across requests on handshake-era (legacy) connections, but
+ not on 2026-07-28 connections, where `session_id` is per-request; use
+ [Session State](/servers/sessions) for those. Values must be
JSON-serializable (dicts, lists, strings, numbers, etc.).
For non-serializable values (e.g., HTTP clients, database connections),