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.

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

Code review

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

src/mcp/server/mcpserver/server.py

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 ?

src/mcp/shared/_context.py

docs/migration.md

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? 🤔

I was thinking that it doesn't make sense to have RequestT be a generic parameter referencing the Transport on the Server class. This is because Server can be instantiated and then used for many different Transports, and you would only know the actual type depending on what you pass in to the run method.

I could be wrong, but it didn't make sense to me. You thinking something else?

But the ServerRequestContext depends on it anyway, so it seems something is wrong here.

This Any shouldn't be here.

I've changed RequestT in the context object to default to Any since it'll be refactored in #2021 anyway.

I've removed the Any, here and in a few other places.

src/mcp/server/lowlevel/server.py

src/mcp/server/mcpserver/server.py

src/mcp/shared/message.py

…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

…lers

- Fix all migration.md examples to use ServerRequestContext instead of RequestContext - Fix all imports to use 'from mcp.server import Server, ServerRequestContext' - Apply ruff formatting to code examples - Add Server constructor calls to examples that were missing them - Re-export ServerRequestContext from mcp.server.__init__ - Add type hints to TaskResultHandler docstring example

…erver Move handler functions from a dict-returning method to private methods on MCPServer, passed directly to the Server constructor by name. This eliminates the **kwargs unpacking pattern and makes the handler registration explicit.

Allow users to override default task handlers by passing on_get_task, on_task_result, on_list_tasks, and on_cancel_task to enable_tasks(). User-provided handlers are registered first; defaults fill in the rest.

Kludex · 2026-02-09T19:29:56Z

src/mcp/server/lowlevel/server.py

+                        _task_support=task_support,
+                    ),
+                )
+                await handler(ctx, getattr(notify, "params", None))


why do we need to use getattr?

Yea it's not, removed.

Kludex · 2026-02-09T19:30:20Z

src/mcp/server/lowlevel/server.py



-async def _ping_handler(request: types.PingRequest) -> types.ServerResult:
+async def _ping_handler(ctx: Any, params: Any) -> types.EmptyResult:


why Any again? Please check all Anys in this branch.

Yea definitely shouldn't be Any here. I've updated this Any as well as gone through all the other Anys added, I think it's in a better spot now.

…tT default

The subscribe capability in ResourcesCapability was hardcoded to False, even when on_subscribe_resource handler was provided. Now dynamically checks whether a subscribe handler is registered. Also applies ruff formatting to experimental.py.

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

Kludex reviewed Feb 3, 2026

View reviewed changes

maxisbey force-pushed the sketch/lowlevel-server-v2-kwargs branch from 28c7209 to 7221cca Compare February 6, 2026 16:48

maxisbey added 5 commits February 9, 2026 13:11

fix: remove unnecessary request_ctx contextvar from notification hand…

c5a5fb2

…lers

fix: collapse single-arg Server() to one line in migration example

67172b6

maxisbey force-pushed the sketch/lowlevel-server-v2-kwargs branch from 7221cca to 7e9e53f Compare February 9, 2026 13:38

maxisbey added 4 commits February 9, 2026 13:41

refactor: use dict instead of list of tuples for handler maps

bfe9537

docs: document keyword-only Server constructor params in migration guide

f41ec17

refactor: inline _register_default_task_handlers into enable_tasks

9f0ae6c

feat: add on_* handler kwargs to enable_tasks for custom task handlers

4150b2d

Allow users to override default task handlers by passing on_get_task, on_task_result, on_list_tasks, and on_cancel_task to enable_tasks(). User-provided handlers are registered first; defaults fill in the rest.

Kludex reviewed Feb 9, 2026

View reviewed changes

maxisbey added 5 commits February 10, 2026 13:57

refactor: drop explicit Any from ServerRequestContext, rely on Reques…

3fdee2b

…tT default

refactor: make ExperimentalHandlers generic on LifespanResultT

9835917

refactor: type MCPServer handler signatures instead of Any

7fb52b4

refactor: type notify as ClientNotification, remove getattr

addc451

fix: resolve pyright errors in ExperimentalHandlers.enable_tasks

eb011d5

maxisbey mentioned this pull request Feb 10, 2026

Add type annotations for all server decorators (list_tools, list_resources, read_resource) #1980

Closed

maxisbey added 2 commits February 10, 2026 17:50

refactor: make on_ping non-optional with default handler per MCP spec

e9df629



		async def _ping_handler(request: types.PingRequest) -> types.ServerResult:
		async def _ping_handler(ctx: Any, params: Any) -> types.EmptyResult:

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

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

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!

2 participants

maxisbey commented Feb 2, 2026 •

edited

Loading