fix: return a self-describing 404 for an unknown streamable-http session (#1)

* fix: return a self-describing 404 for an unknown streamable-http session

StreamableHTTPSessionManager answered a request for a missing or
credential-mismatched session with a bare "Session not found" -- the
same misleading-error problem #19/#26 already fixed for
SseServerTransport's equivalent case (a redeploy or expiry invalidating
every connected client's session_id at once), just not ported to this
transport.

Both call sites now share one message via _session_not_found_response(),
built once so the "unknown session" and "credential mismatch" cases
(which must answer identically -- see the comment) can't drift apart.

Verified: full suite 1140 passed / 0 regressions (95 skipped, 1 xfailed,
2 pre-existing collection errors for the unrelated optional `websockets`
extra, not installed in this environment) plus ruff and pyright clean.

* fix: address review -- comment direction, unvalidated input note, expire coverage

- _session_not_found_response's comment said "callers below" / "check
  above" -- true when this sat inline in sse.py, backwards once hoisted
  to a module-level function above both call sites. Converted to a
  docstring, direction fixed.
- session_id here is the raw, client-supplied mcp-session-id header,
  never validated against SESSION_ID_PATTERN (only IDs the server mints
  are) -- unlike sse.py's session_id.hex, which is already
  UUID-validated. Safe (JSON-escaped, application/json, truncated to
  64 chars matching the file's existing convention) but the docstring
  now says so, rather than leaving it to be re-derived later.
- Test now asserts "expire" is covered, not just "restart" -- the one
  genuinely new clause this message adds over the sse-side wording
  (this transport has a session_idle_timeout; sse doesn't), which was
  the one claim the prior substring checks didn't actually verify.

---------

Co-authored-by: oliver <oliver.sampson@gitterdan.ai>

Author: MrSampson

src/mcp/server/streamable_http_manager.py

@@ -32,6 +32,41 @@
 """Default maximum Streamable HTTP request body size in bytes (4 MiB)."""
 
 
+def _session_not_found_response(session_id: str) -> Response:
+    """Both call sites in ``_handle_stateful_request`` -- the unknown/expired
+    session branch and the credential-mismatch branch -- use this identical,
+    self-describing message: a session can be missing either because it was
+    never valid or because the credential doesn't match its owner, and the
+    second case must respond exactly as if the session did not exist -- so
+    the two responses can never diverge without leaking which case occurred.
+    Same shape as SseServerTransport's unknown_session_response.
+
+    ``session_id`` here is the raw, client-supplied ``mcp-session-id``
+    header value, not one already validated against SESSION_ID_PATTERN (that
+    check only applies to IDs the server itself mints) -- truncated to 64
+    chars to match the file's existing logging convention, and safe to
+    reflect back since it's JSON-escaped by model_dump_json and served as
+    application/json, never sniffed as HTML.
+    """
+    body = JSONRPCError(
+        jsonrpc="2.0",
+        id="server-error",
+        error=ErrorData(
+            code=INVALID_REQUEST,
+            message=(
+                f"Could not find session {session_id[:64]}: the server may have restarted since this "
+                "session was created, the session may have expired, or the session_id was never valid. "
+                "Reconnect and send a fresh 'initialize' request to start a new session."
+            ),
+        ),
+    )
+    return Response(
+        body.model_dump_json(by_alias=True, exclude_none=True),
+        status_code=404,
+        media_type="application/json",
+    )
+
+
 class StreamableHTTPSessionManager:
     """
     Manages StreamableHTTP sessions with optional resumability via event store.
@@ -264,14 +299,7 @@ async def _handle_stateful_request(
                     "Rejecting request for session %s: credential does not match the one that created the session",
                     request_mcp_session_id[:64],
                 )
-                body = JSONRPCError(
-                    jsonrpc="2.0", id="server-error", error=ErrorData(code=INVALID_REQUEST, message="Session not found")
-                )
-                response = Response(
-                    body.model_dump_json(by_alias=True, exclude_none=True),
-                    status_code=404,
-                    media_type="application/json",
-                )
+                response = _session_not_found_response(request_mcp_session_id)
                 await response(scope, receive, send)
                 return
             logger.debug("Session already exists, handling request directly")
@@ -354,12 +382,7 @@ async def run_server(*, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORE
                 await http_transport.handle_request(scope, receive, send)
         else:
             # Unknown or expired session ID - return 404 per MCP spec
-            body = JSONRPCError(
-                jsonrpc="2.0", id="server-error", error=ErrorData(code=INVALID_REQUEST, message="Session not found")
-            )
-            response = Response(
-                body.model_dump_json(by_alias=True, exclude_none=True), status_code=404, media_type="application/json"
-            )
+            response = _session_not_found_response(request_mcp_session_id)
             await response(scope, receive, send)
 
 

tests/server/test_streamable_http_manager.py

@@ -395,7 +395,9 @@ async def mock_receive():
 
 @pytest.mark.anyio
 async def test_unknown_session_id_returns_404():
-    """Test that requests with unknown session IDs return HTTP 404 per MCP spec."""
+    """Requests with unknown session IDs return HTTP 404 per MCP spec, with a
+    self-describing message -- not a bare "Session not found" -- naming the
+    cause and remedy, mirroring what #19/#26 already did for SseServerTransport."""
     app = Server("test-unknown-session")
     manager = StreamableHTTPSessionManager(app=app)
 
@@ -439,7 +441,14 @@ async def mock_receive():
         assert error_data["jsonrpc"] == "2.0"
         assert error_data["id"] == "server-error"
         assert error_data["error"]["code"] == INVALID_REQUEST
-        assert error_data["error"]["message"] == "Session not found"
+        message = error_data["error"]["message"]
+        assert "restart" in message.lower()
+        assert "reconnect" in message.lower() and "initialize" in message.lower()
+        # This transport (unlike sse) has a session_idle_timeout, so an
+        # expired session is a real, distinct cause the sse-side wording
+        # doesn't need to name -- assert it's actually covered, not just
+        # copied from the sse message.
+        assert "expire" in message.lower()
 
 
 @pytest.mark.anyio