refactor: replace lowlevel Server decorators with on_* constructor kwargs #1985

maxisbey · 2026-02-02T21:27:16Z

Replace the decorator-based handler registration on the lowlevel Server with direct on_* keyword arguments on the constructor. Handlers are now raw callables with a uniform (ctx, params) -> result signature, dispatched by method string.

Delete func_inspection.py (no longer needed without decorator introspection)
Remove RequestT generic from Server (transport-specific, never bound at construction)
Decouple ExperimentalHandlers from Server internals via callbacks
Update MCPServer to pass on_* kwargs via _create_handler_kwargs()
Make RequestContext.request_id optional (notification handlers pass None)

Tests and examples not yet updated — they still use the old decorator API.

Supersedes #1968.

…args Replace the decorator-based handler registration on the lowlevel Server with direct on_* keyword arguments on the constructor. Handlers are raw callables with a uniform (ctx, params) -> result signature. - Server constructor takes on_list_tools, on_call_tool, etc. - String-keyed dispatch instead of type-keyed - Remove RequestT generic from Server (transport-specific, not bound at construction) - Delete handler.py and func_inspection.py (no longer needed) - Update ExperimentalHandlers to use callback-based registration - Update MCPServer to pass on_* kwargs via _create_handler_kwargs() - Update migration docs and docstrings

claude · 2026-02-03T15:34:33Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

maxisbey · 2026-02-03T15:34:55Z

src/mcp/server/mcpserver/server.py

            website_url=website_url,
            icons=icons,
            version=version,
+            **self._create_handler_kwargs(),


this is less nice than the Handler pattern here, but since it's internal not a big issue I suppose?

maxisbey · 2026-02-03T15:36:26Z

src/mcp/server/lowlevel/server.py

+            if handler is not None:
+                self._notification_handlers[method] = handler
+
+    def _add_request_handler(


not as type safe as if we did the Handler approach here.

I don't think we decided for sure whether we wanted to be able to register/remove endpoints at runtime. Thoughts @Kludex ?

src/mcp/server/lowlevel/server.py

maxisbey · 2026-02-03T15:39:05Z

src/mcp/server/mcpserver/server.py

+
+            # TODO(maxisbey): remove private access — completion needs post-construction
+            #   handler registration, find a better pattern for this
+            self._lowlevel_server._add_request_handler(  # pyright: ignore[reportPrivateUsage]


This usecase makes sense to me for adding request handlers after the fact... Unless we change it so that the Server object inside MCPServer is only constructed when you actually run the server, not when you construct MCPServer?

Thoughts @Kludex ?

maxisbey · 2026-02-03T15:41:18Z

src/mcp/shared/context.py

-    request_id: RequestId
-    meta: RequestParamsMeta | None
    session: SessionT
+    request_id: RequestId | None = None


Maybe worth having a notification specific context object so this doesn't need to be optional

…lers

Kludex · 2026-02-03T15:44:13Z

docs/migration.md

+) -> CallToolResult:
    if ctx.meta and "progress_token" in ctx.meta:
        await ctx.session.send_progress_notification(ctx.meta["progress_token"], 0.5, 100)
+    ...


Missing to actually pass it to the Server object.

Kludex · 2026-02-03T15:46:17Z

docs/migration.md

+from mcp.server.lowlevel import Server
+from mcp.shared.context import RequestContext


Suggested change

from mcp.server.lowlevel import Server

from mcp.shared.context import RequestContext

from mcp.server import Server, ServerRequestContext

Kludex · 2026-02-03T15:46:45Z

docs/migration.md

+    return ListToolsResult(tools=[
+        Tool(name="my_tool", description="A tool", inputSchema={})
+    ])


use ruff in this code please

Kludex · 2026-02-03T15:47:36Z

docs/migration.md

+server = Server(
+    "my-server",
+    on_progress=handle_progress,
+)


Suggested change

server = Server(

"my-server",

on_progress=handle_progress,

)

server = Server("my-server", on_progress=handle_progress)

Kludex · 2026-02-03T15:48:42Z

docs/migration.md

+from mcp.types import CallToolRequestParams, CallToolResult, TextContent
+
+async def handle_call_tool(
+    ctx: RequestContext, params: CallToolRequestParams


Thinking about this... It's also an option to rename the shared one to be BaseRequestContext, and then have 2 RequestContext that are imported from different modules... 😅

Suggested change

ctx: RequestContext, params: CallToolRequestParams

ctx: ServerRequestContext, params: CallToolRequestParams

Kludex · 2026-02-03T15:57:34Z

src/mcp/server/lowlevel/server.py

        ] = lifespan,
+        # Request handlers
+        on_list_tools: Callable[
+            [ServerRequestContext[LifespanResultT, Any], types.PaginatedRequestParams | None],


This should be RequestT, why did you drop it? 🤔

Kludex · 2026-02-03T15:59:05Z

src/mcp/server/lowlevel/server.py

+        _request_handler_map: list[
+            tuple[str, Callable[[ServerRequestContext[LifespanResultT, Any], Any], Awaitable[Any]] | None]
+        ] = [
+            ("ping", on_ping),
+            ("prompts/list", on_list_prompts),
+            ("prompts/get", on_get_prompt),
+            ("resources/list", on_list_resources),
+            ("resources/templates/list", on_list_resource_templates),
+            ("resources/read", on_read_resource),
+            ("resources/subscribe", on_subscribe_resource),
+            ("resources/unsubscribe", on_unsubscribe_resource),
+            ("tools/list", on_list_tools),
+            ("tools/call", on_call_tool),
+            ("logging/setLevel", on_set_logging_level),
+            ("completion/complete", on_completion),
+        ]
+        for method, handler in _request_handler_map:
+            if handler is not None:
+                self._request_handlers[method] = handler


Why a list of tuples instead of a dict?

is this used elsewhere?

src/mcp/server/lowlevel/server.py

Kludex · 2026-02-03T16:01:41Z

src/mcp/server/mcpserver/server.py

-        self._lowlevel_server.list_resource_templates()(self.list_resource_templates)
+    def _create_handler_kwargs(
+        self,
+    ) -> dict[str, Callable[[ServerRequestContext[Any, Any], Any], Awaitable[Any]]]:


This could be a TypedDict tho, you don't have generics.

and if you do, you now have type safety on the ** usage above.

hmmm... Do you even need this function? Can't you create each handler and pass it above?

Kludex · 2026-02-03T16:04:17Z

src/mcp/shared/message.py

+    # Transport-specific request context (e.g. starlette Request for HTTP
+    # transports, None for stdio). Typed as Any because the server layer is
+    # transport-agnostic.
+    request_context: Any = None


We should find a better solution here...

maxisbey mentioned this pull request Feb 3, 2026

sketch: refactor lowlevel server to handler pattern #1968

Closed

maxisbey changed the base branch from sketch/lowlevel-server-v2 to main February 3, 2026 14:06

maxisbey force-pushed the sketch/lowlevel-server-v2-kwargs branch from acea3d7 to 8e1d947 Compare February 3, 2026 15:27

maxisbey changed the title ~~refactor: replace Handler objects with on_* constructor kwargs~~ refactor: replace lowlevel Server decorators with on_* constructor kwargs Feb 3, 2026

maxisbey commented Feb 3, 2026

View reviewed changes

maxisbey marked this pull request as draft February 3, 2026 15:41

fix: remove unnecessary request_ctx contextvar from notification hand…

6c8abd3

…lers

Kludex reviewed Feb 3, 2026

View reviewed changes

		from mcp.server.lowlevel import Server
		from mcp.shared.context import RequestContext

	from mcp.server.lowlevel import Server
	from mcp.shared.context import RequestContext
	from mcp.server import Server, ServerRequestContext

	ctx: RequestContext, params: CallToolRequestParams
	ctx: ServerRequestContext, params: CallToolRequestParams

refactor: replace lowlevel Server decorators with on_* constructor kwargs #1985

Are you sure you want to change the base?

refactor: replace lowlevel Server decorators with on_* constructor kwargs #1985

Uh oh!

Conversation

maxisbey commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Feb 3, 2026

Code review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maxisbey commented Feb 2, 2026 •

edited

Loading