v2 refactor!: remove Zod schema parameter from public-facing APIs (modelcontextprotocol#1606)

Author: KKonstantinov

docs/client.md

@@ -16,7 +16,6 @@ The examples below use these imports. Adjust based on which features and transpo
 import type { Prompt, Resource, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
-    CallToolResultSchema,
     Client,
     ClientCredentialsProvider,
     createMiddleware,
@@ -198,13 +197,16 @@ if (result.structuredContent) {
 Pass `onprogress` to receive incremental progress notifications from long-running tools. Use `resetTimeoutOnProgress` to keep the request alive while the server is actively reporting, and `maxTotalTimeout` as an absolute cap:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#callTool_progress"
-const result = await client.callTool({ name: 'long-operation', arguments: {} }, undefined, {
-    onprogress: ({ progress, total }) => {
-        console.log(`Progress: ${progress}/${total ?? '?'}`);
-    },
-    resetTimeoutOnProgress: true,
-    maxTotalTimeout: 600_000
-});
+const result = await client.callTool(
+    { name: 'long-operation', arguments: {} },
+    {
+        onprogress: ({ progress, total }: { progress: number; total?: number }) => {
+            console.log(`Progress: ${progress}/${total ?? '?'}`);
+        },
+        resetTimeoutOnProgress: true,
+        maxTotalTimeout: 600_000
+    }
+);
 console.log(result.content);
 ```
 
@@ -484,7 +486,6 @@ All requests have a 60-second default timeout. Pass a custom `timeout` in the op
 try {
     const result = await client.callTool(
         { name: 'slow-task', arguments: {} },
-        undefined,
         { timeout: 120_000 } // 2 minutes instead of the default 60 seconds
     );
     console.log(result.content);
@@ -523,7 +524,6 @@ const result = await client.request(
         method: 'tools/call',
         params: { name: 'long-running-task', arguments: {} }
     },
-    CallToolResultSchema,
     {
         resumptionToken: lastToken,
         onresumptiontoken: (token: string) => {

docs/migration-SKILL.md

@@ -203,7 +203,7 @@ import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/core';
 if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient) { ... }
 ```
 
-**Unchanged APIs** (only import paths changed): `Client` constructor and methods, `McpServer` constructor, `server.connect()`, `server.close()`, all client transports (`StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport`), `StdioServerTransport`, all Zod schemas, all callback return types.
+**Unchanged APIs** (only import paths changed): `Client` constructor and most methods, `McpServer` constructor, `server.connect()`, `server.close()`, all client transports (`StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport`), `StdioServerTransport`, all Zod schemas, all callback return types. Note: `callTool()` and `request()` signatures changed (schema parameter removed, see section 11).
 
 ## 6. McpServer API Changes
 
@@ -396,11 +396,39 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 | `ctx.mcpReq.elicitInput(params, options?)` | Elicit user input (form or URL) | `server.elicitInput(...)` from within handler |
 | `ctx.mcpReq.requestSampling(params, options?)` | Request LLM sampling from client | `server.createMessage(...)` from within handler |
 
-## 11. Client Behavioral Changes
+## 11. Schema parameter removed from `request()`, `send()`, and `callTool()`
+
+`Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` no longer take a Zod result schema argument. The SDK resolves the schema internally from the method name.
+
+```typescript
+// v1: schema required
+import { CallToolResultSchema, ElicitResultSchema } from '@modelcontextprotocol/sdk/types.js';
+const result = await client.request({ method: 'tools/call', params: { ... } }, CallToolResultSchema);
+const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } }, ElicitResultSchema);
+const tool = await client.callTool({ name: 'my-tool', arguments: {} }, CompatibilityCallToolResultSchema);
+
+// v2: no schema argument
+const result = await client.request({ method: 'tools/call', params: { ... } });
+const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } });
+const tool = await client.callTool({ name: 'my-tool', arguments: {} });
+```
+
+| v1 call | v2 call |
+|---------|---------|
+| `client.request(req, ResultSchema)` | `client.request(req)` |
+| `client.request(req, ResultSchema, options)` | `client.request(req, options)` |
+| `ctx.mcpReq.send(req, ResultSchema)` | `ctx.mcpReq.send(req)` |
+| `ctx.mcpReq.send(req, ResultSchema, options)` | `ctx.mcpReq.send(req, options)` |
+| `client.callTool(params, CompatibilityCallToolResultSchema)` | `client.callTool(params)` |
+| `client.callTool(params, schema, options)` | `client.callTool(params, options)` |
+
+Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
+
+## 12. 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.
 
-## 12. Runtime-Specific JSON Schema Validators (Enhancement)
+## 13. Runtime-Specific JSON Schema Validators (Enhancement)
 
 The SDK now auto-selects the appropriate JSON Schema validator based on runtime:
 - Node.js → `AjvJsonSchemaValidator` (no change from v1)
@@ -420,7 +448,7 @@ new McpServer({ name: 'server', version: '1.0.0' }, {});
 
 Access validators via `_shims` export: `import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';`
 
-## 13. Migration Steps (apply in this order)
+## 14. 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

@@ -337,6 +337,73 @@ Common method string replacements:
 | `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
 | `PromptListChangedNotificationSchema`   | `'notifications/prompts/list_changed'`   |
 
+### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
+
+The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
+
+**`client.request()` — Before (v1):**
+
+```typescript
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const result = await client.request(
+    { method: 'tools/call', params: { name: 'my-tool', arguments: {} } },
+    CallToolResultSchema
+);
+```
+
+**After (v2):**
+
+```typescript
+const result = await client.request(
+    { method: 'tools/call', params: { name: 'my-tool', arguments: {} } }
+);
+```
+
+**`ctx.mcpReq.send()` — Before (v1):**
+
+```typescript
+import { CreateMessageResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+server.setRequestHandler('tools/call', async (request, ctx) => {
+    const samplingResult = await ctx.mcpReq.send(
+        { method: 'sampling/createMessage', params: { messages: [...], maxTokens: 100 } },
+        CreateMessageResultSchema
+    );
+    return { content: [{ type: 'text', text: 'done' }] };
+});
+```
+
+**After (v2):**
+
+```typescript
+server.setRequestHandler('tools/call', async (request, ctx) => {
+    const samplingResult = await ctx.mcpReq.send(
+        { method: 'sampling/createMessage', params: { messages: [...], maxTokens: 100 } }
+    );
+    return { content: [{ type: 'text', text: 'done' }] };
+});
+```
+
+**`client.callTool()` — Before (v1):**
+
+```typescript
+import { CompatibilityCallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const result = await client.callTool(
+    { name: 'my-tool', arguments: {} },
+    CompatibilityCallToolResultSchema
+);
+```
+
+**After (v2):**
+
+```typescript
+const result = await client.callTool({ name: 'my-tool', arguments: {} });
+```
+
+The return type is now inferred from the method name via `ResultTypeMap`. For example, `client.request({ method: 'tools/call', ... })` returns `Promise<CallToolResult | CreateTaskResult>`.
+
 ### 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.
@@ -708,7 +775,7 @@ import { AjvJsonSchemaValidator, CfWorkerJsonSchemaValidator } from '@modelconte
 
 The following APIs are unchanged between v1 and v2 (only the import paths changed):
 
-- `Client` constructor and all client methods (`connect`, `callTool`, `listTools`, `listPrompts`, `listResources`, `readResource`, etc.)
+- `Client` constructor and most client methods (`connect`, `listTools`, `listPrompts`, `listResources`, `readResource`, etc.) — note: `callTool()` signature changed (schema parameter removed)
 - `McpServer` constructor, `server.connect(transport)`, `server.close()`
 - `Server` (low-level) constructor and all methods
 - `StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport` constructors and options

examples/client/src/clientGuide.examples.ts

@@ -11,7 +11,6 @@
 import type { Prompt, Resource, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
-    CallToolResultSchema,
     Client,
     ClientCredentialsProvider,
     createMiddleware,
@@ -181,13 +180,16 @@ async function callTool_structuredOutput(client: Client) {
 /** Example: Track progress of a long-running tool call. */
 async function callTool_progress(client: Client) {
     //#region callTool_progress
-    const result = await client.callTool({ name: 'long-operation', arguments: {} }, undefined, {
-        onprogress: ({ progress, total }) => {
-            console.log(`Progress: ${progress}/${total ?? '?'}`);
-        },
-        resetTimeoutOnProgress: true,
-        maxTotalTimeout: 600_000
-    });
+    const result = await client.callTool(
+        { name: 'long-operation', arguments: {} },
+        {
+            onprogress: ({ progress, total }: { progress: number; total?: number }) => {
+                console.log(`Progress: ${progress}/${total ?? '?'}`);
+            },
+            resetTimeoutOnProgress: true,
+            maxTotalTimeout: 600_000
+        }
+    );
     console.log(result.content);
     //#endregion callTool_progress
 }
@@ -450,7 +452,6 @@ async function errorHandling_timeout(client: Client) {
     try {
         const result = await client.callTool(
             { name: 'slow-task', arguments: {} },
-            undefined,
             { timeout: 120_000 } // 2 minutes instead of the default 60 seconds
         );
         console.log(result.content);
@@ -492,7 +493,6 @@ async function resumptionToken_basic(client: Client) {
             method: 'tools/call',
             params: { name: 'long-running-task', arguments: {} }
         },
-        CallToolResultSchema,
         {
             resumptionToken: lastToken,
             onresumptiontoken: (token: string) => {

examples/client/src/elicitationUrlExample.ts

@@ -10,6 +10,7 @@ import { createInterface } from 'node:readline';
 
 import type {
     CallToolRequest,
+    CallToolResult,
     ElicitRequest,
     ElicitRequestURLParams,
     ElicitResult,
@@ -18,10 +19,8 @@ import type {
     ResourceLink
 } from '@modelcontextprotocol/client';
 import {
-    CallToolResultSchema,
     Client,
     getDisplayName,
-    ListToolsResultSchema,
     ProtocolError,
     ProtocolErrorCode,
     StreamableHTTPClientTransport,
@@ -666,7 +665,7 @@ async function listTools(): Promise<void> {
             method: 'tools/list',
             params: {}
         };
-        const toolsResult = await client.request(toolsRequest, ListToolsResultSchema);
+        const toolsResult = await client.request(toolsRequest);
 
         console.log('Available tools:');
         if (toolsResult.tools.length === 0) {
@@ -697,7 +696,7 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<vo
         };
 
         console.log(`Calling tool '${name}' with args:`, args);
-        const result = await client.request(request, CallToolResultSchema);
+        const result = (await client.request(request)) as CallToolResult;
 
         console.log('Tool result:');
         const resourceLinks: ResourceLink[] = [];

examples/client/src/multipleClientsParallel.ts

@@ -1,5 +1,5 @@
 import type { CallToolRequest, CallToolResult } from '@modelcontextprotocol/client';
-import { CallToolResultSchema, Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Multiple Clients MCP Example
@@ -60,7 +60,7 @@ async function createAndRunClient(config: ClientConfig): Promise<{ id: string; r
             }
         };
 
-        const result = await client.request(toolRequest, CallToolResultSchema);
+        const result = (await client.request(toolRequest)) as CallToolResult;
         console.log(`[${config.id}] Tool call completed`);
 
         // Keep the connection open for a bit to receive notifications

examples/client/src/parallelToolCallsClient.ts

@@ -1,5 +1,5 @@
-import type { CallToolResult, ListToolsRequest } from '@modelcontextprotocol/client';
-import { CallToolResultSchema, Client, ListToolsResultSchema, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import type { CallToolRequest, CallToolResult, ListToolsRequest } from '@modelcontextprotocol/client';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Parallel Tool Calls MCP Client
@@ -86,7 +86,7 @@ async function listTools(client: Client): Promise<void> {
             method: 'tools/list',
             params: {}
         };
-        const toolsResult = await client.request(toolsRequest, ListToolsResultSchema);
+        const toolsResult = await client.request(toolsRequest);
 
         console.log('Available tools:');
         if (toolsResult.tools.length === 0) {
@@ -108,7 +108,7 @@ async function listTools(client: Client): Promise<void> {
 async function startParallelNotificationTools(client: Client): Promise<Record<string, CallToolResult>> {
     try {
         // Define multiple tool calls with different configurations
-        const toolCalls = [
+        const toolCalls: Array<{ caller: string; request: CallToolRequest }> = [
             {
                 caller: 'fast-notifier',
                 request: {
@@ -159,7 +159,7 @@ async function startParallelNotificationTools(client: Client): Promise<Record<st
         const toolPromises = toolCalls.map(({ caller, request }) => {
             console.log(`Starting tool call for ${caller}...`);
             return client
-                .request(request, CallToolResultSchema)
+                .request(request)
                 .then(result => ({ caller, result }))
                 .catch(error => {
                     console.error(`Error in tool call for ${caller}:`, error);
@@ -173,7 +173,7 @@ async function startParallelNotificationTools(client: Client): Promise<Record<st
         // Organize results by caller
         const resultsByTool: Record<string, CallToolResult> = {};
         for (const { caller, result } of results) {
-            resultsByTool[caller] = result;
+            resultsByTool[caller] = result as CallToolResult;
         }
 
         return resultsByTool;

examples/client/src/simpleOAuthClient.ts

@@ -4,14 +4,8 @@ import { createServer } from 'node:http';
 import { createInterface } from 'node:readline';
 import { URL } from 'node:url';
 
-import type { CallToolRequest, ListToolsRequest, OAuthClientMetadata } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    ListToolsResultSchema,
-    StreamableHTTPClientTransport,
-    UnauthorizedError
-} from '@modelcontextprotocol/client';
+import type { CallToolRequest, CallToolResult, ListToolsRequest, OAuthClientMetadata } from '@modelcontextprotocol/client';
+import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
 import open from 'open';
 
 import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider.js';
@@ -262,7 +256,7 @@ class InteractiveOAuthClient {
                 params: {}
             };
 
-            const result = await this.client.request(request, ListToolsResultSchema);
+            const result = await this.client.request(request);
 
             if (result.tools && result.tools.length > 0) {
                 console.log('\n📋 Available tools:');
@@ -320,7 +314,7 @@ class InteractiveOAuthClient {
                 }
             };
 
-            const result = await this.client.request(request, CallToolResultSchema);
+            const result = (await this.client.request(request)) as CallToolResult;
 
             console.log(`\n🔧 Tool '${toolName}' result:`);
             if (result.content) {
@@ -404,7 +398,8 @@ class InteractiveOAuthClient {
 
                     case 'result': {
                         console.log('✓ Completed!');
-                        for (const content of message.result.content) {
+                        const toolResult = message.result as CallToolResult;
+                        for (const content of toolResult.content) {
                             if (content.type === 'text') {
                                 console.log(content.text);
                             } else {