MCP Server Framework - v1.0.0
    Preparing search index...

    Interface TaskToolDefinition<TInput>Experimental

    Task tool definition — a tool with asynchronous task execution support.

    Task tools enable long-running operations that report progress asynchronously. Instead of blocking the tool call until completion, the client receives a task ID and can poll for status updates and results.

    Registered via defineTask() which auto-registers in globalTaskToolRegistry. The framework uses the SDK's experimental.tasks.registerToolTask() internally.

    import { defineTask, text, z } from 'mcp-server-framework';

    export const longRunningTool = defineTask({
      name: 'long_computation',
      description: 'Perform a long computation',
      input: z.object({ data: z.string() }),
      taskSupport: 'required',
      taskHandler: {
        createTask: async (args, ctx) => {
          const task = await ctx.taskStore.createTask({ ttl: 300_000 });
          startBackgroundWork(task.taskId, args);
          return { task };
        },
        getTask: async (_args, ctx) => ctx.taskStore.getTask(ctx.taskId),
        getTaskResult: async (_args, ctx) => ctx.taskStore.getTaskResult(ctx.taskId),
      },
    });
    interface TaskToolDefinition<TInput extends ZodTypeAny = ZodTypeAny> {
        _meta?: Record<string, unknown>;
        annotations?: ToolAnnotations;
        description: string;
        input: TInput;
        name: string;
        requiredScopes?: readonly string[];
        taskHandler: TaskToolHandler<TInput>;
        taskSupport?: TaskSupport;
    }

    Type Parameters

    • TInput extends ZodTypeAny = ZodTypeAny

      Zod schema type for input validation (default: any Zod type)

      MCP Tasks is an experimental SDK feature

    Index

    Properties

    _meta? annotations? description input name requiredScopes? taskHandler taskSupport?

    Properties

    Optional Readonly Experimental_meta

    _meta?: Record<string, unknown>

    Optional metadata passed through to the MCP SDK.

    annotations?: ToolAnnotations

    Optional annotations providing hints about tool behavior.

    ToolAnnotations

    description: string

    Human-readable description shown to LLM

    input: TInput

    Zod schema for input validation

    name: string

    Unique tool name (e.g., 'long_computation')

    requiredScopes?: readonly string[]

    Scopes required to execute this task tool (RBAC).

    When set, the framework checks authInfo.scopes BEFORE the task handler executes. All listed scopes must be present (AND logic). If the check fails, a 403 Forbidden error is returned.

    Omit or set to undefined for task tools accessible to any authenticated user.

    taskHandler: TaskToolHandler<TInput>

    Task handler with create/get/getResult methods.

    These three methods implement the task lifecycle:

    1. createTask — Start the background work
    2. getTask — Report current status
    3. getTaskResult — Return the final result
    taskSupport?: TaskSupport

    Task support level.

    • 'optional' — Tool can be called normally or as a task
    • 'required' — Tool MUST be called as a task
    'required'

    Settings

    Member Visibility

    On This Page

    Properties