docs: deadlock warning for server-to-client requests during initialize

initialize is handled inline (the dispatcher parks the read loop until
the handler - middleware included - returns), so awaiting a peer
response on that path can never dequeue the response. Warn on
ServerMiddleware; TODO at the initialize branch: rework initialization
into a pure incoming middleware and add an outgoing-middleware seam
whose default chain blocks server-to-client requests when the
negotiated protocol version requires initialization and the connection
is neither initialized nor stateless.

Author: maxisbey

src/mcp/server/context.py

@@ -139,6 +139,12 @@ class ServerMiddleware(Protocol[_MwLifespanT]):
     yet). For typed inspection, validate against the model the middleware
     expects.
 
+    Warning: `initialize` is handled inline - the dispatcher does not read
+    further inbound messages until the middleware chain returns. Awaiting a
+    server-to-client request (`ctx.session.send_request`, `send_ping`, ...)
+    while handling `initialize` therefore deadlocks the connection: the
+    response can never be dequeued. Send-and-forget notifications are safe.
+
     `Server[L].middleware` holds `ServerMiddleware[L]`, so an app-specific
     middleware sees `ctx.lifespan_context: L`. While the context is the
     mutable `ServerRequestContext` dataclass it is invariant in `L`, so a

src/mcp/server/runner.py

@@ -259,6 +259,15 @@ async def _inner() -> HandlerResult:
                 if params is not None:
                     payload["params"] = dict(params)
                 client_request_adapter.validate_python(payload, by_name=False)
+            # TODO(maxisbey): rework initialization into a pure incoming
+            # middleware, and add an outgoing-middleware seam whose default
+            # chain blocks server-to-client requests when the negotiated
+            # protocol version requires initialization and the connection is
+            # neither initialized nor stateless. Until then, note that
+            # `initialize` is handled inline (the dispatcher's read loop is
+            # parked until this whole call - middleware included - returns),
+            # so awaiting a peer response anywhere on this path deadlocks the
+            # connection.
             if method == "initialize":
                 return self._handle_initialize(params)
             if not self._initialized and method not in _INIT_EXEMPT: