π 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.mdxindex 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 Availabilitydiff --git a/fastmcp_slim/fastmcp/server/context.py b/fastmcp_slim/fastmcp/server/context.pyindex 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_idclient_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:@propertydef 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_idelse:@@ -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 beJSON-serializable (dicts, lists, strings, numbers, etc.).For non-serializable values (e.g., HTTP clients, database connections),