refactor(server)!: remove getTask/getTaskResult from ToolTaskHandler

These handlers were defined on the ToolTaskHandler interface but never
invoked by the SDK. Three code paths bypassed them and called TaskStore
directly:

- TaskManager.handleGetTask
- TaskManager.handleGetTaskPayload
- McpServer.handleAutomaticTaskPolling

Every test and example implementation was pure boilerplate delegation
to ctx.task.store. Rather than wire them up (which would require
in-memory taskId→tool mapping that doesn't survive restarts or
multi-instance deployments), this removes them.

The TaskStore interface remains the pluggable extension point for
custom task retrieval.

Also adds an isToolTaskHandler type guard and uses it in place of
inline 'createTask' in checks.

BREAKING CHANGE: ToolTaskHandler.getTask and ToolTaskHandler.getTaskResult
have been removed. Delete these methods from your registerToolTask
handlers. If you need custom task retrieval, implement a custom
TaskStore.

Closes #1332

Co-authored-by: Luca Chang <lucalc@amazon.com>

Author: felixweinberger

.changeset/remove-tooltask-get-handlers.md

@@ -0,0 +1,14 @@
+---
+"@modelcontextprotocol/server": minor
+---
+
+Remove `getTask` and `getTaskResult` from `ToolTaskHandler`
+
+**Breaking changes (experimental API):**
+
+- `ToolTaskHandler` now only defines `createTask`. The `getTask` and `getTaskResult` handlers have been removed.
+- `TaskRequestHandler` type has been removed.
+
+These handlers were never invoked by the SDK — `tasks/get` and `tasks/result` requests were always served directly from the configured `TaskStore`, bypassing the user's handlers. Rather than wire them up (which would require in-memory taskId→tool mapping that doesn't survive restarts), we've removed them.
+
+**Migration:** Delete your `getTask` and `getTaskResult` implementations. If you need to customize task retrieval, implement a custom `TaskStore` instead — it's the pluggable interface that `tasks/get` and `tasks/result` consult.

docs/migration-SKILL.md

@@ -96,6 +96,9 @@ Notes:
 | `ErrorCode.RequestTimeout`               | `SdkErrorCode.RequestTimeout`                            |
 | `ErrorCode.ConnectionClosed`             | `SdkErrorCode.ConnectionClosed`                          |
 | `StreamableHTTPError`                    | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
+| `TaskRequestHandler`                     | REMOVED (no replacement)                                 |
+| `ToolTaskHandler.getTask`                | REMOVED (use custom `TaskStore` instead)                 |
+| `ToolTaskHandler.getTaskResult`          | REMOVED (use custom `TaskStore` instead)                 |
 
 All other symbols from `@modelcontextprotocol/sdk/types.js` retain their original names (e.g., `CallToolResultSchema`, `ListToolsResultSchema`, etc.).
 

docs/migration.md

@@ -478,6 +478,38 @@ import { JSONRPCError, ResourceReference, isJSONRPCError } from '@modelcontextpr
 import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse } from '@modelcontextprotocol/server';
 ```
 
+### `ToolTaskHandler.getTask` and `getTaskResult` removed (experimental)
+
+The `getTask` and `getTaskResult` methods have been removed from the experimental `ToolTaskHandler` interface. These handlers were never invoked by the SDK — `tasks/get` and `tasks/result` requests are served directly from the configured `TaskStore`.
+
+**Before:**
+
+```typescript
+server.experimental.tasks.registerToolTask('long-task', config, {
+    createTask: async (args, ctx) => {
+        const task = await ctx.task.store.createTask({ ttl: 60_000 });
+        startBackgroundWork(task.taskId, args);
+        return { task };
+    },
+    getTask: async (ctx) => ctx.task.store.getTask(ctx.task.id),
+    getTaskResult: async (ctx) => ctx.task.store.getTaskResult(ctx.task.id)
+});
+```
+
+**After:**
+
+```typescript
+server.experimental.tasks.registerToolTask('long-task', config, {
+    createTask: async (args, ctx) => {
+        const task = await ctx.task.store.createTask({ ttl: 60_000 });
+        startBackgroundWork(task.taskId, args);
+        return { task };
+    }
+});
+```
+
+If you need to customize task retrieval, implement a custom `TaskStore`.
+
 ### Request handler context types
 
 The `RequestHandlerExtra` type has been replaced with a structured context type hierarchy using nested groups:

examples/server/src/simpleStreamableHttp.ts

@@ -480,13 +480,6 @@ const getServer = () => {
                 return {
                     task
                 };
-            },
-            async getTask(_args, ctx) {
-                return await ctx.task.store.getTask(ctx.task.id);
-            },
-            async getTaskResult(_args, ctx) {
-                const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                return result as CallToolResult;
             }
         }
     );
@@ -588,13 +581,6 @@ const getServer = () => {
                 })();
 
                 return { task };
-            },
-            async getTask(_args, ctx) {
-                return await ctx.task.store.getTask(ctx.task.id);
-            },
-            async getTaskResult(_args, ctx) {
-                const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                return result as CallToolResult;
             }
         }
     );

packages/server/src/experimental/tasks/interfaces.ts

@@ -3,17 +3,9 @@
  * WARNING: These APIs are experimental and may change without notice.
  */
 
-import type {
-    CallToolResult,
-    CreateTaskResult,
-    CreateTaskServerContext,
-    GetTaskResult,
-    Result,
-    StandardSchemaWithJSON,
-    TaskServerContext
-} from '@modelcontextprotocol/core';
+import type { CreateTaskResult, CreateTaskServerContext, Result, StandardSchemaWithJSON } from '@modelcontextprotocol/core';
 
-import type { BaseToolCallback } from '../../server/mcp.js';
+import type { AnyToolHandler, BaseToolCallback } from '../../server/mcp.js';
 
 // ============================================================================
 // Task Handler Types (for registerToolTask)
@@ -28,21 +20,12 @@ export type CreateTaskRequestHandler<
     Args extends StandardSchemaWithJSON | undefined = undefined
 > = BaseToolCallback<SendResultT, CreateTaskServerContext, Args>;
 
-/**
- * Handler for task operations (`get`, `getResult`).
- * @experimental
- */
-export type TaskRequestHandler<SendResultT extends Result, Args extends StandardSchemaWithJSON | undefined = undefined> = BaseToolCallback<
-    SendResultT,
-    TaskServerContext,
-    Args
->;
-
 /**
  * Interface for task-based tool handlers.
  *
- * Task-based tools split a long-running operation into three phases:
- * `createTask`, `getTask`, and `getTaskResult`.
+ * Task-based tools create a task on `tools/call` and let the SDK's {@linkcode TaskStore}
+ * handle subsequent `tasks/get` and `tasks/result` requests. To customize task retrieval
+ * behavior, implement a custom {@linkcode TaskStore}.
  *
  * @see {@linkcode @modelcontextprotocol/server!experimental/tasks/mcpServer.ExperimentalMcpServerTasks#registerToolTask | registerToolTask} for registration.
  * @experimental
@@ -55,12 +38,14 @@ export interface ToolTaskHandler<Args extends StandardSchemaWithJSON | undefined
      * background work, and returns the task object.
      */
     createTask: CreateTaskRequestHandler<CreateTaskResult, Args>;
-    /**
-     * Handler for `tasks/get` requests.
-     */
-    getTask: TaskRequestHandler<GetTaskResult, Args>;
-    /**
-     * Handler for `tasks/result` requests.
-     */
-    getTaskResult: TaskRequestHandler<CallToolResult, Args>;
+}
+
+/**
+ * Type guard for {@linkcode ToolTaskHandler}.
+ * @experimental
+ */
+export function isToolTaskHandler(
+    handler: AnyToolHandler<StandardSchemaWithJSON | undefined>
+): handler is ToolTaskHandler<StandardSchemaWithJSON | undefined> {
+    return 'createTask' in handler;
 }

packages/server/src/experimental/tasks/mcpServer.ts

@@ -45,8 +45,9 @@ export class ExperimentalMcpServerTasks {
      * Registers a task-based tool with a config object and handler.
      *
      * Task-based tools support long-running operations that can be polled for status
-     * and results. The handler must implement {@linkcode ToolTaskHandler.createTask | createTask}, {@linkcode ToolTaskHandler.getTask | getTask}, and {@linkcode ToolTaskHandler.getTaskResult | getTaskResult}
-     * methods.
+     * and results. The handler implements {@linkcode ToolTaskHandler.createTask | createTask}
+     * to start the task; subsequent `tasks/get` and `tasks/result` requests are served
+     * from the configured {@linkcode TaskStore}.
      *
      * @example
      * ```typescript
@@ -59,19 +60,13 @@ export class ExperimentalMcpServerTasks {
      *     const task = await ctx.task.store.createTask({ ttl: 300000 });
      *     startBackgroundWork(task.taskId, args);
      *     return { task };
-     *   },
-     *   getTask: async (args, ctx) => {
-     *     return ctx.task.store.getTask(ctx.task.id);
-     *   },
-     *   getTaskResult: async (args, ctx) => {
-     *     return ctx.task.store.getTaskResult(ctx.task.id);
      *   }
      * });
      * ```
      *
      * @param name - The tool name
      * @param config - Tool configuration (description, schemas, etc.)
-     * @param handler - Task handler with {@linkcode ToolTaskHandler.createTask | createTask}, {@linkcode ToolTaskHandler.getTask | getTask}, {@linkcode ToolTaskHandler.getTaskResult | getTaskResult} methods
+     * @param handler - Task handler with {@linkcode ToolTaskHandler.createTask | createTask}
      * @returns {@linkcode server/mcp.RegisteredTool | RegisteredTool} for managing the tool's lifecycle
      *
      * @experimental

packages/server/src/index.ts

@@ -39,7 +39,8 @@ export type {
 export { WebStandardStreamableHTTPServerTransport } from './server/streamableHttp.js';
 
 // experimental exports
-export type { CreateTaskRequestHandler, TaskRequestHandler, ToolTaskHandler } from './experimental/tasks/interfaces.js';
+export type { CreateTaskRequestHandler, ToolTaskHandler } from './experimental/tasks/interfaces.js';
+export { isToolTaskHandler } from './experimental/tasks/interfaces.js';
 export { ExperimentalMcpServerTasks } from './experimental/tasks/mcpServer.js';
 export { ExperimentalServerTasks } from './experimental/tasks/server.js';
 

packages/server/src/server/mcp.ts

@@ -40,6 +40,7 @@ import {
 } from '@modelcontextprotocol/core';
 
 import type { ToolTaskHandler } from '../experimental/tasks/interfaces.js';
+import { isToolTaskHandler } from '../experimental/tasks/interfaces.js';
 import { ExperimentalMcpServerTasks } from '../experimental/tasks/mcpServer.js';
 import { getCompleter, isCompletable } from './completable.js';
 import type { ServerOptions } from './server.js';
@@ -170,7 +171,7 @@ export class McpServer {
             try {
                 const isTaskRequest = !!request.params.task;
                 const taskSupport = tool.execution?.taskSupport;
-                const isTaskHandler = 'createTask' in (tool.handler as AnyToolHandler<StandardSchemaWithJSON>);
+                const isTaskHandler = isToolTaskHandler(tool.handler);
 
                 // Validate task hint configuration
                 if ((taskSupport === 'required' || taskSupport === 'optional') && !isTaskHandler) {
@@ -325,14 +326,9 @@ export class McpServer {
 
         while (task.status !== 'completed' && task.status !== 'failed' && task.status !== 'cancelled') {
             await new Promise(resolve => setTimeout(resolve, pollInterval));
-            const updatedTask = await ctx.task.store.getTask(taskId);
-            if (!updatedTask) {
-                throw new ProtocolError(ProtocolErrorCode.InternalError, `Task ${taskId} not found during polling`);
-            }
-            task = updatedTask;
+            task = await ctx.task.store.getTask(taskId);
         }
 
-        // Return the final result
         return (await ctx.task.store.getTaskResult(taskId)) as CallToolResult;
     }
 
@@ -1120,9 +1116,7 @@ function createToolExecutor(
     inputSchema: StandardSchemaWithJSON | undefined,
     handler: AnyToolHandler<StandardSchemaWithJSON | undefined>
 ): ToolExecutor {
-    const isTaskHandler = 'createTask' in handler;
-
-    if (isTaskHandler) {
+    if (isToolTaskHandler(handler)) {
         const taskHandler = handler as TaskHandlerInternal;
         return async (args, ctx) => {
             if (!ctx.task?.store) {

test/integration/test/client/client.test.ts

@@ -2331,17 +2331,6 @@ describe('Task-based execution', () => {
                         await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                         return { task };
-                    },
-                    async getTask(_args, ctx) {
-                        const task = await ctx.task.store.getTask(ctx.task.id);
-                        if (!task) {
-                            throw new Error(`Task ${ctx.task.id} not found`);
-                        }
-                        return task;
-                    },
-                    async getTaskResult(_args, ctx) {
-                        const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                        return result as { content: Array<{ type: 'text'; text: string }> };
                     }
                 }
             );
@@ -2414,17 +2403,6 @@ describe('Task-based execution', () => {
                         await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                         return { task };
-                    },
-                    async getTask(_args, ctx) {
-                        const task = await ctx.task.store.getTask(ctx.task.id);
-                        if (!task) {
-                            throw new Error(`Task ${ctx.task.id} not found`);
-                        }
-                        return task;
-                    },
-                    async getTaskResult(_args, ctx) {
-                        const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                        return result as { content: Array<{ type: 'text'; text: string }> };
                     }
                 }
             );
@@ -2498,17 +2476,6 @@ describe('Task-based execution', () => {
                         await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                         return { task };
-                    },
-                    async getTask(_args, ctx) {
-                        const task = await ctx.task.store.getTask(ctx.task.id);
-                        if (!task) {
-                            throw new Error(`Task ${ctx.task.id} not found`);
-                        }
-                        return task;
-                    },
-                    async getTaskResult(_args, ctx) {
-                        const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                        return result as { content: Array<{ type: 'text'; text: string }> };
                     }
                 }
             );
@@ -2586,17 +2553,6 @@ describe('Task-based execution', () => {
                         await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                         return { task };
-                    },
-                    async getTask(_args, ctx) {
-                        const task = await ctx.task.store.getTask(ctx.task.id);
-                        if (!task) {
-                            throw new Error(`Task ${ctx.task.id} not found`);
-                        }
-                        return task;
-                    },
-                    async getTaskResult(_args, ctx) {
-                        const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                        return result as { content: Array<{ type: 'text'; text: string }> };
                     }
                 }
             );
@@ -3078,17 +3034,6 @@ describe('Task-based execution', () => {
                     await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                     return { task };
-                },
-                async getTask(_args, ctx) {
-                    const task = await ctx.task.store.getTask(ctx.task.id);
-                    if (!task) {
-                        throw new Error(`Task ${ctx.task.id} not found`);
-                    }
-                    return task;
-                },
-                async getTaskResult(_args, ctx) {
-                    const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                    return result as { content: Array<{ type: 'text'; text: string }> };
                 }
             }
         );
@@ -3353,17 +3298,6 @@ test('should respect server task capabilities', async () => {
                 await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
 
                 return { task };
-            },
-            async getTask(_args, ctx) {
-                const task = await ctx.task.store.getTask(ctx.task.id);
-                if (!task) {
-                    throw new Error(`Task ${ctx.task.id} not found`);
-                }
-                return task;
-            },
-            async getTaskResult(_args, ctx) {
-                const result = await ctx.task.store.getTaskResult(ctx.task.id);
-                return result as { content: Array<{ type: 'text'; text: string }> };
             }
         }
     );