Skip to content

Support custom method handlers with custom params and return types on MCPServer #2105

@maxisbey

Description

@maxisbey

The SDK should provide a clear, documented way to register custom JSON-RPC method handlers on the server side that can:

  1. Receive custom parameter types — not just the built-in MCP request types, but arbitrary structured params (dicts, Pydantic models, etc.)
  2. Return custom response types — not just the built-in MCP result types

This is important for:

  • Protocol extensions and experimentation
  • Custom server-to-server communication patterns
  • Future spec features (e.g., MRTR) that may introduce new method/response types

The low-level server was recently refactored to use on_* constructor kwargs (PR #1985), which gives a cleaner handler registration pattern. This issue is about making sure there is an explicit, documented escape hatch for methods that are not part of the core MCP spec.

Open questions

  • Should custom handlers go through the same on_* pattern, or a separate register_method() API?
  • How do custom params get validated/parsed?
  • How does this interact with middleware (Middleware Support in MCP #1233)?

Ref: V2 planning discussion

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementRequest for a new feature that's not currently supportedv2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions