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

Author: mattzcarey

CLAUDE.md

@@ -148,19 +148,19 @@ When a request arrives from the remote side:
     - Looks up handler in `_requestHandlers` map (keyed by method name)
     - Creates `RequestHandlerExtra` with `signal`, `sessionId`, `sendNotification`, `sendRequest`
     - Invokes handler, sends JSON-RPC response back via transport
-4. **Handler** was registered via `setRequestHandler(Schema, handler)`
+4. **Handler** was registered via `setRequestHandler('method', handler)`
 
 ### Handler Registration
 
 ```typescript
 // In Client (for server→client requests like sampling, elicitation)
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler('sampling/createMessage', async (request, extra) => {
   // Handle sampling request from server
   return { role: "assistant", content: {...}, model: "..." };
 });
 
 // In Server (for client→server requests like tools/call)
-server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+server.setRequestHandler('tools/call', async (request, extra) => {
   // Handle tool call from client
   return { content: [...] };
 });
@@ -207,7 +207,7 @@ const result = await server.createMessage({
 });
 
 // Client must have registered handler:
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler('sampling/createMessage', async (request, extra) => {
   // Client-side LLM call
   return { role: "assistant", content: {...} };
 });
@@ -218,7 +218,7 @@ client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
 ### Request Handler Registration (Low-Level Server)
 
 ```typescript
-server.setRequestHandler(SomeRequestSchema, async (request, extra) => {
+server.setRequestHandler('tools/call', async (request, extra) => {
     // extra contains sessionId, authInfo, sendNotification, etc.
     return {
         /* result */

docs/migration-SKILL.md

@@ -198,11 +198,50 @@ app.use(hostHeaderValidation(['example.com']));
 
 The server package now exports framework-agnostic alternatives: `validateHostHeader()`, `localhostAllowedHostnames()`, `hostHeaderValidationResponse()`.
 
-## 9. Client Behavioral Changes
+## 9. `setRequestHandler` / `setNotificationHandler` API
+
+The low-level handler registration methods now take a method string instead of a Zod schema.
+
+```typescript
+// v1: schema-based
+server.setRequestHandler(InitializeRequestSchema, async (request) => { ... });
+server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => { ... });
+
+// v2: method string
+server.setRequestHandler('initialize', async (request) => { ... });
+server.setNotificationHandler('notifications/message', (notification) => { ... });
+```
+
+Schema to method string mapping:
+
+| v1 Schema | v2 Method String |
+|-----------|-----------------|
+| `InitializeRequestSchema` | `'initialize'` |
+| `CallToolRequestSchema` | `'tools/call'` |
+| `ListToolsRequestSchema` | `'tools/list'` |
+| `ListPromptsRequestSchema` | `'prompts/list'` |
+| `GetPromptRequestSchema` | `'prompts/get'` |
+| `ListResourcesRequestSchema` | `'resources/list'` |
+| `ReadResourceRequestSchema` | `'resources/read'` |
+| `CreateMessageRequestSchema` | `'sampling/createMessage'` |
+| `ElicitRequestSchema` | `'elicitation/create'` |
+| `SetLevelRequestSchema` | `'logging/setLevel'` |
+| `PingRequestSchema` | `'ping'` |
+| `LoggingMessageNotificationSchema` | `'notifications/message'` |
+| `ToolListChangedNotificationSchema` | `'notifications/tools/list_changed'` |
+| `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
+| `PromptListChangedNotificationSchema` | `'notifications/prompts/list_changed'` |
+| `ProgressNotificationSchema` | `'notifications/progress'` |
+| `CancelledNotificationSchema` | `'notifications/cancelled'` |
+| `InitializedNotificationSchema` | `'notifications/initialized'` |
+
+Request/notification params remain fully typed. Remove unused schema imports after migration.
+
+## 10. Client Behavioral Changes
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, `listTools()` now return empty results when the server lacks the corresponding capability (instead of sending the request). Set `enforceStrictCapabilities: true` in `ClientOptions` to throw an error instead.
 
-## 10. Migration Steps (apply in this order)
+## 11. Migration Steps (apply in this order)
 
 1. Update `package.json`: `npm uninstall @modelcontextprotocol/sdk`, install the appropriate v2 packages
 2. Replace all imports from `@modelcontextprotocol/sdk/...` using the import mapping tables (sections 3-4), including `StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport`

docs/migration.md

@@ -237,6 +237,66 @@ app.use(hostHeaderValidation(['example.com']));
 
 Note: the v2 signature takes a plain `string[]` instead of an options object.
 
+### `setRequestHandler` and `setNotificationHandler` use method strings
+
+The low-level `setRequestHandler` and `setNotificationHandler` methods on `Client`, `Server`, and `Protocol` now take a method string instead of a Zod schema.
+
+**Before (v1):**
+
+```typescript
+import { Server, InitializeRequestSchema, LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/server/index.js';
+
+const server = new Server({ name: 'my-server', version: '1.0.0' });
+
+// Request handler with schema
+server.setRequestHandler(InitializeRequestSchema, async (request) => {
+  return { protocolVersion: '...', capabilities: {}, serverInfo: { name: '...', version: '...' } };
+});
+
+// Notification handler with schema
+server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+  console.log(notification.params.data);
+});
+```
+
+**After (v2):**
+
+```typescript
+import { Server } from '@modelcontextprotocol/server';
+
+const server = new Server({ name: 'my-server', version: '1.0.0' });
+
+// Request handler with method string
+server.setRequestHandler('initialize', async (request) => {
+  return { protocolVersion: '...', capabilities: {}, serverInfo: { name: '...', version: '...' } };
+});
+
+// Notification handler with method string
+server.setNotificationHandler('notifications/message', (notification) => {
+  console.log(notification.params.data);
+});
+```
+
+The request and notification parameters remain fully typed via `RequestTypeMap` and `NotificationTypeMap`. You no longer need to import the individual `*RequestSchema` or `*NotificationSchema` constants for handler registration.
+
+Common method string replacements:
+
+| Schema (v1) | Method string (v2) |
+|-------------|-------------------|
+| `InitializeRequestSchema` | `'initialize'` |
+| `CallToolRequestSchema` | `'tools/call'` |
+| `ListToolsRequestSchema` | `'tools/list'` |
+| `ListPromptsRequestSchema` | `'prompts/list'` |
+| `GetPromptRequestSchema` | `'prompts/get'` |
+| `ListResourcesRequestSchema` | `'resources/list'` |
+| `ReadResourceRequestSchema` | `'resources/read'` |
+| `CreateMessageRequestSchema` | `'sampling/createMessage'` |
+| `ElicitRequestSchema` | `'elicitation/create'` |
+| `LoggingMessageNotificationSchema` | `'notifications/message'` |
+| `ToolListChangedNotificationSchema` | `'notifications/tools/list_changed'` |
+| `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
+| `PromptListChangedNotificationSchema` | `'notifications/prompts/list_changed'` |
+
 ### Client list methods return empty results for missing capabilities
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, and `listTools()` now return empty results when the server didn't advertise the corresponding capability, instead of sending the request. This respects the MCP spec's capability negotiation.

examples/client/src/elicitationUrlExample.ts

@@ -21,8 +21,6 @@ import type {
 import {
     CallToolResultSchema,
     Client,
-    ElicitationCompleteNotificationSchema,
-    ElicitRequestSchema,
     ErrorCode,
     getDisplayName,
     ListToolsResultSchema,
@@ -560,10 +558,10 @@ async function connect(url?: string): Promise<void> {
     console.log('👤 Client created');
 
     // Set up elicitation request handler with proper validation
-    client.setRequestHandler(ElicitRequestSchema, elicitationRequestHandler);
+    client.setRequestHandler('elicitation/create', elicitationRequestHandler);
 
     // Set up notification handler for elicitation completion
-    client.setNotificationHandler(ElicitationCompleteNotificationSchema, notification => {
+    client.setNotificationHandler('notifications/elicitation/complete', notification => {
         const { elicitationId } = notification.params;
         const pending = pendingURLElicitations.get(elicitationId);
         if (pending) {

examples/client/src/multipleClientsParallel.ts

@@ -1,10 +1,5 @@
 import type { CallToolRequest, CallToolResult } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    LoggingMessageNotificationSchema,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Multiple Clients MCP Example
@@ -42,7 +37,7 @@ async function createAndRunClient(config: ClientConfig): Promise<{ id: string; r
     };
 
     // Set up client-specific notification handler
-    client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+    client.setNotificationHandler('notifications/message', notification => {
         console.log(`[${config.id}] Notification: ${notification.params.data}`);
     });
 

examples/client/src/parallelToolCallsClient.ts

@@ -1,11 +1,5 @@
 import type { CallToolResult, ListToolsRequest } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    ListToolsResultSchema,
-    LoggingMessageNotificationSchema,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, ListToolsResultSchema, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Parallel Tool Calls MCP Client
@@ -44,7 +38,7 @@ async function main(): Promise<void> {
         console.log('Successfully connected to MCP server');
 
         // Set up notification handler with caller identification
-        client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        client.setNotificationHandler('notifications/message', notification => {
             console.log(`Notification: ${notification.params.data}`);
         });
 

examples/client/src/simpleStreamableHttp.ts

@@ -12,18 +12,15 @@ import type {
 import {
     CallToolResultSchema,
     Client,
-    ElicitRequestSchema,
     ErrorCode,
     getDisplayName,
     GetPromptResultSchema,
     ListPromptsResultSchema,
     ListResourcesResultSchema,
     ListToolsResultSchema,
-    LoggingMessageNotificationSchema,
     McpError,
     ReadResourceResultSchema,
     RELATED_TASK_META_KEY,
-    ResourceListChangedNotificationSchema,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
 import { Ajv } from 'ajv';
@@ -271,7 +268,7 @@ async function connect(url?: string): Promise<void> {
         };
 
         // Set up elicitation request handler with proper validation
-        client.setRequestHandler(ElicitRequestSchema, async request => {
+        client.setRequestHandler('elicitation/create', async request => {
             if (request.params.mode !== 'form') {
                 throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
             }
@@ -496,14 +493,14 @@ async function connect(url?: string): Promise<void> {
         });
 
         // Set up notification handlers
-        client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        client.setNotificationHandler('notifications/message', notification => {
             notificationCount++;
             console.log(`\nNotification #${notificationCount}: ${notification.params.level} - ${notification.params.data}`);
             // Re-display the prompt
             process.stdout.write('> ');
         });
 
-        client.setNotificationHandler(ResourceListChangedNotificationSchema, async _ => {
+        client.setNotificationHandler('notifications/resources/list_changed', async _ => {
             console.log(`\nResource list changed notification received!`);
             try {
                 if (!client) {

examples/client/src/simpleTaskInteractiveClient.ts

@@ -10,15 +10,7 @@
 import { createInterface } from 'node:readline';
 
 import type { CreateMessageRequest, CreateMessageResult, TextContent } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    CreateMessageRequestSchema,
-    ElicitRequestSchema,
-    ErrorCode,
-    McpError,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, ErrorCode, McpError, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 // Create readline interface for user input
 const readline = createInterface({
@@ -43,7 +35,7 @@ async function elicitationCallback(params: {
     mode?: string;
     message: string;
     requestedSchema?: object;
-}): Promise<{ action: string; content?: Record<string, unknown> }> {
+}): Promise<{ action: 'accept' | 'cancel' | 'decline'; content?: Record<string, string | number | boolean | string[]> }> {
     console.log(`\n[Elicitation] Server asks: ${params.message}`);
 
     // Simple terminal prompt for y/n
@@ -102,15 +94,15 @@ async function run(url: string): Promise<void> {
     );
 
     // Set up elicitation request handler
-    client.setRequestHandler(ElicitRequestSchema, async request => {
+    client.setRequestHandler('elicitation/create', async request => {
         if (request.params.mode && request.params.mode !== 'form') {
             throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
         }
         return elicitationCallback(request.params);
     });
 
     // Set up sampling request handler
-    client.setRequestHandler(CreateMessageRequestSchema, async request => {
+    client.setRequestHandler('sampling/createMessage', async request => {
         return samplingCallback(request.params) as unknown as ReturnType<typeof samplingCallback>;
     });
 

examples/client/src/ssePollingClient.ts

@@ -12,12 +12,7 @@
  * Run with: pnpm tsx src/ssePollingClient.ts
  * Requires: ssePollingExample.ts server running on port 3001
  */
-import {
-    CallToolResultSchema,
-    Client,
-    LoggingMessageNotificationSchema,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 const SERVER_URL = 'http://localhost:3001/mcp';
 
@@ -60,7 +55,7 @@ async function main(): Promise<void> {
     });
 
     // Set up notification handler to receive progress updates
-    client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+    client.setNotificationHandler('notifications/message', notification => {
         const data = notification.params.data;
         console.log(`[Notification] ${data}`);
     });

examples/client/src/streamableHttpWithSseFallbackClient.ts

@@ -3,7 +3,6 @@ import {
     CallToolResultSchema,
     Client,
     ListToolsResultSchema,
-    LoggingMessageNotificationSchema,
     SSEClientTransport,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
@@ -39,7 +38,7 @@ async function main(): Promise<void> {
         transport = connection.transport;
 
         // Set up notification handler
-        client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        client.setNotificationHandler('notifications/message', notification => {
             console.log(`Notification: ${notification.params.level} - ${notification.params.data}`);
         });