refactor: split RequestContext between server and client (#1987)

src/mcp/server/context.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from mcp.server.experimental.request_context import Experimental
+from mcp.server.session import ServerSession
+from mcp.shared.context import RequestContext
+from mcp.shared.message import CloseSSEStreamCallback
+
+LifespanContextT = TypeVar("LifespanContextT")
+RequestT = TypeVar("RequestT", default=Any)
+
+
+@dataclass(kw_only=True)
+class ServerRequestContext(RequestContext[ServerSession], Generic[LifespanContextT, RequestT]):
+    lifespan_context: LifespanContextT
+    experimental: Experimental
+    request: RequestT | None = None
+    close_sse_stream: CloseSSEStreamCallback | None = None
+    close_standalone_sse_stream: CloseSSEStreamCallback | None = None

src/mcp/server/experimental/request_context.py

@@ -57,10 +57,7 @@ class Experimental:
         return self._client_capabilities.tasks is not None
 
     def validate_task_mode(
-        self,
-        tool_task_mode: TaskExecutionMode | None,
-        *,
-        raise_error: bool = True,
+        self, tool_task_mode: TaskExecutionMode | None, *, raise_error: bool = True
     ) -> ErrorData | None:
         """Validate that the request is compatible with the tool's task execution mode.
 
@@ -95,12 +92,7 @@ class Experimental:
 
         return error
 
-    def validate_for_tool(
-        self,
-        tool: Tool,
-        *,
-        raise_error: bool = True,
-    ) -> ErrorData | None:
+    def validate_for_tool(self, tool: Tool, *, raise_error: bool = True) -> ErrorData | None:
         """Validate that the request is compatible with the given tool.
 
         Convenience wrapper around validate_task_mode that extracts the mode from a Tool.

src/mcp/server/lowlevel/server.py

@@ -91,6 +91,7 @@ from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend, RequireAut
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider, TokenVerifier
 from mcp.server.auth.routes import build_resource_metadata_url, create_auth_routes, create_protected_resource_routes
 from mcp.server.auth.settings import AuthSettings
+from mcp.server.context import ServerRequestContext
 from mcp.server.experimental.request_context import Experimental
 from mcp.server.lowlevel.experimental import ExperimentalHandlers
 from mcp.server.lowlevel.func_inspection import create_call_wrapper
@@ -100,7 +101,6 @@ from mcp.server.session import ServerSession
 from mcp.server.streamable_http import EventStore
 from mcp.server.streamable_http_manager import StreamableHTTPASGIApp, StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
-from mcp.shared.context import RequestContext
 from mcp.shared.exceptions import MCPError, UrlElicitationRequiredError
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
@@ -117,16 +117,11 @@ UnstructuredContent: TypeAlias = Iterable[types.ContentBlock]
 CombinationContent: TypeAlias = tuple[UnstructuredContent, StructuredContent]
 
 # This will be properly typed in each Server instance's context
-request_ctx: contextvars.ContextVar[RequestContext[ServerSession, Any, Any]] = contextvars.ContextVar("request_ctx")
+request_ctx: contextvars.ContextVar[ServerRequestContext[Any, Any]] = contextvars.ContextVar("request_ctx")
 
 
 class NotificationOptions:
-    def __init__(
-        self,
-        prompts_changed: bool = False,
-        resources_changed: bool = False,
-        tools_changed: bool = False,
-    ):
+    def __init__(self, prompts_changed: bool = False, resources_changed: bool = False, tools_changed: bool = False):
         self.prompts_changed = prompts_changed
         self.resources_changed = resources_changed
         self.tools_changed = tools_changed
@@ -253,9 +248,7 @@ class Server(Generic[LifespanResultT, RequestT]):
         return capabilities
 
     @property
-    def request_context(
-        self,
-    ) -> RequestContext[ServerSession, LifespanResultT, RequestT]:
+    def request_context(self) -> ServerRequestContext[LifespanResultT, RequestT]:
         """If called outside of a request context, this will raise a LookupError."""
         return request_ctx.get()
 
@@ -762,12 +755,12 @@ class Server(Generic[LifespanResultT, RequestT]):
                 if hasattr(req, "params") and req.params is not None:
                     task_metadata = getattr(req.params, "task", None)
                 token = request_ctx.set(
-                    RequestContext(
-                        message.request_id,
-                        message.request_meta,
-                        session,
-                        lifespan_context,
-                        Experimental(
+                    ServerRequestContext(
+                        request_id=message.request_id,
+                        meta=message.request_meta,
+                        session=session,
+                        lifespan_context=lifespan_context,
+                        experimental=Experimental(
                             task_metadata=task_metadata,
                             _client_capabilities=client_capabilities,
                             _session=session,

src/mcp/server/mcpserver/prompts/base.py

@@ -14,9 +14,8 @@ from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.types import ContentBlock, Icon, TextContent
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT, RequestT
 
 
 class Message(BaseModel):
@@ -137,7 +136,7 @@ class Prompt(BaseModel):
     async def render(
         self,
         arguments: dict[str, Any] | None = None,
-        context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT] | None = None,
     ) -> list[Message]:
         """Render the prompt with arguments."""
         # Validate required arguments

src/mcp/server/mcpserver/prompts/manager.py

@@ -8,9 +8,8 @@ from mcp.server.mcpserver.prompts.base import Message, Prompt
 from mcp.server.mcpserver.utilities.logging import get_logger
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT, RequestT
 
 logger = get_logger(__name__)
 
@@ -50,7 +49,7 @@ class PromptManager:
         self,
         name: str,
         arguments: dict[str, Any] | None = None,
-        context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT] | None = None,
     ) -> list[Message]:
         """Render a prompt by name with arguments."""
         prompt = self.get_prompt(name)

src/mcp/server/mcpserver/resources/resource_manager.py

@@ -13,9 +13,8 @@ from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.types import Annotations, Icon
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT, RequestT
 
 logger = get_logger(__name__)
 
@@ -82,7 +81,7 @@ class ResourceManager:
         return template
 
     async def get_resource(
-        self, uri: AnyUrl | str, context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None
+        self, uri: AnyUrl | str, context: Context[LifespanContextT, RequestT] | None = None
     ) -> Resource:
         """Get resource by URI, checking concrete resources first, then templates."""
         uri_str = str(uri)

src/mcp/server/mcpserver/resources/templates.py

@@ -16,9 +16,8 @@ from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.types import Annotations, Icon
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT, RequestT
 
 
 class ResourceTemplate(BaseModel):
@@ -100,7 +99,7 @@ class ResourceTemplate(BaseModel):
         self,
         uri: str,
         params: dict[str, Any],
-        context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT] | None = None,
     ) -> Resource:
         """Create a resource from the template with the given parameters."""
         try:

src/mcp/server/mcpserver/server.py

@@ -25,6 +25,7 @@ from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend, RequireAuthMiddleware
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider, ProviderTokenVerifier, TokenVerifier
 from mcp.server.auth.settings import AuthSettings
+from mcp.server.context import LifespanContextT, RequestT, ServerRequestContext
 from mcp.server.elicitation import ElicitationResult, ElicitSchemaModelT, UrlElicitationResult, elicit_with_validation
 from mcp.server.elicitation import elicit_url as _elicit_url
 from mcp.server.lowlevel.helper_types import ReadResourceContents
@@ -36,13 +37,11 @@ from mcp.server.mcpserver.resources import FunctionResource, Resource, ResourceM
 from mcp.server.mcpserver.tools import Tool, ToolManager
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter
 from mcp.server.mcpserver.utilities.logging import configure_logging, get_logger
-from mcp.server.session import ServerSession, ServerSessionT
 from mcp.server.sse import SseServerTransport
 from mcp.server.stdio import stdio_server
 from mcp.server.streamable_http import EventStore
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
-from mcp.shared.context import LifespanContextT, RequestContext, RequestT
 from mcp.types import Annotations, ContentBlock, GetPromptResult, Icon, ToolAnnotations
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
@@ -294,7 +293,7 @@ class MCPServer(Generic[LifespanResultT]):
             for info in tools
         ]
 
-    def get_context(self) -> Context[ServerSession, LifespanResultT, Request]:
+    def get_context(self) -> Context[LifespanResultT, Request]:
         """Returns a Context object. Note that the context will only be valid
         during a request; outside a request, most methods will error.
         """
@@ -972,7 +971,7 @@ class MCPServer(Generic[LifespanResultT]):
             raise ValueError(str(e))
 
 
-class Context(BaseModel, Generic[ServerSessionT, LifespanContextT, RequestT]):
+class Context(BaseModel, Generic[LifespanContextT, RequestT]):
     """Context object providing access to MCP capabilities.
 
     This provides a cleaner interface to MCP's RequestContext functionality.
@@ -1006,14 +1005,15 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT, RequestT]):
     The context is optional - tools that don't need it can omit the parameter.
     """
 
-    _request_context: RequestContext[ServerSessionT, LifespanContextT, RequestT] | None
+    _request_context: ServerRequestContext[LifespanContextT, RequestT] | None
     _mcp_server: MCPServer | None
 
     def __init__(
         self,
         *,
-        request_context: (RequestContext[ServerSessionT, LifespanContextT, RequestT] | None) = None,
+        request_context: ServerRequestContext[LifespanContextT, RequestT] | None = None,
         mcp_server: MCPServer | None = None,
+        # TODO(Marcelo): We should drop this kwargs parameter.
         **kwargs: Any,
     ):
         super().__init__(**kwargs)
@@ -1028,9 +1028,7 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT, RequestT]):
         return self._mcp_server  # pragma: no cover
 
     @property
-    def request_context(
-        self,
-    ) -> RequestContext[ServerSessionT, LifespanContextT, RequestT]:
+    def request_context(self) -> ServerRequestContext[LifespanContextT, RequestT]:
         """Access to the underlying request context."""
         if self._request_context is None:  # pragma: no cover
             raise ValueError("Context is not available outside of a request")

src/mcp/server/mcpserver/tools/base.py

@@ -16,9 +16,8 @@ from mcp.shared.tool_name_validation import validate_and_warn_tool_name
 from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT, RequestT
 
 
 class Tool(BaseModel):
@@ -93,7 +92,7 @@ class Tool(BaseModel):
     async def run(
         self,
         arguments: dict[str, Any],
-        context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT] | None = None,
         convert_result: bool = False,
     ) -> Any:
         """Run the tool with arguments."""

src/mcp/server/mcpserver/tools/tool_manager.py

@@ -6,12 +6,11 @@ from typing import TYPE_CHECKING, Any
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.tools.base import Tool
 from mcp.server.mcpserver.utilities.logging import get_logger
-from mcp.shared.context import LifespanContextT, RequestT
 from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
+    from mcp.server.context import LifespanContextT, RequestT
     from mcp.server.mcpserver.server import Context
-    from mcp.server.session import ServerSessionT
 
 logger = get_logger(__name__)
 
@@ -82,7 +81,7 @@ class ToolManager:
         self,
         name: str,
         arguments: dict[str, Any],
-        context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT] | None = None,
         convert_result: bool = False,
     ) -> Any:
         """Call a tool by name with arguments."""