`ClientConfig` has inconsistent naming: `message_handler` should be `message_callback`

[fuyu-quant]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

ClientConfig exposes five user-facing callback fields, but four of them use the *_callback suffix while one uses *_handler:

# src/mcp/client/client.py
sampling_callback: SamplingFnT | None = None
list_roots_callback: ListRootsFnT | None = None
logging_callback: LoggingFnT | None = None
elicitation_callback: ElicitationFnT | None = None
message_handler: MessageHandlerFnT | None = None  # ← inconsistent

The same inconsistency is present in ClientSession.__init__ and ServerConnectionParams:

# src/mcp/client/session.py
def __init__(self, ..., message_handler: MessageHandlerFnT | None = None, ...)

# src/mcp/client/session_group.py
class ServerConnectionParams:
    message_handler: MessageHandlerFnT | None = None

A TODO comment in the codebase already flags this:

# TODO(Marcelo): Why do we have both "callback" and "handler"?
message_handler: MessageHandlerFnT | None = None

Proposed Fix

Rename message_handler → message_callback consistently across all three sites:

File	Change
src/mcp/client/client.py	message_handler → message_callback (field + forwarding call)
src/mcp/client/session.py	message_handler parameter → message_callback; internal _message_handler → _message_callback
src/mcp/client/session_group.py	ServerConnectionParams.message_handler → message_callback + forwarding call
src/mcp/client/__main__.py	local variable + keyword arg rename

Since this is the v2 rewrite on main, a breaking rename is appropriate and there is no need for a deprecation shim.

I'd like to take this on if you're open to a fix.

Python & MCP Python SDK

Python 3.13
Reproduced on: main @ 161834d (2026-05-13)

[scosemicolon]

This rename looks clean for main. Two small follow-up checks I would include in the PR:

• search examples/docs for message_handler= as well as source/tests, since keyword-call examples are the most likely copy-paste break
• add one construction test that passes message_callback= through ClientConfig -> ClientSession, then verifies the raw-message path still reaches the provided callback

Since ClientConfig is a dataclass, I agree a deprecation shim is probably not worth carrying on the v2 branch unless maintainers want temporary keyword compatibility. The important part is making the forwarding sites fail loudly in tests if one of them keeps the old name.