fix: reserve initialize registration; validate initialized before state-set

add_request_handler("initialize", ...) now raises ValueError pointing at
Server.middleware (the handler could never fire; the runner answers
initialize itself, as ServerSession did). notifications/initialized now
validates params before flipping the init gate (malformed drops like any
other malformed notification, as the receive-loop union check did) and
then falls through to the registry so a registered handler observes the
initialized connection.

Author: maxisbey

src/mcp/server/lowlevel/server.py

@@ -259,8 +259,15 @@ def add_request_handler(
         `params_type` is the model incoming params are validated against
         before the handler is invoked. It should subclass `RequestParams` so
         `_meta` parses uniformly. Replaces any existing handler for the same
-        method (no collision guard against spec methods).
+        method, except `initialize`, which is reserved: the runner owns the
+        handshake, so registering it raises `ValueError`. Use
+        `Server.middleware` to observe or wrap initialization.
         """
+        if method == "initialize":
+            raise ValueError(
+                "'initialize' is handled by the server runner and cannot be overridden; "
+                "use Server.middleware to observe or wrap initialization"
+            )
         self._request_handlers[method] = HandlerEntry(params_type, handler)
 
     def add_notification_handler(
@@ -272,7 +279,9 @@ def add_notification_handler(
         """Register a notification handler for `method`.
 
         `params_type` should subclass `NotificationParams` so `_meta`
-        parses uniformly. Replaces any existing handler.
+        parses uniformly. Replaces any existing handler. A handler for
+        `notifications/initialized` runs after the runner has marked the
+        connection initialized.
         """
         self._notification_handlers[method] = HandlerEntry(params_type, handler)
 

src/mcp/server/runner.py

@@ -46,6 +46,7 @@
     Implementation,
     InitializeRequestParams,
     InitializeResult,
+    NotificationParams,
     RequestParams,
     RequestParamsMeta,
     client_request_adapter,
@@ -315,10 +316,23 @@ async def _on_notify(
 
         async def _inner() -> None:
             if method == "notifications/initialized":
+                # Validate against the spec params model *before* flipping the
+                # init state, so a malformed initialized notification drops
+                # like any other malformed notification and leaves the
+                # connection uninitialized (the existing server validated the
+                # full `ClientNotification` union before dispatch). On
+                # success, fall through to the registry so a handler
+                # registered for this method observes an initialized
+                # connection.
+                if params is not None:
+                    try:
+                        NotificationParams.model_validate(params, by_name=False)
+                    except ValidationError:
+                        logger.warning("dropped %r: malformed params", method)
+                        return
                 self._initialized = True
                 self.connection.initialized.set()
-                return
-            if not self._initialized:
+            elif not self._initialized:
                 logger.debug("dropped %s: received before initialization", method)
                 return
             entry = self.server.get_notification_handler(method)

tests/server/test_runner.py

@@ -260,6 +260,48 @@ async def test_runner_on_notify_initialized_sets_flag_and_connection_event(serve
     assert runner._initialized is True
 
 
+@pytest.mark.anyio
+async def test_runner_on_notify_malformed_initialized_does_not_initialize(
+    server: SrvT, caplog: pytest.LogCaptureFixture
+):
+    """A malformed `notifications/initialized` drops like any other malformed
+    notification and leaves the connection uninitialized."""
+    async with connected_runner(server, initialized=False) as (client, runner):
+        await client.notify("notifications/initialized", {"_meta": 42})
+        await anyio.wait_all_tasks_blocked()
+        assert runner._initialized is False
+        assert not runner.connection.initialized.is_set()
+    assert "dropped 'notifications/initialized': malformed params" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_runner_on_notify_initialized_routes_to_registered_handler_after_state_set(server: SrvT):
+    """A handler registered for `notifications/initialized` fires after the
+    runner flips the init state, so it observes an initialized connection."""
+    seen: list[bool] = []
+    delivered = anyio.Event()
+
+    async def on_initialized(ctx: Ctx, params: NotificationParams | None) -> None:
+        seen.append(runner._initialized and runner.connection.initialized.is_set())
+        delivered.set()
+
+    server.add_notification_handler("notifications/initialized", NotificationParams, on_initialized)
+    async with connected_runner(server, initialized=False) as (client, runner):
+        await client.notify("notifications/initialized", {"_meta": {"k": "v"}})
+        await delivered.wait()
+    assert seen == [True]
+
+
+def test_server_add_request_handler_rejects_initialize():
+    async def handler(ctx: Ctx, params: InitializeRequestParams) -> dict[str, Any]:
+        raise NotImplementedError
+
+    server: SrvT = Server(name="s")
+    with pytest.raises(ValueError, match="Server.middleware"):
+        server.add_request_handler("initialize", InitializeRequestParams, handler)
+    assert server.get_request_handler("initialize") is None
+
+
 @pytest.mark.anyio
 async def test_runner_on_notify_routes_to_registered_handler(server: SrvT):
     seen: list[tuple[Any, Any]] = []
@@ -792,14 +834,16 @@ async def test_runner_exit_stack_blocking_cleanup_abandoned_after_grace(
 
     async def _abandoned() -> None:
         # LIFO unwind: pushed first, so it runs after the blocker. By then the
-        # deadline has fired, so this checkpoint raises and the append never runs.
+        # deadline has fired, so this checkpoint raises and the line below is
+        # unreachable (if abandonment broke, the missing warning fails the
+        # caplog assert).
         await anyio.sleep(0)
-        ran.append("abandoned")
+        raise NotImplementedError
 
     async def _blocker() -> None:
         ran.append("blocker started")
         await release.wait()
-        ran.append("blocker finished")
+        raise NotImplementedError
 
     async with connected_runner(server) as (client, runner):
         runner.connection.exit_stack.push_async_callback(_abandoned)