Expose server-assigned session_id on ClientSession

Read session_id from InitializeResult._meta after initialize and expose
as session.session_id property. Enables client-side construction of
session-scoped event topics for the {session_id} authorization convention.

Author: elijahr

docs/events.md

@@ -27,6 +27,10 @@ Topics are `/`-separated strings with a maximum depth of 8 segments. Clients sub
 - `+` matches exactly one segment
 - `#` matches zero or more trailing segments (must be the last segment)
 
+### Session-Scoped Topics
+
+Servers may use a `{session_id}` placeholder in topic patterns to scope topics to individual sessions (e.g., `app/sessions/{session_id}/messages`). When a topic contains `{session_id}`, the server enforces that subscribers can only substitute their own session UUID -- wildcards and other session IDs are rejected. This convention is not part of the core MCP spec but is a common server-side pattern (used by FastMCP, among others).
+
 ## Server-Side
 
 ### Declaring Event Topics
@@ -195,6 +199,17 @@ server.request_handlers[EventListRequest] = handle_list
 
 ## Client-Side
 
+### Session ID
+
+After initialization, `session.session_id` returns the server-assigned session ID (`str | None`), sourced from `InitializeResult._meta["session_id"]`. This is useful for constructing session-scoped topic patterns:
+
+```python
+topic = f"app/sessions/{session.session_id}/messages"
+await session.subscribe_events([topic])
+```
+
+Returns `None` if the server does not provide a session ID in `_meta`.
+
 ### Subscribing to Events
 
 Use `subscribe_events()` to register interest in one or more topic patterns:

src/mcp/client/session.py

@@ -146,6 +146,7 @@ def __init__(
         self._message_handler = message_handler or _default_message_handler
         self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
         self._server_capabilities: types.ServerCapabilities | None = None
+        self._session_id: str | None = None
         self._experimental_features: ExperimentalClientFeatures | None = None
         self._event_handler: EventHandlerFnT | None = None
         self._event_topic_filter: str | None = None
@@ -205,6 +206,16 @@ async def initialize(self) -> types.InitializeResult:
 
         self._server_capabilities = result.capabilities
 
+        # FastMCP servers inject a server-assigned session_id into
+        # InitializeResult._meta so clients can synchronously read it after
+        # connect (e.g. to subscribe to session-scoped event topics like
+        # ``sessions/{session_id}/messages``). Non-FastMCP servers typically
+        # omit this, in which case ``self._session_id`` stays ``None``.
+        if result.meta is not None:
+            meta_session_id = result.meta.get("session_id")
+            if isinstance(meta_session_id, str):
+                self._session_id = meta_session_id
+
         await self.send_notification(types.ClientNotification(types.InitializedNotification()))
 
         return result
@@ -216,6 +227,17 @@ def get_server_capabilities(self) -> types.ServerCapabilities | None:
         """
         return self._server_capabilities
 
+    @property
+    def session_id(self) -> str | None:
+        """The server-assigned session ID from InitializeResult._meta, if present.
+
+        This is set by FastMCP servers to enable client-side subscription to
+        session-scoped event topics like ``sessions/{session_id}/messages``.
+        Returns None if the server did not provide a session_id (e.g.,
+        non-FastMCP server).
+        """
+        return self._session_id
+
     @property
     def experimental(self) -> ExperimentalClientFeatures:
         """Experimental APIs for tasks and other features.