Warn per event on unbound client notifications; keep server drops at debug

Drop the once-per-method dedup and its per-runner state: the client now
warns on every unbound notification (registering a binding, even a no-op
one, is the silence), and server-side inbound drops return to debug since
the peer is an arbitrary client and warning on its input floods the log.

Revert the ClientSession.send_notification widening: the 2026-07-28
transports do not agree on client-to-server custom notifications yet, so
the closed union stays the accurate type. Carve notifications/cancelled and
listen-owned acks out of the message_handler catch-all claim, add the
imports the notification example was missing, and note that a
json_response answer has no stream to carry request-scoped notifications.

Author: maxisbey

docs/advanced/low-level-server.md

@@ -166,11 +166,16 @@ The constructor covers the methods MCP defines. `add_request_handler` covers eve
 * `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.
 
-Notifications have a twin in each direction. Inbound, `add_notification_handler(method, params_type, handler)` registers `async (ctx, params) -> None`. Spec-defined notification methods are validated against the negotiated version's tables before dispatch, and one that does not exist at that version is dropped with a warning. Custom methods skip the version gate; your `params_type` is their validation, and a custom notification nobody registered a handler for is dropped with a warning.
+Notifications have a twin in each direction. Inbound, `add_notification_handler(method, params_type, handler)` registers `async (ctx, params) -> None`. Spec-defined notification methods are validated against the negotiated version's tables before dispatch; custom methods skip the version gate, so your `params_type` is their validation.
 
 Outbound, `ctx.session.send_notification(...)` accepts any `mcp_types.Notification` subclass, not just the spec-defined union, so the notifying half of a vendor protocol is one model away:
 
 ```python
+from typing import Literal
+
+from mcp_types import Notification, NotificationParams
+
+
 class ReindexProgressParams(NotificationParams):
     percent: float
 
@@ -187,7 +192,7 @@ async def reindex(ctx: ServerRequestContext, params: ReindexParams) -> None:
     )
 ```
 
-Pass `related_request_id` so the notification rides the originating request's stream; the 2026-07-28 wire gives standalone notifications no channel outside `subscriptions/listen`. A python-sdk client observes vendor methods with a `NotificationBinding` (**[Extensions](extensions.md)**) and warns about ones it has no binding for.
+Pass `related_request_id` so the notification rides the originating request's stream; the 2026-07-28 wire gives standalone notifications no channel outside `subscriptions/listen`, and a streamable HTTP response answered with `json_response=True` has no stream, so notifications sent during it are dropped. A python-sdk client observes vendor methods with a `NotificationBinding` (**[Extensions](extensions.md)**) and warns on each one it has no binding for.
 
 One honest caveat: the high-level `Client` only has verbs for the methods MCP defines, so there is no `client.reindex()`. A vendor method is for a peer that already knows it exists: a client you also ship, or another service of yours speaking JSON-RPC.
 

docs/client/callbacks.md

@@ -135,7 +135,7 @@ Two more. Neither declares anything.
 
 `logging_callback` receives every `notifications/message` a server sends, as `LoggingMessageNotificationParams` (`level`, `logger`, `data`). Protocol logging is itself deprecated by the 2026-07-28 spec (**[Logging](../handlers/logging.md)** has what to do instead), so this callback exists for the servers that still emit it.
 
-`message_handler` is the catch-all for spec traffic: every notification the negotiated protocol version defines reaches it (as well as its specific callback), and on a stream-backed transport so does every transport-level `Exception`. Vendor and extension methods are outside that set; they are delivered only to a matching `NotificationBinding` (**[Extensions](../advanced/extensions.md)**), and without one they are dropped with a warning. The one pattern worth knowing is `if isinstance(message, Exception): raise message`, so a broken connection fails loudly instead of vanishing.
+`message_handler` is the catch-all for spec traffic: every notification the negotiated protocol version defines reaches it (as well as its specific callback), except `notifications/cancelled`, which the session applies internally, and acknowledgements consumed by an open `listen()` stream. On a stream-backed transport it also receives every transport-level `Exception`. Vendor and extension methods are outside that set; they are delivered only to a matching `NotificationBinding` (**[Extensions](../advanced/extensions.md)**), and without one they are dropped with a warning. The one pattern worth knowing is `if isinstance(message, Exception): raise message`, so a broken connection fails loudly instead of vanishing.
 
 ## Recap
 

docs/migration.md

@@ -1681,7 +1681,7 @@ session = ClientSession(
 )
 ```
 
-On the high-level `Client`, bindings are declared by a `ClientExtension`'s `notifications()`; see [Extensions](advanced/extensions.md). The sending direction also loses its `cast`: `send_notification` on both `ClientSession` and `ServerSession` accepts any `mcp_types.Notification` subclass, where v1 typed it to the closed unions.
+On the high-level `Client`, bindings are declared by a `ClientExtension`'s `notifications()`; see [Extensions](advanced/extensions.md). The server's sending direction also loses its `cast`: `ServerSession.send_notification` accepts any `mcp_types.Notification` subclass, where v1 typed it to the closed union.
 
 ### Experimental Tasks support removed
 

docs/whats-new.md

@@ -201,7 +201,7 @@ At 2026-07-28 the standalone HTTP GET stream and `resources/subscribe` are repla
 * **Requests are routable without parsing bodies.** Modern HTTP requests carry `Mcp-Method` (and, for the three tool-ish calls, `Mcp-Name`); a tool input-schema property annotated with `x-mcp-header` is mirrored into an `Mcp-Param-*` header and cross-checked by the server ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243)). Gateways and rate limiters can route on headers alone; the **[Migration Guide](migration.md#servers-validate-mcp-param-headers-against-the-request-body-sep-2243)** has the rules.
 * **Results carry cache hints.** List and read results declare `ttlMs` and `cacheScope` ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)); you set them per method with `cache_hints=`, and `Client` honors them with a built-in response cache. A server that sends no hints (every pre-2026 server) sees identical, uncached traffic. **[Caching hints](client/caching.md)**.
 * **Extensions are first class.** Servers and clients declare optional capability bundles under reverse-DNS identifiers ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)); the built-in `Apps` extension (MCP Apps) is the reference. **[Extensions](advanced/extensions.md)** and **[MCP Apps](advanced/apps.md)**.
-* **Vendor notifications are typed end to end.** `send_notification` on both sessions accepts any `mcp_types.Notification` subclass, and a client observes methods outside the negotiated version's tables with a `NotificationBinding` (on `ClientSession` directly, or declared by a `ClientExtension`); a notification nothing observes is dropped with a warning, not silently. **[Extensions](advanced/extensions.md)**.
+* **Vendor notifications are typed end to end.** `ServerSession.send_notification` accepts any `mcp_types.Notification` subclass, and a client observes methods outside the negotiated version's tables with a `NotificationBinding` (on `ClientSession` directly, or declared by a `ClientExtension`); a notification nothing observes is dropped with a warning, not silently. **[Extensions](advanced/extensions.md)**.
 * **Error codes got standardized.** A missing resource is `-32602` with the URI in `error.data`, and the new spec-reserved codes appear as `-32020` (header mismatch), `-32021` (missing required capability), and `-32022` (unsupported protocol version). **[Troubleshooting](troubleshooting.md)** is keyed by the exact messages.
 * **Authorization got harder to hold wrong.** The client validates the `iss` returned with the authorization code ([RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207); your `callback_handler` now returns an `AuthorizationCodeResult`), sends `application_type` when it registers, and never replays credentials against a different authorization server. New in the enterprise corner: the [SEP-990](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990) identity-assertion flow. The **[Migration Guide](migration.md)** lists every OAuth change; **[OAuth for clients](client/oauth-clients.md)** and **[Identity assertion](client/identity-assertion.md)** are the pages.
 * **Every server is traceable.** OpenTelemetry ships on by default as middleware: every request gets a server span, at no cost until the process configures an exporter. When both ends run the SDK, the client also propagates W3C trace context in `_meta`, so the traces join up. **[OpenTelemetry](run/opentelemetry.md)**.

src/mcp/client/session.py

@@ -363,7 +363,6 @@ def __init__(
         self._extensions = dict(extensions) if extensions is not None else None
         self._result_claims = _index_claims(result_claims, extensions)
         self._notification_bindings = _index_bindings(notification_bindings)
-        self._warned_notification_drops: set[str] = set()
         self._active_claims: dict[str, ResultClaim[Any]] = {}
         self._call_tool_adapter = _CallToolResultAdapter
         self._binding_queues: dict[
@@ -528,14 +527,9 @@ async def send_request(
             return result_type.validate_python(raw, by_name=False)
         return result_type.model_validate(raw, by_name=False)
 
-    async def send_notification(self, notification: types.ClientNotification | types.Notification[Any, Any]) -> None:
+    async def send_notification(self, notification: types.ClientNotification) -> None:
         """Send a one-way notification. Usable before entering the context manager.
 
-        Spec notifications are the `types.ClientNotification` union members; any
-        other `types.Notification` subclass is sent as-is, so extensions can emit
-        their own methods (a python-sdk server routes those to handlers registered
-        with `Server.add_notification_handler`).
-
         Fire-and-forget: after the connection has closed, the notification is
         dropped with a debug log instead of raising.
         """
@@ -1340,11 +1334,9 @@ async def _on_notify(
             # Only methods unknown to the negotiated version's core tables reach the bindings.
             binding = self._notification_bindings.get(method)
             if binding is None:
-                # The first drop of a method warns; repeats log at debug so a stream cannot flood the log.
-                level = logging.WARNING if method not in self._warned_notification_drops else logging.DEBUG
-                self._warned_notification_drops.add(method)
-                logger.log(
-                    level, "dropped %r: not defined at %s and no notification binding is registered", method, version
+                # A binding is the opt-in for methods core does not know; a no-op one silences the warning.
+                logger.warning(
+                    "dropped %r: not defined at %s and no notification binding is registered", method, version
                 )
                 return
             try:

src/mcp/server/runner.py

@@ -17,7 +17,7 @@
 import logging
 from collections.abc import AsyncIterator, Awaitable, Mapping
 from contextlib import asynccontextmanager
-from dataclasses import KW_ONLY, dataclass, field, replace
+from dataclasses import KW_ONLY, dataclass, replace
 from functools import cached_property, partial
 from typing import TYPE_CHECKING, Any, Generic, cast
 
@@ -164,14 +164,6 @@ class ServerRunner(Generic[LifespanT]):
     init_options: InitializationOptions | None = None
     """`InitializeResult` payload. Defaults to `server.create_initialization_options()`."""
 
-    _warned_notification_drops: set[str] = field(default_factory=lambda: set(), init=False, repr=False)
-
-    def _log_dropped_notification(self, method: str, message: str, *args: object) -> None:
-        """The first drop of a method warns; repeats log at debug so a stream cannot flood the log."""
-        level = logging.WARNING if method not in self._warned_notification_drops else logging.DEBUG
-        self._warned_notification_drops.add(method)
-        logger.log(level, message, method, *args)
-
     @cached_property
     def on_request(self) -> OnRequest:
         return self._on_request
@@ -259,12 +251,11 @@ async def _on_notify(
 
         async def _inner(ctx: ServerRequestContext[LifespanT, Any]) -> None:
             method, params = ctx.method, ctx.params
-            is_spec = method in _methods.SPEC_CLIENT_NOTIFICATION_METHODS
-            if is_spec:
+            if method in _methods.SPEC_CLIENT_NOTIFICATION_METHODS:
                 try:
                     _methods.validate_client_notification(method, version, params)
                 except KeyError:
-                    self._log_dropped_notification(method, "dropped %r: not defined at %s", version)
+                    logger.debug("dropped %r: not defined at %s", method, version)
                     return
                 except ValidationError:
                     logger.warning("dropped %r: malformed params", method)
@@ -279,13 +270,7 @@ async def _inner(ctx: ServerRequestContext[LifespanT, Any]) -> None:
                 return
             entry = self.server.get_notification_handler(method)
             if entry is None:
-                if is_spec:
-                    # Not serving a spec notification is ordinary (most servers
-                    # ignore roots/list_changed); dropping a custom method the
-                    # peer went out of its way to send deserves a warning.
-                    logger.debug("no handler for notification %s", method)
-                else:
-                    self._log_dropped_notification(method, "dropped %r: no notification handler is registered")
+                logger.debug("no handler for notification %s", method)
                 return
             # Same absent-params contract as requests.
             try:

tests/client/test_session.py

@@ -2,7 +2,7 @@
 
 from collections.abc import AsyncIterator, Mapping
 from contextlib import AsyncExitStack, asynccontextmanager
-from typing import Any, Literal, cast
+from typing import Any, cast
 
 import anyio
 import anyio.abc
@@ -1475,29 +1475,6 @@ async def test_send_notification_after_close_is_dropped_silently():
             s.close()
 
 
-class _ReceiptEventParams(types.NotificationParams):
-    seq: int
-
-
-class _ReceiptEvent(types.Notification[_ReceiptEventParams, Literal["notifications/com.example/receipt"]]):
-    method: Literal["notifications/com.example/receipt"] = "notifications/com.example/receipt"
-    params: _ReceiptEventParams
-
-
-@pytest.mark.anyio
-async def test_send_notification_accepts_a_custom_notification_model():
-    """A `types.Notification` subclass outside the spec union serializes onto the wire
-    as-is, so extensions can emit their own methods without casts."""
-    async with raw_client_session() as (session, _, recv_from_client):
-        await session.send_notification(_ReceiptEvent(params=_ReceiptEventParams(seq=7)))
-        with anyio.fail_after(5):
-            sent = await recv_from_client.receive()
-    notification = sent.message
-    assert isinstance(notification, JSONRPCNotification)
-    assert notification.method == "notifications/com.example/receipt"
-    assert notification.params == {"seq": 7}
-
-
 # --- discover() ladder ---
 
 

tests/client/test_session_notification_bindings.py

@@ -183,12 +183,12 @@ async def on_event(params: _EventParams) -> None:
 
 @pytest.mark.anyio
 async def test_unbound_vendor_notification_is_dropped_with_a_warning(caplog: pytest.LogCaptureFixture) -> None:
-    """SDK-defined: a vendor method with no binding is dropped with a warning naming the
-    remedy; repeats of the same method drop to debug so a stream cannot flood the log."""
+    """SDK-defined: each vendor notification with no binding is dropped with a warning
+    naming the remedy; a binding for the method is what silences it."""
     client_side, server_side = create_direct_dispatcher_pair()
     binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=_noop_handler)
     session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
-    with caplog.at_level(logging.DEBUG, logger="client"), anyio.fail_after(5):
+    with anyio.fail_after(5):
         async with anyio.create_task_group() as tg:
             await tg.start(server_side.run, _server_on_request, _server_on_notify)
             async with session:
@@ -202,7 +202,7 @@ async def test_unbound_vendor_notification_is_dropped_with_a_warning(caplog: pyt
         "and no notification binding is registered"
     )
     levels = [r.levelno for r in caplog.records if r.getMessage() == expected]
-    assert levels == [logging.WARNING, logging.DEBUG]
+    assert levels == [logging.WARNING, logging.WARNING]
 
 
 @pytest.mark.anyio