Repository navigation
ClientSession: add public API for updating callbacks after initialization #2379
Description
Problem
ClientSession accepts callback parameters (list_roots_callback, sampling_callback, elicitation_callback) at initialization, but provides no public API to update them after the session is created.
This means any client that needs to change callbacks at runtime (e.g., updating roots in response to user action) must mutate private attributes like _list_roots_callback directly — which is fragile and couples consumers to implementation details.
Use case
A client connects to a server with initial roots, then the user changes the working directory or project context. The client needs to update its roots callback so that the next roots/list request from the server reflects the new roots. Today this requires:
session._list_roots_callback = new_callback # private attributeThe same issue applies to _sampling_callback and _elicitation_callback.
Proposed solution
Add public setter methods on ClientSession for updating callbacks after initialization. For example:
session.set_list_roots_callback(callback)
session.set_sampling_callback(callback)
session.set_elicitation_callback(callback)Or alternatively, make the callback attributes public (without the leading underscore).
Context
This came up while fixing PrefectHQ/fastmcp#326 — Client.set_roots() wasn't updating the live session because it only modified pending kwargs. The fix (PrefectHQ/fastmcp#3714) mutates _list_roots_callback directly with a comment noting the fragility. A public API would make this safe and stable.
Activity
mgierschdev commentedon Apr 1, 2026
@dgenio looking to do my first contribution inside github, can I take this task?
dgenio commentedon Apr 1, 2026
Sure, go ahead! I'm not a maintainer so I'm not sure if they agree with this proposal
mgierschdev commentedon Apr 2, 2026
I thought you were, I think I'll better wait for it to be approved
feat: add public setter methods for ClientSession callbacks
dgenio commentedon Sep 16, 2026
Re-checking this after the v2 rewrite: I believe the underlying issue is still relevant, although the right API may be slightly different from the original proposal.
On current
main,ClientSessionstill storessampling_callback,elicitation_callback, andlist_roots_callbackprivately. The high-levelClientexposes these as public fields, but_build_session()copies them into theClientSessionwhen the connection is established, so changing them while the client is connected does not affect the live session.One distinction that seems important in v2 is replacing callback behavior vs changing advertised capabilities.
Callbacks participate in client capability advertisement, so enabling a callback after negotiation (or disabling one that was advertised) could leave the negotiated capability state inconsistent. But replacing the implementation of a callback for a capability that is already enabled seems like a valid runtime operation.
Would maintainers be open to a public API for that narrower operation?
For example, either:
with clearly documented capability semantics, or public mutable callback properties / another indirection mechanism.
I'm happy to prepare a fresh v2-native PR once there is agreement on the intended API.
For the original FastMCP roots use case, I think FastMCP can also avoid callback replacement by keeping a stable callback backed by mutable roots state, so I no longer see that particular case as requiring an SDK change. The broader runtime callback-replacement API still seems useful, particularly for elicitation/sampling and the v2 multi-round-trip flow.