fix: replace schema-based handlers with string method names by mattzcarey · Pull Request #1446 · modelcontextprotocol/typescript-sdk

mattzcarey · 2026-02-02T16:53:24Z

Remove schema imports and update setRequestHandler/setNotificationHandler calls to use string method names directly instead of schema objects. Update type annotations for elicitation content to use explicit union types and add const assertions for action returns.

Motivation and Context

Standardize method names and simplify the API. This brings it inline with the Python SDK and removes complex Zod schema introspection code.

How Has This Been Tested?

All 485 tests pass. Lint and typecheck pass.

Breaking Changes

`setRequestHandler` and `setNotificationHandler` API Change

Before:

import{InitializeRequestSchema}from'@modelcontextprotocol/core';server.setRequestHandler(InitializeRequestSchema,(request)=>{// handle initialize});

After:

server.setRequestHandler('initialize',(request)=>{// handle initialize - request is still fully typed});

The method string is now passed directly instead of the Zod schema. Type safety is preserved through RequestTypeMap and NotificationTypeMap.

New Exports

Export	Description
`RequestMethod`	Union type of all request method strings
`NotificationMethod`	Union type of all notification method strings
`RequestTypeMap`	Maps method string → request type
`NotificationTypeMap`	Maps method string → notification type
`getRequestSchema()`	Runtime lookup: method → Zod schema
`getNotificationSchema()`	Runtime lookup: method → Zod schema

Migration

Replace schema-based handler registration:

setRequestHandler(InitializeRequestSchema, ...) → setRequestHandler('initialize', ...)
setRequestHandler(CallToolRequestSchema, ...) → setRequestHandler('tools/call', ...)
setNotificationHandler(ProgressNotificationSchema, ...) → setNotificationHandler('notifications/progress', ...)

The request/notification parameter in your handler remains fully typed.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Remove schema imports and update setRequestHandler/setNotificationHandler calls to use string method names directly instead of schema objects. Update type annotations for elicitation content to use explicit union types and add const assertions for action returns.

changeset-bot · 2026-02-02T16:53:29Z

⚠️ No Changeset found

Latest commit: e7bcfc2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2026-02-02T16:54:37Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1446

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1446

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1446

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1446

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1446

commit: 36ac2c2

Remove redundant `as unknown as SendResultT` and `as Promise<SendResultT>` type assertions from ping handler and setRequestHandler since TypeScript can infer these types correctly.

felixweinberger · 2026-02-02T17:44:03Z

- setRequestHandler<T extends AnyObjectSchema>(
-requestSchema: T,
+ setRequestHandler<M extends RequestMethod>(
+method: M,


Important caveat discussed separately with @mattzcarey - this tightens the possibilities from any request to only requests actually defined on the MCP protocol.
Worth confirming this inadvertent capability wasn't being heavily used elsewhere.

we have fallbackRequestHandler for this

KKonstantinov · 2026-02-02T22:00:30Z

+ return map;
+}
+
+const requestSchemas = buildSchemaMap([...ClientRequestSchema.options, ...ServerRequestSchema.options] as const) as Record<


Leaving a note so we don't forget (here or in a follow up PR):
Client and Server support different client request and server request schemas, we should differentiate by that, client.setRequestHandler / server.setRequestHandler) to only allow what is acceptable for them respectively

@ts-expect-error

…ver, and Client After the string-based setRequestHandler API (PR #1446), the generic type parameters <RequestT, NotificationT, ResultT> on Server/Client and <SendRequestT, SendNotificationT, SendResultT> on Protocol no longer serve any purpose since custom methods cannot be registered. This removes them entirely, simplifying: - Protocol class declaration and all methods - RequestHandlerExtra type (no longer generic) - Server and Client class declarations - ExperimentalServerTasks and ExperimentalClientTasks - 4 @ts-expect-error comments that were needed to work around the generics Net -103 lines of type complexity.

@ts-expect-error

…ver, and Client After the string-based setRequestHandler API (PR #1446), the generic type parameters <RequestT, NotificationT, ResultT> on Server/Client and <SendRequestT, SendNotificationT, SendResultT> on Protocol no longer serve any purpose since custom methods cannot be registered. This removes them entirely, simplifying: - Protocol class declaration and all methods - RequestHandlerExtra type (no longer generic) - Server and Client class declarations - ExperimentalServerTasks and ExperimentalClientTasks - 4 @ts-expect-error comments that were needed to work around the generics Net -103 lines of type complexity.

Add RequestMethod, NotificationMethod, RequestTypeMap, NotificationTypeMap, getRequestSchema, and getNotificationSchema to the curated public API. These were introduced by the setRequestHandler string-based API change and are needed by users writing typed handlers or doing custom validation.

The string-based setRequestHandler API (from #1446) requires methods to be in the RequestTypeMap. Replace custom test method names (test/longRunning, test/method, etc.) with 'tools/call' which is a valid protocol method.

@ts-expect-error

…ver, and Client After the string-based setRequestHandler API (PR #1446), the generic type parameters <RequestT, NotificationT, ResultT> on Server/Client and <SendRequestT, SendNotificationT, SendResultT> on Protocol no longer serve any purpose since custom methods cannot be registered. This removes them entirely, simplifying: - Protocol class declaration and all methods - RequestHandlerExtra type (no longer generic) - Server and Client class declarations - ExperimentalServerTasks and ExperimentalClientTasks - 4 @ts-expect-error comments that were needed to work around the generics Net -103 lines of type complexity.

mattzcarey requested a review from a team as a code owner February 2, 2026 16:53

mattzcareyand others added 4 commits February 2, 2026 17:21

fix(core): remove unnecessary type assertions in protocol handlers
d5c3c0f
Remove redundant `as unknown as SendResultT` and `as Promise<SendResultT>` type assertions from ping handler and setRequestHandler since TypeScript can infer these types correctly.

Merge branch 'main' into feat/set-request-handler
3c9ef1b

Merge branch 'main' into feat/set-request-handler
8367617

chore: clean up type annotations in simpleStreamableHttp example
18c0ab6

felixweinberger reviewed Feb 2, 2026
View reviewed changes

mattzcarey changed the title ~~fix(client): replace schema-based handlers with string method names~~fix: replace schema-based handlers with string method namesFeb 2, 2026

docs: add migration notes for setRequestHandler method-string API
36ac2c2

felixweinberger approved these changes Feb 2, 2026
View reviewed changes

Merge branch 'main' into feat/set-request-handler
e7bcfc2

mattzcarey enabled auto-merge (squash) February 2, 2026 19:32

KKonstantinov reviewed Feb 2, 2026
View reviewed changes

felixweinberger mentioned this pull request Feb 2, 2026
[RFC] refactor: remove vestigial generic type parameters from Protocol, Server, and Client #1451
Merged
6 tasks

mattzcarey merged commit f6e8204 into mainFeb 2, 2026
10 of 24 checks passed

mattzcarey deleted the feat/set-request-handler branch February 2, 2026 23:57

felixweinberger mentioned this pull request Feb 3, 2026
[RFC]: tighten public API surface with explicit named exports #1447
Closed
6 tasks

This was referenced Feb 3, 2026
fix: tighten setRequestHandler types for Client and Server #1461
Closed
fix: tighten setRequestHandler types for Client and Server #1463
Closed

KKonstantinov linked an issue Mar 31, 2026 that may be closed by this pull request
Decouple from Zod, allow any validator (bring your own) #1252
Closed

felixweinberger mentioned this pull request Apr 2, 2026
feat(core): add custom request/notification handler API to Protocol #1846
Closed
9 tasks

coderabbitaiBot mentioned this pull request May 28, 2026
fix: 删除 edit tool 中的旧逻辑处理，现在已经不需要这些处理了，大模型够屌 claude-code-best/claude-code#1251
Merged

Navigation Menu

Uh oh!

fix: replace schema-based handlers with string method names - #1446

fix: replace schema-based handlers with string method names#1446
mattzcarey merged 7 commits into
mainfrom
feat/set-request-handler

mattzcarey commented Feb 2, 2026•
edited
Loading

Uh oh!

changeset-botBot commented Feb 2, 2026•
edited
Loading

Uh oh!

pkg-pr-newBot commented Feb 2, 2026•
edited
Loading

Uh oh!

Uh oh!

Uh oh!

felixweinbergerFeb 2, 2026

Uh oh!

mattzcareyFeb 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KKonstantinovFeb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

setRequestHandler and setNotificationHandler API Change

New Exports

Migration

Types of changes

Checklist

Uh oh!

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

Uh oh!

⚠️ No Changeset found

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixweinbergerFeb 2, 2026

Choose a reason for hiding this comment

Uh oh!

mattzcareyFeb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KKonstantinovFeb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattzcarey commented Feb 2, 2026•
edited
Loading

`setRequestHandler` and `setNotificationHandler` API Change

changeset-botBot commented Feb 2, 2026•
edited
Loading

pkg-pr-newBot commented Feb 2, 2026•
edited
Loading