refactor(client): rename message_handler to message_callback for naming consistency

Closes #2588.

The five user-facing callback fields on ClientConfig / ClientSession /
ServerConnectionParams were inconsistently named (four used *_callback,
one used *_handler). Rename message_handler -> message_callback across:

  src/mcp/client/client.py        ClientConfig field + forwarding call
  src/mcp/client/session.py       ClientSession.__init__ param +
                                  internal _message_handler ->
                                  _message_callback; related docstring
                                  and log messages updated
  src/mcp/client/session_group.py ServerConnectionParams field +
                                  forwarding call
  src/mcp/client/__main__.py      CLI entry point
  src/mcp/client/subscriptions.py docstring
  src/mcp/shared/jsonrpc_dispatcher.py docstring

Type alias MessageHandlerFnT is intentionally not renamed (separate
naming layer). Test usages updated across the codebase.

Since this lands on the v2 rewrite on main, a breaking rename is
appropriate without a deprecation shim. 4383 tests pass; ruff lint
and format clean.

Author: sanjibani

examples/stories/standalone_get/client.py

@@ -8,7 +8,7 @@
 
 
 async def main(target: Target, *, mode: str = "auto") -> None:
-    # `message_handler` is constructor-only on `Client`, so the event it sets
+    # `message_callback` is constructor-only on `Client`, so the event it sets
     # has to exist before the connection does.
     received: list[types.ResourceListChangedNotification] = []
     seen = anyio.Event()
@@ -18,7 +18,7 @@ async def on_message(message: object) -> None:
             received.append(message)
             seen.set()
 
-    async with Client(target, mode=mode, message_handler=on_message) as client:
+    async with Client(target, mode=mode, message_callback=on_message) as client:
         before = await client.list_resources()
         assert len(before.resources) >= 1, before
 

examples/stories/stickynotes/client.py

@@ -22,7 +22,7 @@ async def on_message(message: object) -> None:
         if isinstance(message, types.ResourceListChangedNotification):
             list_changed.set()
 
-    async with Client(target, mode=mode, elicitation_callback=on_elicit, message_handler=on_message) as client:
+    async with Client(target, mode=mode, elicitation_callback=on_elicit, message_callback=on_message) as client:
         legacy = client.protocol_version in HANDSHAKE_PROTOCOL_VERSIONS
 
         # Add two notes.

src/mcp/client/__main__.py

@@ -22,7 +22,7 @@
 logger = logging.getLogger("client")
 
 
-async def message_handler(
+async def message_callback(
     message: RequestResponder[types.ServerRequest, types.ClientResult] | types.ServerNotification | Exception,
 ) -> None:
     if isinstance(message, Exception):
@@ -40,7 +40,7 @@ async def run_session(
     async with ClientSession(
         read_stream,
         write_stream,
-        message_handler=message_handler,
+        message_callback=message_callback,
         client_info=client_info,
     ) as session:
         logger.info("Initializing session")

src/mcp/client/client.py

@@ -152,7 +152,7 @@ def _strip_userinfo(url: str) -> str:
     return url[:start] + authority.rpartition("@")[2] + url[end:]
 
 
-def _evicting_message_handler(cache: ClientResponseCache, user_handler: MessageHandlerFnT | None) -> MessageHandlerFnT:
+def _evicting_message_callback(cache: ClientResponseCache, user_handler: MessageHandlerFnT | None) -> MessageHandlerFnT:
     """Wrap the session message handler with cache eviction on server notifications."""
 
     async def handler(
@@ -166,7 +166,7 @@ async def handler(
         if user_handler is not None:
             await user_handler(message)
         else:
-            # Mirrors ClientSession's default handler (session._default_message_handler).
+            # Mirrors ClientSession's default handler (session._default_message_callback).
             await anyio.lowlevel.checkpoint()
 
     return handler
@@ -316,7 +316,7 @@ async def main():
     """Callback for handling logging notifications."""
 
     # TODO(Marcelo): Why do we have both "callback" and "handler"?
-    message_handler: MessageHandlerFnT | None = None
+    message_callback: MessageHandlerFnT | None = None
     """Callback for handling raw messages."""
 
     client_info: Implementation | None = None
@@ -417,17 +417,17 @@ def __post_init__(self) -> None:
     async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
         """Enter the resolved connector and return an un-entered ClientSession."""
         dispatcher = await self._connect(exit_stack, self.mode, self.raise_exceptions)
-        message_handler = self.message_handler
+        message_callback = self.message_callback
         if self._response_cache is not None:
-            message_handler = _evicting_message_handler(self._response_cache, self.message_handler)
+            message_callback = _evicting_message_callback(self._response_cache, self.message_callback)
         return ClientSession(
             dispatcher=dispatcher,
             read_timeout_seconds=self.read_timeout_seconds,
             sampling_callback=self.sampling_callback,
             sampling_capabilities=self.sampling_capabilities,
             list_roots_callback=self.list_roots_callback,
             logging_callback=self.logging_callback,
-            message_handler=message_handler,
+            message_callback=message_callback,
             client_info=self.client_info,
             elicitation_callback=self.elicitation_callback,
             extensions=self._folded_extensions.ad,

src/mcp/client/session.py

@@ -163,7 +163,7 @@ async def __call__(
     ) -> None: ...  # pragma: no branch
 
 
-async def _default_message_handler(
+async def _default_message_callback(
     message: RequestResponder[types.ServerRequest, types.ClientResult] | types.ServerNotification | Exception,
 ) -> None:
     await anyio.lowlevel.checkpoint()
@@ -315,7 +315,7 @@ class ClientSession:
     `dispatcher=`), enter as an async context manager, then call
     `initialize()`. The dispatcher owns the receive loop and request
     correlation; this class owns the typed MCP layer and the constructor
-    callbacks. Transport `Exception` items reach `message_handler` only when
+    callbacks. Transport `Exception` items reach `message_callback` only when
     the session builds its own dispatcher from a stream pair.
 
     Extension `result_claims` fold into tools/call parsing at `adopt()`;
@@ -331,7 +331,7 @@ def __init__(
         elicitation_callback: ElicitationFnT | None = None,
         list_roots_callback: ListRootsFnT | None = None,
         logging_callback: LoggingFnT | None = None,
-        message_handler: MessageHandlerFnT | None = None,
+        message_callback: MessageHandlerFnT | None = None,
         client_info: types.Implementation | None = None,
         *,
         sampling_capabilities: types.SamplingCapability | None = None,
@@ -355,7 +355,7 @@ def __init__(
         self._elicitation_callback = elicitation_callback or _default_elicitation_callback
         self._list_roots_callback = list_roots_callback or _default_list_roots_callback
         self._logging_callback = logging_callback or _default_logging_callback
-        self._message_handler = message_handler or _default_message_handler
+        self._message_callback = message_callback or _default_message_callback
         self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
         self._x_mcp_header_maps: dict[str, dict[tuple[str, ...], str]] = {}
         self._initialize_result: types.InitializeResult | None = None
@@ -370,7 +370,7 @@ def __init__(
                 raise ValueError("pass read_stream/write_stream or dispatcher, not both")
             self._dispatcher: Dispatcher[Any] = dispatcher
             if isinstance(dispatcher, JSONRPCDispatcher) and dispatcher.on_stream_exception is None:
-                # Route transport-level Exception items into message_handler — only
+                # Route transport-level Exception items into message_callback — only
                 # stream-backed dispatchers carry these; DirectDispatcher has none.
                 # Don't clobber a caller-supplied hook.
                 # TODO(L78): this leaves a bound-method ref on the dispatcher after the
@@ -1367,7 +1367,7 @@ def _intercept_notification(self, method: str, params: Mapping[str, Any] | None)
     async def _on_notify(
         self, dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
     ) -> None:
-        """Route a server notification: validate, run the typed callback, tee to message_handler."""
+        """Route a server notification: validate, run the typed callback, tee to message_callback."""
         # Same fallback as `_on_request`: covers pre-handshake and stateless.
         version = self._negotiated_version or "2025-11-25"
         try:
@@ -1403,16 +1403,16 @@ async def _on_notify(
         try:
             if isinstance(notification, types.LoggingMessageNotification):
                 await self._logging_callback(notification.params)
-            await self._message_handler(notification)
+            await self._message_callback(notification)
         except Exception:
             # Contain here, not in the dispatcher: DirectDispatcher awaits this
             # handler inline in the peer's notify() call, so a raising callback
             # would otherwise fail the peer's send. A raising logging_callback
-            # skips the message_handler tee for that notification (v1 parity).
+            # skips the message_callback tee for that notification (v1 parity).
             logger.exception("notification callback for %r raised", method)
 
     async def _on_stream_exception(self, exc: Exception) -> None:
-        """Deliver a transport-level fault to message_handler via a spawned task.
+        """Deliver a transport-level fault to message_callback via a spawned task.
 
         Running the handler inline would park the dispatcher's read loop and
         deadlock handlers that await session I/O.
@@ -1422,6 +1422,6 @@ async def _on_stream_exception(self, exc: Exception) -> None:
 
     async def _deliver_stream_exception(self, exc: Exception) -> None:
         try:
-            await self._message_handler(exc)
+            await self._message_callback(exc)
         except Exception:
-            logger.exception("message_handler raised on transport exception")
+            logger.exception("message_callback raised on transport exception")

src/mcp/client/session_group.py

@@ -78,7 +78,7 @@ class ClientSessionParameters:
     elicitation_callback: ElicitationFnT | None = None
     list_roots_callback: ListRootsFnT | None = None
     logging_callback: LoggingFnT | None = None
-    message_handler: MessageHandlerFnT | None = None
+    message_callback: MessageHandlerFnT | None = None
     client_info: types.Implementation | None = None
 
 
@@ -347,7 +347,7 @@ async def _establish_session(
                     elicitation_callback=session_params.elicitation_callback,
                     list_roots_callback=session_params.list_roots_callback,
                     logging_callback=session_params.logging_callback,
-                    message_handler=session_params.message_handler,
+                    message_callback=session_params.message_callback,
                     client_info=session_params.client_info,
                 )
             )

src/mcp/client/subscriptions.py

@@ -64,7 +64,7 @@ def __init__(self, negotiated_version: str | None) -> None:
         super().__init__(
             f"subscriptions/listen is not available at protocol version {negotiated_version!r}; it requires "
             "2026-07-28. On earlier versions use subscribe_resource() and the change notifications delivered "
-            "through message_handler."
+            "through message_callback."
         )
 
 

src/mcp/shared/jsonrpc_dispatcher.py

@@ -291,7 +291,7 @@ def __init__(
         self.on_stream_exception = on_stream_exception
         """Observer for ``Exception`` items on the read stream. Mutable so a session can
         bind it after the dispatcher is built (e.g. ``ClientSession`` routing into
-        ``message_handler``); only consulted inside ``run()`` so pre-enter assignment is safe."""
+        ``message_callback``); only consulted inside ``run()`` so pre-enter assignment is safe."""
 
         self._next_id = 0
         self._pending: dict[RequestId, _Pending] = {}

tests/client/test_client_caching.py

@@ -217,11 +217,11 @@ async def test_cache_false_disables_the_cache_and_the_handler_wrap() -> None:
     async def handler(message: IncomingMessage) -> None:
         raise NotImplementedError
 
-    client = Client(_list_changed_server(), cache=False, message_handler=handler)
+    client = Client(_list_changed_server(), cache=False, message_callback=handler)
     assert client._response_cache is None
 
     async with client:
-        assert client.session._message_handler is handler
+        assert client.session._message_callback is handler
 
 
 def test_the_default_cache_uses_a_per_client_in_memory_store() -> None:
@@ -284,7 +284,7 @@ async def collect(message: IncomingMessage) -> None:
         received.append(message)
         seen.set()
 
-    client = Client(_list_changed_server(), mode="legacy", message_handler=collect)
+    client = Client(_list_changed_server(), mode="legacy", message_callback=collect)
 
     async with client:
         key = await _warm_tools_list_entry(client)
@@ -304,10 +304,10 @@ async def test_non_notification_items_pass_through_to_the_user_handler_untouched
     async def collect(message: IncomingMessage) -> None:
         received.append(message)
 
-    client = Client(_list_changed_server(), message_handler=collect)
+    client = Client(_list_changed_server(), message_callback=collect)
 
     async with client:
-        installed = client.session._message_handler
+        installed = client.session._message_callback
         assert installed is not collect  # the wrap, not the bare user handler
         key = await _warm_tools_list_entry(client)
         fault = RuntimeError("stream broke")
@@ -328,7 +328,7 @@ async def collect(message: IncomingMessage) -> None:
         received.append(message)
         seen.set()
 
-    client = Client(_list_changed_server(), mode="legacy", message_handler=collect)
+    client = Client(_list_changed_server(), mode="legacy", message_callback=collect)
     # The wrap reads `_response_cache` at session build, so the swap must happen pre-enter.
     client._response_cache = _ExplodingCache(
         store=InMemoryResponseCacheStore(),
@@ -923,7 +923,7 @@ async def on_message(message: IncomingMessage) -> None:
         assert isinstance(message, ToolListChangedNotification)  # the only message this server emits
         delivered.set()
 
-    client = Client(server, mode="legacy", cache=CacheConfig(default_ttl_ms=60_000), message_handler=on_message)
+    client = Client(server, mode="legacy", cache=CacheConfig(default_ttl_ms=60_000), message_callback=on_message)
     async with client:
         await client.list_tools()
         await client.list_tools()
@@ -964,7 +964,7 @@ async def on_message(message: IncomingMessage) -> None:
         delivered.append(message.params.uri)
         seen.set()
 
-    client = Client(server, mode="legacy", cache=CacheConfig(default_ttl_ms=60_000), message_handler=on_message)
+    client = Client(server, mode="legacy", cache=CacheConfig(default_ttl_ms=60_000), message_callback=on_message)
     async with client:
         await client.read_resource(uri)
         await client.read_resource(uri)
@@ -1201,7 +1201,7 @@ async def on_message(message: IncomingMessage) -> None:
         server,
         mode="legacy",
         cache=CacheConfig(default_ttl_ms=60_000, clock=_ManualClock()),
-        message_handler=on_message,
+        message_callback=on_message,
     )
 
     async with client:
@@ -1469,7 +1469,7 @@ async def on_message(message: IncomingMessage) -> None:
         server,
         mode="legacy",
         cache=CacheConfig(default_ttl_ms=60_000, clock=_ManualClock()),
-        message_handler=on_message,
+        message_callback=on_message,
     )
 
     async with client:

tests/client/test_logging_callback.py

@@ -55,7 +55,7 @@ async def test_tool_with_log_dict(
         return True
 
     # Create a message handler to catch exceptions
-    async def message_handler(
+    async def message_callback(
         message: RequestResponder[types.ServerRequest, types.ClientResult] | types.ServerNotification | Exception,
     ) -> None:
         if isinstance(message, Exception):  # pragma: no cover
@@ -64,7 +64,7 @@ async def message_handler(
     async with Client(
         server,
         logging_callback=logging_collector,
-        message_handler=message_handler,
+        message_callback=message_callback,
         mode="legacy",
     ) as client:
         # First verify our test tool works