feat: Background tasks — async long-running operations

[superWorldSavior]

Motivation

Some MCP tools trigger operations that take seconds or minutes (database migrations, report generation, batch processing, API calls with retries). Today, these block the tool call and risk timeouts. The agent sits waiting, the user sees nothing.

We need a pattern where a tool can kick off a task, return immediately, and let the agent poll or be notified when it's done.

Proposal

Registration

server.registerTool(
  {
    name: "generate_report",
    description: "Generate monthly sales report (takes ~30s)",
    inputSchema: {
      type: "object",
      properties: { month: { type: "string" } },
      required: ["month"],
    },
    background: true, // marks this as a background-capable tool
  },
  async ({ month }, ctx) => {
    const taskId = ctx.background.start(async (progress) => {
      progress.update("Fetching data...", 0.2);
      const data = await fetchSalesData(month);
      progress.update("Building report...", 0.6);
      const report = await buildReport(data);
      progress.update("Done", 1.0);
      return report;
    });

    return { taskId, status: "running" };
  },
);

Built-in task management tools

The framework auto-registers companion tools when background tasks are enabled:

• task_status — check progress of a running task ({ taskId } → { status, progress, message })
• task_result — retrieve the result of a completed task
• task_cancel — cancel a running task (if supported)

Behavior

• Task state is scoped to the session (or server, configurable)
• Progress updates are optional but help the agent communicate status to the user
• Completed task results are cached for a configurable TTL
• Works with the existing backpressure system (background tasks don't count toward concurrent limit once started)

Use cases

• Report generation: agent triggers, checks back in 30s
• Batch operations: bulk update 500 records, track progress
• External API calls: webhook-style integrations with slow third parties
• Data exports: CSV/PDF generation

Prior art

• FastMCP 3.0 background tasks via Docket integration (SEP-1686)
• Job queue patterns (Bull, Celery, Temporal)

Scope

• background option on tool registration
• ctx.background.start() API with progress callback
• Auto-registered task_status / task_result / task_cancel tools
• Session-scoped task storage (in-memory default, pluggable)
• TTL / cleanup for completed tasks
• Documentation + examples
• Tests