fix: return a self-describing 404 for an unknown SSE session

handle_post_message's session-lookup failure returned a bare "Could
not find session" 404, indistinguishable from any other cause and
naming neither the reason nor the remedy. This is the more common
sibling of the case fixed in 8058392 (self-describing error for a
request before initialization): that fix answers through the
ServerSession's responder once a session object exists, but a
restarted process has no session object at all for an unknown
session_id -- the rejection happens in handle_post_message itself,
one layer below where a JSON-RPC error could be shaped.

Every redeploy invalidates every previously-connected client's
session_id at once, so this 404 is what most stranded clients
actually hit, and it reads as a service outage rather than "restart
your MCP client."

Both 404 branches (unknown session_id, and the credential-mismatch
branch that deliberately mimics "session doesn't exist" so it can't
be used to probe for valid session IDs under another user) now share
one message via a single Response built once, so they can't drift
apart and leak which case occurred.

Updated test_sse_security_post_valid_content_type, which asserted the
old exact bare string -- it's testing content-type handling reaches
the 404 branch at all, not the message's wording, so relaxed to a
substring check.

Author: oliver

src/mcp/server/sse.py

@@ -237,20 +237,31 @@ async def handle_post_message(self, scope: Scope, receive: Receive, send: Send)
             response = Response("Invalid session ID", status_code=400)
             return await response(scope, receive, send)
 
+        # Both branches below 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 (see
+        # below) -- so the two messages can never diverge without leaking
+        # which case occurred.
+        unknown_session_response = Response(
+            f"Could not find session {session_id.hex}: the server may have restarted since this "
+            "session was created, or the session_id was never valid. Reconnect (open a new SSE "
+            "stream) and send a fresh 'initialize' request.",
+            status_code=404,
+        )
+
         writer = self._read_stream_writers.get(session_id)
         if not writer:
             logger.warning(f"Could not find session for ID: {session_id}")
-            response = Response("Could not find session", status_code=404)
-            return await response(scope, receive, send)
+            return await unknown_session_response(scope, receive, send)
 
         user = scope.get("user")
         requestor = authorization_context(user) if isinstance(user, AuthenticatedUser) else None
         if requestor != self._session_owners.get(session_id):
             # A session can only be used with the credential that created it.
             # Respond exactly as if the session did not exist.
             logger.warning("Rejecting message for session %s: credential does not match", session_id)
-            response = Response("Could not find session", status_code=404)
-            return await response(scope, receive, send)
+            return await unknown_session_response(scope, receive, send)
 
         body = await request.body()
         logger.debug(f"Received JSON: {body}")

tests/server/test_sse_security.py

@@ -310,7 +310,7 @@ async def test_sse_security_post_valid_content_type(server_port: int):
                 # Will get 404 because session doesn't exist, but that's OK
                 # We're testing that it passes the content-type check
                 assert response.status_code == 404
-                assert response.text == "Could not find session"
+                assert "Could not find session" in response.text
 
     finally:
         process.terminate()

tests/shared/test_sse.py

@@ -5,6 +5,7 @@
 from collections.abc import AsyncGenerator, Generator
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock, Mock, patch
+from uuid import uuid4
 
 import anyio
 import httpx
@@ -176,6 +177,24 @@ async def connection_test() -> None:
             await connection_test()
 
 
+@pytest.mark.anyio
+async def test_post_message_unknown_session_returns_self_describing_error(http_client: httpx.AsyncClient) -> None:
+    """A POST for a session_id the server has no record of (e.g. because the
+    process restarted since the client's SSE stream was opened) should
+    explain the cause and remedy, not a bare "Could not find session" -- the
+    same misleading-error problem #19 fixed for the uninitialized-session
+    case, one layer down where no ServerSession exists to answer through."""
+    unknown_session_id = uuid4().hex
+    response = await http_client.post(
+        f"/messages/?session_id={unknown_session_id}",
+        json={"jsonrpc": "2.0", "id": 1, "method": "ping"},
+    )
+    assert response.status_code == 404
+    body = response.text
+    assert "restart" in body.lower()
+    assert "reconnect" in body.lower() and "initialize" in body.lower()
+
+
 @pytest.mark.anyio
 async def test_sse_client_basic_connection(server: None, server_url: str) -> None:
     async with sse_client(server_url + "/sse") as streams: