registerToolTask handlers receive wrong arguments when inputSchema is omitted

[mattzcarey]

Summary

When using registerToolTask without providing an inputSchema, handlers that expect two arguments (args, extra) receive extra as undefined because the executor only passes one argument.

Reproduction

server.experimental.tasks.registerToolTask(
    'test-tool',
    {
        description: 'A test tool'
        // Note: no inputSchema provided
    },
    {
        async createTask(_args, extra) {
            // extra is undefined here!
            const task = await extra.taskStore.createTask({ ttl: extra.taskRequestedTtl });
            // TypeError: Cannot read properties of undefined (reading 'taskStore')
            return { task };
        },
        // ...
    }
);

Root Cause

In createToolExecutor (packages/server/src/server/mcp.ts), when inputSchema is undefined, the executor calls the handler with only one argument:

if (!inputSchema) {
    return handler(extra);  // Only passes extra as first argument
}
// vs when inputSchema is defined:
return handler(parsedArgs, extra);  // Passes both args and extra

When a handler is defined as async createTask(_args, extra), JavaScript will:

• With handler(extra): _args = extra, extra = undefined
• With handler(parsedArgs, extra): _args = parsedArgs, extra = extra ✓

Workaround

Always provide inputSchema: z.object({}) even for tools that don't require arguments:

server.experimental.tasks.registerToolTask(
    'test-tool',
    {
        description: 'A test tool',
        inputSchema: z.object({})  // Required for two-argument handlers
    },
    // ...
);

Potential Solutions

1. Always pass two arguments: Change the executor to always call handler({}, extra) when inputSchema is undefined
2. TypeScript enforcement: Use function overloads or conditional types to enforce that handlers without inputSchema must use single-argument signature
3. Documentation: Document that inputSchema must be provided when using two-argument handler signatures

Environment

• SDK version: v2 (drop-zod-v3-support branch)
• Affects: registerToolTask in experimental tasks API

[mcp-claude]

bug confirmed on main (b8886e7). not present on v1.x — tasks API is v2-only.

root cause: createToolExecutor (packages/server/src/server/mcp.ts:1141-1142) calls taskHandler.createTask(taskCtx) when inputSchema is undefined, so any handler written as (_args, extra) receives extra = undefined. the typescript overloads catch this at compile time for ts users, but js users and anyone who bypasses types hit it silently at runtime.

workaround: always provide inputSchema: z.object({}) even for tools that take no arguments, or write the handler as single-arg (ctx) with no inputSchema.

repro script, output, and code path

repro.mjs (run with node repro.mjs after cd packages/server && pnpm build && cd ../..):

import { McpServer } from './packages/server/dist/index.mjs';

const fakeTaskStore = {
    createTask: async (opts) => ({ taskId: 'test-task-id', status: 'pending', ttl: opts?.ttl ?? 300 }),
};
function buildCtx() {
    return { signal: new AbortController().signal, task: { store: fakeTaskStore, requestedTtl: 600 } };
}
function getExecutor(server, name) {
    return server._registeredTools?.[name]?.executor;
}

// No inputSchema, two-arg handler — the issue scenario
const server = new McpServer({ name: 'test', version: '0.0.0' });
let argsCaptured, extraCaptured;
server.experimental.tasks.registerToolTask(
    'no-schema-2arg',
    { description: 'two-arg handler without schema' },
    {
        async createTask(_args, extra) { argsCaptured = _args; extraCaptured = extra; return { task: { taskId: 'x', status: 'pending' } }; },
        async getTask(_args, extra) { return { task: { taskId: 'x', status: 'pending' } }; },
        async getTaskResult(_args, extra) { return { content: [] }; },
    }
);
await getExecutor(server, 'no-schema-2arg')({}, buildCtx());
console.log('argsCaptured has task.store:', !!argsCaptured?.task?.store);  // true — got ctx object
console.log('extraCaptured:', extraCaptured);                               // undefined — BUG

output:

argsCaptured has task.store: true   ← _args received the ctx object
extraCaptured: undefined            ← BUG: extra is undefined

code path:
createToolExecutor (mcp.ts:1129-1143):

const isTaskHandler = 'createTask' in handler;
if (isTaskHandler) {
    const taskHandler = handler as TaskHandlerInternal;
    return async (args, ctx) => {
        // ...
        const taskCtx = { ...ctx, task: { store: ctx.task.store, requestedTtl: ctx.task?.requestedTtl } };
        if (inputSchema) {
            return taskHandler.createTask(args, taskCtx);   // two args ✓
        }
        // When no inputSchema, call with just ctx — LINE 1142
        return (taskHandler.createTask as (ctx: CreateTaskServerContext) => ...)(taskCtx);
        //                                                                        ^ only one arg
    };
}

suggested fix

// packages/server/src/server/mcp.ts
             const taskCtx: CreateTaskServerContext = { ...ctx, task: { store: ctx.task.store, requestedTtl: ctx.task?.requestedTtl } };
-            if (inputSchema) {
-                return taskHandler.createTask(args, taskCtx);
-            }
-            // When no inputSchema, call with just ctx (the handler expects (ctx) signature)
-            return (taskHandler.createTask as (ctx: CreateTaskServerContext) => CreateTaskResult | Promise<CreateTaskResult>)(taskCtx);
+            return taskHandler.createTask(args, taskCtx);

// packages/server/src/experimental/tasks/interfaces.ts
 export type CreateTaskRequestHandler<
     SendResultT extends Result,
     Args extends StandardSchemaWithJSON | undefined = undefined
-> = BaseToolCallback<SendResultT, CreateTaskServerContext, Args>;
+> = Args extends StandardSchemaWithJSON
+    ? (args: StandardSchemaWithJSON.InferOutput<Args>, ctx: CreateTaskServerContext) => SendResultT | Promise<SendResultT>
+    : (_args: undefined, ctx: CreateTaskServerContext) => SendResultT | Promise<SendResultT>;

this makes createTask always two-arg. existing no-schema handlers that used the old single-arg async ctx => {} form need to be updated to async (_args, ctx) => {}.

test to verify: register a no-schema task tool with a two-arg createTask(_args, extra), call the executor, and assert extra (not _args) holds the CreateTaskServerContext with task.store.