feat: add ClientRequestContext type alias for client-side handlers

Introduce a dedicated `ClientRequestContext` type alias in
`mcp.client.context` to provide a cleaner API for client-side callback
handlers (sampling, elicitation, list_roots).

This improves the developer experience by:
- Providing a concrete type instead of requiring `RequestContext[ClientSession]`
- Making the internal `RequestContext` private by moving it to `_context.py`
- Exporting `ClientRequestContext` from `mcp.client` for easy access

All examples and conformance tests have been updated to use
`ClientRequestContext` instead of the internal `RequestContext` type.

The migration guide has been updated to reflect these changes.

Author: Kludex

.github/actions/conformance/client.py

@@ -38,9 +38,9 @@
     PrivateKeyJWTOAuthProvider,
     SignedJWTParameters,
 )
+from mcp.client.context import ClientRequestContext
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
-from mcp.shared.context import RequestContext
 
 # Set up logging to stderr (stdout is for conformance test output)
 logging.basicConfig(
@@ -187,7 +187,7 @@ async def run_sse_retry(server_url: str) -> None:
 
 
 async def default_elicitation_callback(
-    context: RequestContext[ClientSession],
+    context: ClientRequestContext,
     params: types.ElicitRequestParams,
 ) -> types.ElicitResult | types.ErrorData:
     """Accept elicitation and apply defaults from the schema (SEP-1034)."""

README.md

@@ -2120,8 +2120,8 @@ import asyncio
 import os
 
 from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.context import ClientRequestContext
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(
@@ -2133,7 +2133,7 @@ server_params = StdioServerParameters(
 
 # Optional: create a sampling callback
 async def handle_sampling_message(
-    context: RequestContext[ClientSession, None], params: types.CreateMessageRequestParams
+    context: ClientRequestContext, params: types.CreateMessageRequestParams
 ) -> types.CreateMessageResult:
     print(f"Sampling request: {params.messages}")
     return types.CreateMessageResult(

README.v2.md

@@ -2121,8 +2121,8 @@ import asyncio
 import os
 
 from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.context import ClientRequestContext
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(
@@ -2134,7 +2134,7 @@ server_params = StdioServerParameters(
 
 # Optional: create a sampling callback
 async def handle_sampling_message(
-    context: RequestContext[ClientSession], params: types.CreateMessageRequestParams
+    context: ClientRequestContext, params: types.CreateMessageRequestParams
 ) -> types.CreateMessageResult:
     print(f"Sampling request: {params.messages}")
     return types.CreateMessageResult(

docs/migration.md

@@ -387,6 +387,7 @@ The `RequestContext` class has been split to separate shared fields from server-
 **Before (v1):**
 
 ```python
+from mcp.client.session import ClientSession
 from mcp.shared.context import RequestContext, LifespanContextT, RequestT
 from mcp.shared.progress import ProgressContext
 
@@ -400,19 +401,19 @@ progress_ctx: ProgressContext[SendRequestT, SendNotificationT, SendResultT, Rece
 **After (v2):**
 
 ```python
-from mcp.shared.context import RequestContext
+from mcp.client.context import ClientRequestContext
+from mcp.client.session import ClientSession
+from mcp.server.context import ServerRequestContext, LifespanContextT, RequestT
 from mcp.shared.progress import ProgressContext
 
-# RequestContext with 1 type parameter
-ctx: RequestContext[ClientSession]
-
-# ProgressContext with 1 type parameter
-progress_ctx: ProgressContext[ClientSession]
+# For client-side context (sampling, elicitation, list_roots callbacks)
+ctx: ClientRequestContext
 
 # For server-specific context with lifespan and request types
-from mcp.server.context import ServerRequestContext, LifespanContextT, RequestT
-
 server_ctx: ServerRequestContext[LifespanContextT, RequestT]
+
+# ProgressContext with 1 type parameter
+progress_ctx: ProgressContext[ClientSession]
 ```
 
 ### Resource URI type changed from `AnyUrl` to `str`

examples/clients/simple-task-interactive-client/mcp_simple_task_interactive_client/main.py

@@ -10,8 +10,8 @@
 
 import click
 from mcp import ClientSession
+from mcp.client.context import ClientRequestContext
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared.context import RequestContext
 from mcp.types import (
     CallToolResult,
     CreateMessageRequestParams,
@@ -23,7 +23,7 @@
 
 
 async def elicitation_callback(
-    context: RequestContext[ClientSession],
+    context: ClientRequestContext,
     params: ElicitRequestParams,
 ) -> ElicitResult:
     """Handle elicitation requests from the server."""
@@ -38,7 +38,7 @@ async def elicitation_callback(
 
 
 async def sampling_callback(
-    context: RequestContext[ClientSession],
+    context: ClientRequestContext,
     params: CreateMessageRequestParams,
 ) -> CreateMessageResult:
     """Handle sampling requests from the server."""

examples/snippets/clients/stdio_client.py

@@ -6,8 +6,8 @@
 import os
 
 from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.context import ClientRequestContext
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(
@@ -19,7 +19,7 @@
 
 # Optional: create a sampling callback
 async def handle_sampling_message(
-    context: RequestContext[ClientSession], params: types.CreateMessageRequestParams
+    context: ClientRequestContext, params: types.CreateMessageRequestParams
 ) -> types.CreateMessageResult:
     print(f"Sampling request: {params.messages}")
     return types.CreateMessageResult(

examples/snippets/clients/url_elicitation_client.py

@@ -31,14 +31,14 @@
 from urllib.parse import urlparse
 
 from mcp import ClientSession, types
+from mcp.client.context import ClientRequestContext
 from mcp.client.sse import sse_client
-from mcp.shared.context import RequestContext
 from mcp.shared.exceptions import MCPError, UrlElicitationRequiredError
 from mcp.types import URL_ELICITATION_REQUIRED
 
 
 async def handle_elicitation(
-    context: RequestContext[ClientSession],
+    context: ClientRequestContext,
     params: types.ElicitRequestParams,
 ) -> types.ElicitResult | types.ErrorData:
     """Handle elicitation requests from the server.

src/mcp/client/__init__.py

@@ -2,6 +2,7 @@
 
 from mcp.client._transport import Transport
 from mcp.client.client import Client
+from mcp.client.context import ClientRequestContext
 from mcp.client.session import ClientSession
 
-__all__ = ["Client", "ClientSession", "Transport"]
+__all__ = ["Client", "ClientRequestContext", "ClientSession", "Transport"]

src/mcp/client/context.py

@@ -0,0 +1,16 @@
+"""Request context for MCP client handlers."""
+
+from mcp.client.session import ClientSession
+from mcp.shared._context import RequestContext
+
+ClientRequestContext = RequestContext[ClientSession]
+"""Context for handling incoming requests in a client session.
+
+This context is passed to client-side callbacks (sampling, elicitation, list_roots) when the server sends requests
+to the client.
+
+Attributes:
+    request_id: The unique identifier for this request.
+    meta: Optional metadata associated with the request.
+    session: The client session handling this request.
+"""

src/mcp/client/experimental/task_handlers.py

@@ -19,7 +19,7 @@
 from pydantic import TypeAdapter
 
 import mcp.types as types
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 from mcp.shared.session import RequestResponder
 
 if TYPE_CHECKING: