Share the unsupported-version rejection between request and notification arms

The notification arm hand-built the -32022 error (message text plus the
supported/requested payload) that the request ladder's last rung already
produces, so the two could drift. Lift that rung into
`unsupported_protocol_version_rejection()` in `mcp.shared.inbound`, use it
from both, and let `_write_rejection` take a null id so the notification
arm writes through the same path as every other rejection.

Also note in the low-level server and middleware docs that on the
2026-07-28 streamable-HTTP path a client notification POST is acknowledged
202 at the transport and not dispatched, so notification handlers and
middleware do not see it there.

Author: maxisbey

docs/advanced/low-level-server.md

@@ -162,7 +162,7 @@ The constructor covers the methods MCP defines. `add_request_handler` covers eve
 --8<-- "docs_src/lowlevel/tutorial006.py"
 ```
 
-* The first argument is the method string. Notifications have a twin, `add_notification_handler`.
+* The first argument is the method string. Notifications have a twin, `add_notification_handler`. Its handlers fire on stdio and on handshake-era HTTP connections; on the `2026-07-28` streamable-HTTP path a client's notification POST is acknowledged `202` and not dispatched, because that revision defines no client-to-server notifications over HTTP.
 * `params_type` is the model the incoming `params` are validated against **before** your handler runs, so custom methods *do* get the validation tools don't. Subclass `RequestParams` so the `_meta` field parses like every other method's.
 * The handler returns a `BaseModel`, a `dict`, or `None`. The SDK serialises it into the JSON-RPC result.
 

docs/advanced/middleware.md

@@ -48,8 +48,11 @@ That is the point. Middleware wraps **every** inbound message:
 
 * The connection setup: `server/discover`, or `initialize` and `notifications/initialized`
   on a legacy session.
-* Every request and every notification. For a notification, `ctx.request_id is None`,
-  `call_next(ctx)` returns `None`, and whatever you return is discarded.
+* Every request and every notification that reaches the server. For a notification,
+  `ctx.request_id is None`, `call_next(ctx)` returns `None`, and whatever you return is discarded.
+  (On the `2026-07-28` streamable-HTTP path a client's notification POST is acknowledged `202` at
+  the transport and never dispatched, so it does not reach middleware either; that revision
+  defines no client-to-server notifications over HTTP.)
 * Even a method the server has no handler for: `call_next` raises the
   `MCPError(-32601, "Method not found")` *through* your middleware on its way to the client.
 
@@ -105,8 +108,8 @@ don't think about it. It is a no-op until you install an exporter, and it has it
 
 * A middleware is `async (ctx, call_next) -> result`, passed as `MCPServer(middleware=[...])` (or
   appended to `mcp.middleware`), and appended to `server.middleware` on the low-level `Server`.
-* It wraps **every** inbound message (`server/discover`, `initialize`, requests, notifications,
-  unknown methods) and runs outermost-first.
+* It wraps **every** inbound message that reaches the server (`server/discover`, `initialize`,
+  requests, notifications, unknown methods) and runs outermost-first.
 * `ctx.request_id is None` is how you tell a notification from a request.
 * Raise instead of calling `call_next` to refuse one message; the connection survives.
 * The SDK's own OpenTelemetry tracing is a middleware too, already on the list. See

src/mcp/server/_streamable_http_modern.py

@@ -36,18 +36,15 @@
     INVALID_REQUEST,
     PARSE_ERROR,
     PROTOCOL_VERSION_META_KEY,
-    UNSUPPORTED_PROTOCOL_VERSION,
     ErrorData,
     JSONRPCError,
     JSONRPCNotification,
     JSONRPCRequest,
     JSONRPCResponse,
     ProgressToken,
     RequestId,
-    UnsupportedProtocolVersionErrorData,
 )
 from mcp_types import methods as _methods
-from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
@@ -67,6 +64,7 @@
     InboundModernRoute,
     classify_inbound_request,
     find_duplicated_routing_header,
+    unsupported_protocol_version_rejection,
     validate_mcp_param_headers,
 )
 from mcp.shared.jsonrpc_dispatcher import progress_token_from_params
@@ -169,7 +167,7 @@ def _sse_event(msg: JSONRPCResponse | JSONRPCError | JSONRPCNotification) -> byt
 
 async def _write_rejection(
     rejection: InboundLadderRejection,
-    request_id: RequestId,
+    request_id: RequestId | None,
     scope: Scope,
     receive: Receive,
     send: Send,
@@ -250,19 +248,8 @@ async def _acknowledge_notification(
         await _write(_INVALID_BODY, scope, receive, send)
         return
     requested = request.headers.get(MCP_PROTOCOL_VERSION_HEADER, "")
-    if requested not in MODERN_PROTOCOL_VERSIONS:
-        rej = JSONRPCError(
-            jsonrpc="2.0",
-            id=None,
-            error=ErrorData(
-                code=UNSUPPORTED_PROTOCOL_VERSION,
-                message="Unsupported protocol version",
-                data=UnsupportedProtocolVersionErrorData(
-                    supported=list(MODERN_PROTOCOL_VERSIONS), requested=requested
-                ).model_dump(mode="json"),
-            ),
-        )
-        await _write(rej, scope, receive, send)
+    if (unsupported := unsupported_protocol_version_rejection(requested)) is not None:
+        await _write_rejection(unsupported, None, scope, receive, send)
         return
     logger.debug("acknowledged and dropped client notification %s at %s", notification.method, requested)
     await Response(status_code=202)(scope, receive, send)

src/mcp/shared/inbound.py

@@ -52,6 +52,7 @@
     "find_duplicated_routing_header",
     "find_invalid_x_mcp_header",
     "mcp_param_headers",
+    "unsupported_protocol_version_rejection",
     "validate_mcp_param_headers",
     "x_mcp_header_map",
 ]
@@ -367,6 +368,25 @@ def find_duplicated_routing_header(headers: Iterable[tuple[str, str]]) -> str |
     return None
 
 
+def unsupported_protocol_version_rejection(
+    requested: str, supported_modern_versions: Sequence[str] = MODERN_PROTOCOL_VERSIONS
+) -> InboundLadderRejection | None:
+    """The `UNSUPPORTED_PROTOCOL_VERSION` rejection for `requested`, or `None` if it is served.
+
+    The request ladder's last rung, shared with the transport's notification arm
+    so both message kinds name the same `supported` list in the same words.
+    """
+    if requested in supported_modern_versions:
+        return None
+    return InboundLadderRejection(
+        code=UNSUPPORTED_PROTOCOL_VERSION,
+        message="Unsupported protocol version",
+        data=UnsupportedProtocolVersionErrorData(
+            supported=list(supported_modern_versions), requested=requested
+        ).model_dump(mode="json"),
+    )
+
+
 def classify_inbound_request(
     body: Mapping[str, Any],
     *,
@@ -464,14 +484,8 @@ def classify_inbound_request(
             message="the protocol-version envelope value must be a string",
         )
 
-    if protocol_version not in supported_modern_versions:
-        return InboundLadderRejection(
-            code=UNSUPPORTED_PROTOCOL_VERSION,
-            message="Unsupported protocol version",
-            data=UnsupportedProtocolVersionErrorData(
-                supported=list(supported_modern_versions), requested=protocol_version
-            ).model_dump(mode="json"),
-        )
+    if (unsupported := unsupported_protocol_version_rejection(protocol_version, supported_modern_versions)) is not None:
+        return unsupported
 
     return InboundModernRoute(
         protocol_version=protocol_version,

tests/shared/test_inbound.py

@@ -43,6 +43,7 @@
     find_duplicated_routing_header,
     find_invalid_x_mcp_header,
     mcp_param_headers,
+    unsupported_protocol_version_rejection,
     validate_mcp_param_headers,
     x_mcp_header_map,
 )
@@ -225,6 +226,22 @@ def test_version_rung_data_reflects_supplied_supported_list() -> None:
     assert rejection.data == {"supported": list(custom), "requested": LATEST_MODERN_VERSION}
 
 
+def test_unsupported_protocol_version_rejection_is_the_version_rung_standalone() -> None:
+    """SDK-defined: the standalone helper (used by the HTTP notification arm) yields `None` for a
+    served version and otherwise the very rejection the request ladder's version rung produces."""
+    assert unsupported_protocol_version_rejection(LATEST_MODERN_VERSION) is None
+    assert unsupported_protocol_version_rejection("2099-01-01") == classify_inbound_request(
+        envelope(version="2099-01-01")
+    )
+    assert unsupported_protocol_version_rejection(LATEST_MODERN_VERSION, (LATEST_HANDSHAKE_VERSION,)) == (
+        InboundLadderRejection(
+            code=UNSUPPORTED_PROTOCOL_VERSION,
+            message="Unsupported protocol version",
+            data={"supported": [LATEST_HANDSHAKE_VERSION], "requested": LATEST_MODERN_VERSION},
+        )
+    )
+
+
 # --- rung 3: header ↔ envelope agreement ---------------------------------------