converse-mcp-server 4.8.5 → 4.9.0

package/README.md

@@ -98,6 +98,7 @@ Once installed, you can:
 
 - **Chat with a specific model**: Ask Claude to use the chat tool with your preferred model
 - **Get consensus**: Ask Claude to use the chat tool with `mode: "consensus"` when you need multiple perspectives
+- **Keep working while models think**: In Claude Code v2.1.304+, chat calls run as [MCP tasks](docs/API.md#mcp-tasks) — they move to the background immediately and the answer arrives as a task notification
 - **Run tasks in background**: Use `async: true` for long-running operations that you can check later
 - **Monitor progress**: Use the check_status tool to monitor async operations with AI-generated summaries
 - **Cancel jobs**: Use the cancel_job tool to stop running operations

package/docs/API.md

@@ -11,36 +11,33 @@ The Converse MCP Server exposes three tools through the Model Context Protocol (
 2. **Check Status Tool** (`check_status`) — monitor and retrieve results from asynchronous jobs.
 3. **Cancel Job Tool** (`cancel_job`) — cancel a running background job.
 
-The chat tool runs **synchronously** (immediate response) or **asynchronously** (`async: true`, background processing polled with `check_status`). When AI summarization is enabled, the server generates titles and summaries for better context tracking.
+The chat tool runs **synchronously** (immediate response), as an **MCP task** (automatic, for clients that support the [Tasks extension](#mcp-tasks)), or **asynchronously** (`async: true`, background processing polled with `check_status`). When AI summarization is enabled, the server generates titles and summaries for better context tracking.
 
 ## Transport Protocols
 
-The server supports two transport modes:
+The server supports two transport modes. Both serve two MCP protocol eras side by side: the stateless **2026-07-28** revision (`server/discover`, per-request capabilities), which is required for [MCP tasks](#mcp-tasks), and the earlier `initialize`-based revisions for older clients.
 
-### HTTP Transport (Default)
+### HTTP Transport
 - **Endpoint**: `http://localhost:3157/mcp`
 - **Protocol**: HTTP streaming with JSON-RPC 2.0
 - **Usage**: Best for development, debugging, and web integrations
-- **Features**: Health endpoints, CORS support, session management
+- **Features**: Health endpoints, CORS support. 2026-07-28 requests are stateless; earlier-revision clients get `Mcp-Session-Id` sessions
 
-### Stdio Transport (Legacy)
+### Stdio Transport (Default)
 - **Protocol**: Standard input/output with JSON-RPC 2.0
 - **Usage**: Traditional MCP client integrations
-- **Features**: Process-based communication, lower latency
+- **Features**: Process-based communication, lower latency. The client's first message picks the protocol era for the connection
 
 **Transport Selection:**
 ```bash
-# Default (HTTP)
+# Default (stdio)
 npm start
 
-# Explicit HTTP
+# HTTP transport
 npm start -- --transport=http
 
-# Stdio transport
-npm start -- --transport=stdio
-
 # Environment variable
-MCP_TRANSPORT=stdio npm start
+MCP_TRANSPORT=http npm start
 ```
 
 ## Chat Tool
@@ -812,6 +809,36 @@ The first request creates a continuation automatically and returns its ID; pass
 { "prompt": "What about microservices?", "continuation_id": "conv_abc123" }
 ```
 
+## MCP Tasks
+
+The server implements the [MCP Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview) (`io.modelcontextprotocol/tasks`) on protocol revision 2026-07-28 and advertises it in `server/discover`. When a `chat` call's per-request client capabilities declare the extension, the server answers the `tools/call` at once with a task handle instead of blocking until the models finish:
+
+```json
+{
+  "resultType": "task",
+  "taskId": "task_V1StGXR8_Z5jdHi6B-myT",
+  "status": "working",
+  "statusMessage": "consensus: codex, gemini",
+  "createdAt": "2026-10-23T18:43:28.419Z",
+  "lastUpdatedAt": "2026-10-23T18:43:28.419Z",
+  "ttlMs": null,
+  "pollIntervalMs": 2000
+}
+```
+
+The client polls `tasks/get` with the `taskId`. On `completed`, the `result` field holds exactly the `CallToolResult` a blocking call would have returned, including `isError: true` for tool-level failures. `tasks/cancel` aborts the in-flight provider calls. `tasks/update` is acknowledged but never needed, because no tool asks for input mid-task.
+
+| Behaviour | Detail |
+|-----------|--------|
+| Which calls become tasks | `chat` only, and only without `async: true` (that path already returns at once and is followed with `check_status`). `decide`, `check_status`, and `cancel_job` always answer directly |
+| Clients without the extension | Get the normal blocking result. Earlier protocol revisions never see tasks |
+| `ttlMs` | `null` while the task runs (it never expires mid-flight). Once it finishes, the task stays answerable for one hour |
+| Unknown or expired `taskId` | JSON-RPC error `-32602` |
+| `tasks/*` without the extension declared | JSON-RPC error `-32021` |
+| Server restart | Tasks live in server memory. A restarted server answers `-32602` for earlier task IDs; completed conversations are still saved under their `continuation_id` |
+
+**Claude Code** uses MCP tasks on v2.1.304 or later, in interactive terminal sessions and in Agent SDK or `--input-format stream-json` sessions with `CLAUDE_AUTO_BACKGROUND_TASKS=1`. A task-backed `chat` call moves to the background right away: Claude keeps working and gets the answer as a task notification, and the task appears in `/tasks` with its `statusMessage`. Set `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1` to make Claude wait for the result instead. See [MCP tasks in Claude Code](https://code.claude.com/docs/en/mcp#mcp-tasks-for-server-authors).
+
 ## Asynchronous Execution
 
 Set `async: true` on a chat request for long-running work:

package/docs/ARCHITECTURE.md

@@ -8,7 +8,10 @@ The Converse MCP Server follows a **functional, modular architecture** designed
 
 ```
 src/
-├── index.js              # Main entry point & MCP server setup
+├── index.js              # Main entry point & transport startup
+├── serverFactory.js      # Per-era MCP Server factory (SDK v2)
+├── router.js             # Request handlers, tool dispatch, MCP tasks
+├── async/taskStore.js    # MCP Tasks extension store
 ├── config.js             # Configuration and environment management
 ├── systemPrompts.js      # System prompts for tools
 ├── providers/            # AI provider implementations
@@ -54,55 +57,30 @@ tests/                    # Test suites
 
 ### Server Setup
 
-**HTTP Transport (Default):**
-```javascript
-// index.js - HTTP transport setup
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-
-const server = new Server(
-  { name: 'converse-mcp-server', version: '1.0.0' },
-  { capabilities: { tools: {} } }
-);
-
-// HTTP transport on port 3157 (default)
-const httpTransport = new StreamableHTTPServerTransport({
-  host: 'localhost',
-  port: 3157
-});
-```
+The server is built on MCP TypeScript SDK v2 (`@modelcontextprotocol/server`), which serves the stateless 2026-07-28 protocol revision alongside the earlier `initialize`-based ones. The SDK builds a `Server` per connection (stdio), per request (2026-07-28 over HTTP), or per session (earlier revisions over HTTP), so nothing request-scoped lives on a `Server` instance:
 
-**Stdio Transport (Legacy):**
 ```javascript
-// Alternative stdio transport
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// index.js
+const router = await createRouter(config);            // built once: dependencies, tools, task store
+const serverFactory = createServerFactory(router, mcpConfig);
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// serverFactory({ era }) → new Server(...) + router.attach(server, { era })
+// era 'modern' (2026-07-28) also advertises the Tasks extension and
+// registers tasks/get, tasks/update, tasks/cancel.
+
+serveStdio(serverFactory);                            // stdio: the first message picks the era
+await createHTTPTransport(serverFactory, httpConfig); // HTTP: see below
 ```
 
 **Transport Selection:**
-- **HTTP**: Default, better for development and debugging
-- **Stdio**: Use `--transport=stdio` or `MCP_TRANSPORT=stdio`
+- **Stdio**: Default
+- **HTTP**: Use `--transport=http` or `MCP_TRANSPORT=http`. `/mcp` classifies each request with the SDK's `isLegacyRequest`. Requests carrying the 2026-07-28 `_meta` envelope go to `createMcpHandler` (stateless). Everything else keeps the `Mcp-Session-Id` session map backed by `NodeStreamableHTTPServerTransport`
 
 ### Tool Registration
-```javascript
-// Dynamic tool registration
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  
-  switch (name) {
-    case 'chat':
-      return await chatTool(args); // mode: chat | consensus | roundtable
-    case 'check_status':
-      return await checkStatusTool(args);
-    case 'cancel_job':
-      return await cancelJobTool(args);
-    default:
-      throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${name}`);
-  }
-});
-```
+`router.attach(server, { era })` registers handlers by method name (`tools/call`, `tools/list`, `prompts/*`, `resources/*`) that dispatch to the tool registry in `src/tools/index.js`. Each tool is an `async (args, dependencies) => CallToolResult` function with `description` and `inputSchema` attached.
+
+### MCP Tasks
+A tool can attach a `task` policy (`{ eligible(args), statusMessage(args) }`); `chat` does. When a `tools/call` request's per-request client capabilities declare `io.modelcontextprotocol/tasks` and the policy accepts the arguments, the router creates a task in the process-global store (`src/async/taskStore.js`) and returns the `resultType: "task"` handle immediately. The tool then runs exactly as a blocking call would, under the task's own `AbortSignal`, and its `CallToolResult` becomes the task's `result`. The store is process-global so a task ID stays answerable across HTTP requests and reconnects; finished tasks are retained for an hour.
 
 ## 🤖 Provider System
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "4.8.5",
+  "version": "4.9.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",
@@ -93,13 +93,14 @@
     ".env.example"
   ],
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.303",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.304",
     "@anthropic-ai/sdk": "^0.135.0",
-    "@github/copilot-sdk": "^1.0.22",
+    "@github/copilot-sdk": "^1.0.23",
     "@google/genai": "^2.30.0",
     "@lydell/node-pty": "1.2.0-beta.15",
     "@mistralai/mistralai": "^2.7.0",
-    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@modelcontextprotocol/node": "^2.1.2",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@openai/codex-sdk": "^0.163.0",
     "cors": "^2.8.6",
     "dotenv": "^18.0.8",
@@ -108,9 +109,11 @@
     "nanoid": "^6.0.2",
     "openai": "^7.39.0",
     "p-limit": "^7.3.3",
-    "vite": "^8.3.4"
+    "vite": "^8.3.4",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@vitest/coverage-v8": "^5.0.5",
     "cross-env": "^10.1.0",
     "eslint": "^10.13.0",

package/src/async/taskStore.js

@@ -0,0 +1,239 @@
+/**
+ * MCP Tasks extension store (io.modelcontextprotocol/tasks).
+ *
+ * A task wraps one tools/call that the server chose to answer with a handle
+ * instead of blocking. The wrapped call runs exactly as it would synchronously;
+ * its CallToolResult becomes the task's `result`, so a client polling via
+ * tasks/get receives the same payload a plain tools/call would have returned.
+ *
+ * The store is process-global rather than per-connection: clients poll on new
+ * connections (HTTP reconnects, resumed sessions), so a task ID must stay
+ * answerable for as long as this process holds the record.
+ */
+
+import { LRUCache } from 'lru-cache';
+import { nanoid } from 'nanoid';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('task-store');
+
+export const TASKS_EXTENSION_ID = 'io.modelcontextprotocol/tasks';
+
+export const TASK_STATUS = {
+  WORKING: 'working',
+  INPUT_REQUIRED: 'input_required',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+};
+
+const TERMINAL_STATUSES = new Set([
+  TASK_STATUS.COMPLETED,
+  TASK_STATUS.FAILED,
+  TASK_STATUS.CANCELLED,
+]);
+
+// Model calls take seconds to minutes; polling faster than this only adds load.
+export const DEFAULT_POLL_INTERVAL_MS = 2000;
+
+// How long a task stays answerable after it reaches a terminal status. Clients
+// poll every few seconds, so this only needs to cover a client that was away
+// (disconnected, resumed later) when the task finished.
+export const DEFAULT_TERMINAL_RETENTION_MS = 60 * 60 * 1000;
+
+// Bounds memory if a client creates tasks and never polls them.
+const MAX_TASKS = 1000;
+
+const JSONRPC_INTERNAL_ERROR = -32603;
+
+/**
+ * True when the request's per-request client capabilities declare the tasks
+ * extension. Servers must never answer with a task otherwise.
+ * @param {object|undefined} meta - The request's `params._meta`
+ */
+export function clientSupportsTasks(meta) {
+  const extensions =
+    meta?.['io.modelcontextprotocol/clientCapabilities']?.extensions;
+  return Boolean(
+    extensions &&
+      typeof extensions === 'object' &&
+      Object.hasOwn(extensions, TASKS_EXTENSION_ID),
+  );
+}
+
+export function isTerminalStatus(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+
+export class TaskStore {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.terminalRetentionMs]
+   * @param {number} [options.pollIntervalMs]
+   */
+  constructor(options = {}) {
+    this.terminalRetentionMs =
+      options.terminalRetentionMs ?? DEFAULT_TERMINAL_RETENTION_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    // Running tasks have no TTL (ttl: 0 on set); a task only starts expiring
+    // once it is terminal, so a long model call is never evicted mid-flight.
+    this.tasks = new LRUCache({
+      max: MAX_TASKS,
+      ttlAutopurge: false,
+      allowStale: false,
+    });
+  }
+
+  /**
+   * Create a task and start `run` in the background. Resolves once the task
+   * record exists, before the work finishes, so the caller can answer the
+   * tools/call with the handle immediately.
+   * @param {object} params
+   * @param {string} params.toolName
+   * @param {string} [params.statusMessage]
+   * @param {(signal: AbortSignal) => Promise<object>} params.run - Produces the CallToolResult
+   * @returns {object} The CreateTaskResult wire object
+   */
+  create({ toolName, statusMessage, run }) {
+    const now = new Date().toISOString();
+    const record = {
+      taskId: `task_${nanoid(21)}`,
+      toolName,
+      status: TASK_STATUS.WORKING,
+      statusMessage,
+      createdAt: now,
+      lastUpdatedAt: now,
+      controller: new AbortController(),
+      result: undefined,
+      error: undefined,
+    };
+    this.tasks.set(record.taskId, record, { ttl: 0 });
+
+    logger.info('Task created', {
+      data: { taskId: record.taskId, tool: toolName },
+    });
+
+    // Detached on purpose: the tools/call response must not wait for the work.
+    Promise.resolve()
+      .then(() => run(record.controller.signal))
+      .then(
+        (result) => this.#settle(record, TASK_STATUS.COMPLETED, { result }),
+        (error) =>
+          this.#settle(record, TASK_STATUS.FAILED, {
+            error: {
+              code: JSONRPC_INTERNAL_ERROR,
+              message: error?.message || 'Task failed',
+            },
+          }),
+      );
+
+    return { resultType: 'task', ...this.#toWire(record) };
+  }
+
+  /**
+   * The current task state for tasks/get, or undefined for an unknown ID.
+   */
+  get(taskId) {
+    const record = this.tasks.get(taskId);
+    if (!record) return undefined;
+
+    const wire = { resultType: 'complete', ...this.#toWire(record) };
+    if (record.status === TASK_STATUS.COMPLETED) {
+      wire.result = record.result;
+    } else if (record.status === TASK_STATUS.FAILED) {
+      wire.error = record.error;
+    }
+    return wire;
+  }
+
+  /**
+   * Cooperative cancellation for tasks/cancel. Returns false for an unknown ID.
+   * A task that is already terminal keeps its status.
+   */
+  cancel(taskId) {
+    const record = this.tasks.get(taskId);
+    if (!record) return false;
+    if (isTerminalStatus(record.status)) return true;
+
+    record.controller.abort(new Error('Task cancelled by client'));
+    this.#settle(record, TASK_STATUS.CANCELLED, {
+      statusMessage: 'Cancelled by client',
+    });
+    return true;
+  }
+
+  /**
+   * Abort every running task. Used on shutdown so in-flight provider calls stop.
+   */
+  abortAll(reason = 'Server shutting down') {
+    for (const record of this.tasks.values()) {
+      if (!isTerminalStatus(record.status)) {
+        record.controller.abort(new Error(reason));
+      }
+    }
+  }
+
+  get size() {
+    return this.tasks.size;
+  }
+
+  #settle(record, status, { result, error, statusMessage } = {}) {
+    // The first terminal transition wins: a cancelled task whose work later
+    // resolves (or rejects on the abort) stays cancelled.
+    if (isTerminalStatus(record.status)) return;
+
+    record.status = status;
+    record.result = result;
+    record.error = error;
+    record.statusMessage = statusMessage;
+    record.lastUpdatedAt = new Date().toISOString();
+    this.tasks.set(record.taskId, record, { ttl: this.terminalRetentionMs });
+
+    logger.info('Task settled', {
+      data: {
+        taskId: record.taskId,
+        tool: record.toolName,
+        status,
+        isError: result?.isError === true,
+      },
+    });
+  }
+
+  #toWire(record) {
+    const wire = {
+      taskId: record.taskId,
+      status: record.status,
+      createdAt: record.createdAt,
+      lastUpdatedAt: record.lastUpdatedAt,
+      ttlMs: this.#ttlMs(record),
+      pollIntervalMs: this.pollIntervalMs,
+    };
+    if (record.statusMessage) {
+      wire.statusMessage = record.statusMessage;
+    }
+    return wire;
+  }
+
+  // The spec measures ttlMs from createdAt. A running task never expires here,
+  // so it reports null; a terminal one is kept for the retention window past
+  // the moment it settled.
+  #ttlMs(record) {
+    if (!isTerminalStatus(record.status)) return null;
+    const settledAfterMs =
+      Date.parse(record.lastUpdatedAt) - Date.parse(record.createdAt);
+    return settledAfterMs + this.terminalRetentionMs;
+  }
+}
+
+let taskStore = null;
+
+export function getTaskStore() {
+  if (!taskStore) {
+    taskStore = new TaskStore();
+  }
+  return taskStore;
+}
+
+export function setTaskStore(store) {
+  taskStore = store;
+}

package/src/index.js

@@ -8,8 +8,7 @@
  */
 
 import { fileURLToPath, pathToFileURL } from 'url';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import {
   loadConfig,
   validateRuntimeConfig,
@@ -17,6 +16,7 @@ import {
   getHttpTransportConfig,
 } from './config.js';
 import { createRouter } from './router.js';
+import { createServerFactory } from './serverFactory.js';
 import { createHTTPTransport } from './transport/httpTransport.js';
 import { createLogger, startTimer } from './utils/logger.js';
 import { debugError, forceLog } from './utils/console.js';
@@ -135,27 +135,22 @@ async function main() {
 
     logger.info('Using transport type', { data: { transport: transportType } });
 
-    logger.debug('Creating MCP server instance', {
+    logger.debug('Creating MCP server factory', {
       data: { name: mcpConfig.name, version: mcpConfig.version },
     });
 
-    // Create MCP server with configuration
-    const server = new Server(
-      {
-        name: mcpConfig.name,
-        version: mcpConfig.version,
-      },
-      mcpConfig,
-    );
-
-    // Set up router with server and config
-    await createRouter(server, config);
+    const router = await createRouter(config);
+    const serverFactory = createServerFactory(router, mcpConfig);
 
     // Start server with appropriate transport
     if (transportType === 'http') {
       // HTTP streaming transport with full configuration
       const httpConfig = getHttpTransportConfig(config);
-      const httpTransport = await createHTTPTransport(server, httpConfig);
+      const httpTransport = await createHTTPTransport(serverFactory, {
+        ...httpConfig,
+        serverName: mcpConfig.name,
+        serverVersion: mcpConfig.version,
+      });
 
       await httpTransport.start();
       const status = httpTransport.getStatus();
@@ -176,9 +171,12 @@ async function main() {
       // Store reference for shutdown
       process.httpTransport = httpTransport;
     } else {
-      // Stdio transport (legacy)
-      const transport = new StdioServerTransport();
-      await server.connect(transport);
+      // The opening message decides the connection's era: server/discover (or
+      // an envelope-carrying request) pins a 2026-07-28 instance, initialize
+      // pins a legacy one.
+      serveStdio(serverFactory, {
+        onerror: (error) => logger.error('Stdio transport error', { error }),
+      });
 
       const startupTime = serverTimer('completed');
       logger.info(
@@ -227,6 +225,9 @@ async function gracefulShutdown(signal) {
     stopAsyncJobStoreCleanup();
     stopFileCacheCleanup();
     logger.info('Cleanup timers stopped successfully');
+
+    const { getTaskStore } = await import('./async/taskStore.js');
+    getTaskStore().abortAll();
   } catch (error) {
     logger.error('Error stopping cleanup timers', { error });
   }

package/src/router.js

@@ -7,13 +7,11 @@
  */
 
 import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
+  MissingRequiredClientCapabilityError,
+  ProtocolError,
+  ProtocolErrorCode,
+} from '@modelcontextprotocol/server';
+import { z } from 'zod';
 import { getContinuationStore } from './continuationStore.js';
 import { getTools } from './tools/index.js';
 import { getProviders } from './providers/index.js';
@@ -27,6 +25,11 @@ import { processUnifiedContext } from './utils/contextProcessor.js';
 import { getAsyncJobStore } from './async/asyncJobStore.js';
 import { getJobRunner } from './async/jobRunner.js';
 import { getFileCache } from './async/fileCache.js';
+import {
+  getTaskStore,
+  clientSupportsTasks,
+  TASKS_EXTENSION_ID,
+} from './async/taskStore.js';
 import providerStreamNormalizer from './async/providerStreamNormalizer.js';
 import { createLogger, startTimer } from './utils/logger.js';
 import { debugError } from './utils/console.js';
@@ -177,12 +180,63 @@ async function createDependencies(config, context = {}) {
 }
 
 /**
- * Creates and configures the central router for handling MCP requests
- * @param {object} server - MCP Server instance
+ * Resolve a tool and validate its arguments, throwing on either failure.
+ * @returns {Function} The tool handler
+ */
+function prepareTool(toolName, toolArgs, tools) {
+  const { tool } = validateTool(toolName, tools);
+
+  if (tool.inputSchema) {
+    const isValidArgs = validateToolArguments(toolArgs, tool.inputSchema);
+    if (!isValidArgs) {
+      throw new ValidationError(
+        `Invalid arguments for tool ${toolName}`,
+        ERROR_CODES.INVALID_TOOL_ARGS,
+        {
+          providedArgs: Object.keys(toolArgs),
+          expectedSchema: tool.inputSchema,
+        },
+      );
+    }
+  }
+
+  return tool;
+}
+
+const TaskIdParamsSchema = z.object({ taskId: z.string() });
+
+// inputResponses is lifted out of params by the SDK before validation (it is
+// read from ctx.mcpReq.inputResponses), so it must stay optional here.
+const TaskUpdateParamsSchema = z.object({
+  taskId: z.string(),
+  inputResponses: z.record(z.string(), z.unknown()).optional(),
+});
+
+function requireTasksCapability(ctx) {
+  if (!clientSupportsTasks(ctx?.mcpReq?.envelope)) {
+    throw new MissingRequiredClientCapabilityError({
+      requiredCapabilities: { extensions: { [TASKS_EXTENSION_ID]: {} } },
+    });
+  }
+}
+
+function taskNotFoundError(taskId) {
+  return new ProtocolError(
+    ProtocolErrorCode.InvalidParams,
+    'Failed to retrieve task: Task not found',
+    { taskId },
+  );
+}
+
+/**
+ * Creates the central router. Built once per process; `attach` registers its
+ * handlers on every Server instance the transports create (one per stdio
+ * connection, per modern HTTP request, and per legacy HTTP session), so all of
+ * them share the same dependencies and the same task store.
  * @param {object} config - Configuration object with provider settings
- * @returns {Promise<void>}
+ * @returns {Promise<object>} Router interface: attach, listTools, callTool
  */
-export async function createRouter(server, config) {
+export async function createRouter(config) {
   const createRouterLogger = logger.operation('createRouter');
   const timer = startTimer('router-initialization', 'router');
 
@@ -192,16 +246,19 @@ export async function createRouter(server, config) {
     // Initialize dependencies with validation
     const dependencies = await createDependencies(config);
     const tools = getTools(config);
+    const taskStore = getTaskStore();
 
     createRouterLogger.info(
       `Router initialized with ${Object.keys(tools).length} tools`,
     );
 
-    // Register unified tool call handler with enhanced error handling
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    /**
+     * Run a tool to completion. Always resolves to a CallToolResult: failures
+     * become `isError` results, which is what both a plain tools/call and a
+     * completed task carry.
+     */
+    const executeTool = async (toolName, toolArgs, { signal, requestId }) => {
       const toolTimer = startTimer('tool-execution', 'router');
-      const toolName = request.params?.name;
-      const toolArgs = request.params?.arguments || {};
       const requestLogger = logger.operation(`tool-call:${toolName}`);
 
       try {
@@ -209,33 +266,14 @@ export async function createRouter(server, config) {
           data: { toolName, argCount: Object.keys(toolArgs).length },
         });
 
-        // Validate tool existence and callability
-        const { tool } = validateTool(toolName, tools);
-
-        // Validate tool arguments if schema is provided
-        if (tool.inputSchema) {
-          const isValidArgs = validateToolArguments(toolArgs, tool.inputSchema);
-          if (!isValidArgs) {
-            throw new ValidationError(
-              `Invalid arguments for tool ${toolName}`,
-              ERROR_CODES.INVALID_TOOL_ARGS,
-              {
-                providedArgs: Object.keys(toolArgs),
-                expectedSchema: tool.inputSchema,
-              },
-            );
-          }
-        }
-
-        // Execute the tool with dependency injection (signal is per-request from MCP SDK)
-        const result = await tool(toolArgs, { ...dependencies, signal: extra?.signal });
+        const tool = prepareTool(toolName, toolArgs, tools);
+        const result = await tool(toolArgs, { ...dependencies, signal });
 
         const executionTime = toolTimer('completed');
         requestLogger.info('Tool execution completed', {
           data: { executionTime: `${executionTime}ms` },
         });
 
-        // Ensure result has proper format
         if (!result || !result.content) {
           throw new ToolError(
             `Tool ${toolName} returned invalid result format`,
@@ -250,7 +288,7 @@ export async function createRouter(server, config) {
         const executionTime = toolTimer('failed');
 
         // Detect cancellation — log at debug, not error
-        if (extra?.signal?.aborted || error.name === 'AbortError') {
+        if (signal?.aborted || error.name === 'AbortError') {
           requestLogger.debug('Tool execution cancelled by client', {
             data: { executionTime: `${executionTime}ms` },
           });
@@ -268,13 +306,54 @@ export async function createRouter(server, config) {
         return createErrorResponse(error, toolName, {
           executionTime,
           arguments: Object.keys(toolArgs),
-          requestId: request.id || 'unknown',
+          requestId,
         });
       }
-    });
+    };
 
-    // Register enhanced list_tools handler
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    /**
+     * tools/call: answer with a task handle when the tool is long-running and
+     * this request's client declared the tasks extension; otherwise block.
+     */
+    const handleToolCall = async (request, ctx) => {
+      const toolName = request.params?.name;
+      const toolArgs = request.params?.arguments || {};
+      const requestId = ctx?.mcpReq?.id ?? 'unknown';
+      const taskPolicy = tools[toolName]?.task;
+
+      if (
+        taskPolicy &&
+        clientSupportsTasks(ctx?.mcpReq?.envelope) &&
+        taskPolicy.eligible(toolArgs)
+      ) {
+        // Bad arguments are reported on the call itself rather than as a task
+        // that fails on its first poll.
+        try {
+          prepareTool(toolName, toolArgs, tools);
+        } catch (error) {
+          return createErrorResponse(error, toolName, {
+            arguments: Object.keys(toolArgs),
+            requestId,
+          });
+        }
+
+        // The task owns its own abort signal: this request finishes as soon as
+        // the handle is returned, and only tasks/cancel may stop the work.
+        return taskStore.create({
+          toolName,
+          statusMessage: taskPolicy.statusMessage?.(toolArgs),
+          run: (taskSignal) =>
+            executeTool(toolName, toolArgs, { signal: taskSignal, requestId }),
+        });
+      }
+
+      return executeTool(toolName, toolArgs, {
+        signal: ctx?.mcpReq?.signal,
+        requestId,
+      });
+    };
+
+    const handleListTools = async () => {
       try {
         const toolList = Object.entries(tools).map(([name, handler]) => {
           const toolInfo = {
@@ -315,17 +394,9 @@ export async function createRouter(server, config) {
           { error: error.message },
         );
       }
-    });
-
-    // Register list_prompts handler
-    server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      return {
-        prompts: [helpPromptMetadata],
-      };
-    });
+    };
 
-    // Register get_prompt handler
-    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const handleGetPrompt = async (request) => {
       const promptName = request.params?.name;
 
       if (promptName === 'help') {
@@ -343,18 +414,9 @@ export async function createRouter(server, config) {
         'PROMPT_NOT_FOUND',
         { requestedPrompt: promptName },
       );
-    });
-
-    // Register list_resources handler
-    server.setRequestHandler(ListResourcesRequestSchema, async () => {
-      const resources = listResources();
-      return {
-        resources,
-      };
-    });
+    };
 
-    // Register read_resource handler
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const handleReadResource = async (request) => {
       const resourceUri = request.params?.uri;
 
       if (resourceUri === helpResourceMetadata.uri) {
@@ -366,9 +428,73 @@ export async function createRouter(server, config) {
         'RESOURCE_NOT_FOUND',
         { requestedResource: resourceUri },
       );
-    });
+    };
 
-    // Note: Custom health endpoint removed - MCP uses standard protocol methods only
+    const handleGetTask = async ({ taskId }, ctx) => {
+      requireTasksCapability(ctx);
+      const task = taskStore.get(taskId);
+      if (!task) {
+        throw taskNotFoundError(taskId);
+      }
+      return task;
+    };
+
+    // No tool asks for input mid-task, so there is never an outstanding
+    // inputRequest to fulfil; the spec says to ignore unknown keys and ack.
+    const handleUpdateTask = async ({ taskId }, ctx) => {
+      requireTasksCapability(ctx);
+      if (!taskStore.get(taskId)) {
+        throw taskNotFoundError(taskId);
+      }
+      return {};
+    };
+
+    const handleCancelTask = async ({ taskId }, ctx) => {
+      requireTasksCapability(ctx);
+      if (!taskStore.cancel(taskId)) {
+        throw taskNotFoundError(taskId);
+      }
+      return {};
+    };
+
+    /**
+     * Register the router's handlers on one Server instance.
+     * @param {object} server - MCP Server instance
+     * @param {object} [options]
+     * @param {'legacy'|'modern'} [options.era] - Protocol era the instance serves.
+     *   The tasks/* methods exist only on the modern (2026-07-28) era; on the
+     *   legacy era those names belong to the removed 2025-11-25 tasks design.
+     */
+    const attach = (server, { era = 'legacy' } = {}) => {
+      server.setRequestHandler('tools/call', handleToolCall);
+      server.setRequestHandler('tools/list', handleListTools);
+      server.setRequestHandler('prompts/list', async () => ({
+        prompts: [helpPromptMetadata],
+      }));
+      server.setRequestHandler('prompts/get', handleGetPrompt);
+      server.setRequestHandler('resources/list', async () => ({
+        resources: listResources(),
+      }));
+      server.setRequestHandler('resources/read', handleReadResource);
+
+      if (era === 'modern') {
+        server.setRequestHandler(
+          'tasks/get',
+          { params: TaskIdParamsSchema },
+          handleGetTask,
+        );
+        server.setRequestHandler(
+          'tasks/update',
+          { params: TaskUpdateParamsSchema },
+          handleUpdateTask,
+        );
+        server.setRequestHandler(
+          'tasks/cancel',
+          { params: TaskIdParamsSchema },
+          handleCancelTask,
+        );
+      }
+    };
 
     timer('completed');
     createRouterLogger.info('Router configured successfully', {
@@ -380,8 +506,9 @@ export async function createRouter(server, config) {
       },
     });
 
-    // Return router interface for testing purposes
     return {
+      attach,
+
       listTools: async () => {
         const tools = getTools(config);
         return {
@@ -405,28 +532,7 @@ export async function createRouter(server, config) {
         const toolArgs = toolCall.arguments || {};
 
         try {
-          // Validate tool existence and callability
-          const { tool } = validateTool(toolName, tools);
-
-          // Validate tool arguments if schema is provided
-          if (tool.inputSchema) {
-            const isValidArgs = validateToolArguments(
-              toolArgs,
-              tool.inputSchema,
-            );
-            if (!isValidArgs) {
-              throw new ValidationError(
-                `Invalid arguments for tool ${toolName}`,
-                ERROR_CODES.INVALID_TOOL_ARGS,
-                {
-                  providedArgs: Object.keys(toolArgs),
-                  expectedSchema: tool.inputSchema,
-                },
-              );
-            }
-          }
-
-          // Execute the tool with dependency injection (signal is per-request)
+          const tool = prepareTool(toolName, toolArgs, tools);
           return await tool(toolArgs, { ...dependencies, signal });
         } catch (error) {
           return createErrorResponse(error, toolName, {

package/src/serverFactory.js

@@ -0,0 +1,35 @@
+/**
+ * MCP Server factory
+ *
+ * The SDK builds a fresh Server per stdio connection, per modern (2026-07-28)
+ * HTTP request, and per legacy HTTP session, and tells the factory which
+ * protocol era the instance will serve. All instances share one router, so
+ * dependencies and the task store live outside any single Server.
+ */
+
+import { Server } from '@modelcontextprotocol/server';
+import { TASKS_EXTENSION_ID } from './async/taskStore.js';
+
+/**
+ * @param {object} router - Router from createRouter()
+ * @param {object} mcpConfig - Result of getMcpClientConfig()
+ * @returns {(ctx: { era: 'legacy'|'modern' }) => Server}
+ */
+export function createServerFactory(router, mcpConfig) {
+  return ({ era } = {}) => {
+    const capabilities = { ...mcpConfig.capabilities };
+    // Tasks are only served on the modern era, where tasks/get, tasks/update
+    // and tasks/cancel are registered; advertising them to a legacy client
+    // would point it at the removed 2025-11-25 task methods.
+    if (era === 'modern') {
+      capabilities.extensions = { [TASKS_EXTENSION_ID]: {} };
+    }
+
+    const server = new Server(
+      { name: mcpConfig.name, version: mcpConfig.version },
+      { capabilities },
+    );
+    router.attach(server, { era });
+    return server;
+  };
+}

package/src/tools/chat.js

@@ -1209,3 +1209,15 @@ chatTool.inputSchema = {
   },
   required: ['prompt'],
 };
+
+// Every model call takes seconds to minutes, so a client that supports the MCP
+// Tasks extension gets a task handle instead of a blocked call. `async: true`
+// is excluded: it already returns at once and is followed via check_status.
+chatTool.task = {
+  eligible: (args) => args.async !== true,
+  statusMessage: (args) => {
+    const mode = args.mode ?? 'chat';
+    const models = Array.isArray(args.models) ? args.models : ['auto'];
+    return `${mode}: ${models.join(', ')}`;
+  },
+};

package/src/tools/index.js

@@ -60,6 +60,7 @@ export function getTools(config = null) {
       };
       wrappedTool.description = tool.description;
       wrappedTool.inputSchema = modifiedSchema;
+      wrappedTool.task = tool.task;
 
       filteredTools[name] = wrappedTool;
     } else {

package/src/transport/httpTransport.js

@@ -1,15 +1,27 @@
 /**
  * HTTP Streaming Transport for MCP Server
  *
- * Implements StreamableHTTPServerTransport to replace stdio transport,
- * eliminating console output interference and providing better local development experience.
+ * Serves both protocol eras on one /mcp endpoint. Requests carrying the
+ * 2026-07-28 per-request envelope are stateless and go to the SDK's modern
+ * handler, which builds a server per request. Everything else is 2025-era
+ * traffic and keeps its session model: initialize creates a sessionful
+ * transport, and later POST/GET/DELETE requests find it by Mcp-Session-Id.
  */
 
 import express from 'express';
 import cors from 'cors';
 import { randomUUID } from 'node:crypto';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import {
+  createMcpHandler,
+  isInitializeRequest,
+  isLegacyRequest,
+} from '@modelcontextprotocol/server';
+import {
+  NodeStreamableHTTPServerTransport,
+  hostHeaderValidation,
+  toNodeHandler,
+  toWebRequest,
+} from '@modelcontextprotocol/node';
 import { createLogger } from '../utils/logger.js';
 import {
   registerTransportSession,
@@ -41,7 +53,14 @@ export class HTTPTransportServer {
       corsOptions: config.corsOptions || {
         origin: '*',
         methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-        allowedHeaders: ['Content-Type', 'mcp-session-id', 'Authorization'],
+        allowedHeaders: [
+          'Content-Type',
+          'Authorization',
+          'mcp-session-id',
+          'mcp-protocol-version',
+          'mcp-method',
+          'mcp-name',
+        ],
         credentials: false,
         exposedHeaders: ['Mcp-Session-Id'],
       },
@@ -61,17 +80,27 @@ export class HTTPTransportServer {
     this.server = null;
     this.transports = new Map(); // sessionId -> transport
     this.sessionTimers = new Map(); // sessionId -> timeout timer
-    this.mcpServer = null;
+    this.serverFactory = null;
+    this.modernHandler = null;
     this.isStarted = false;
     this.cleanupInterval = null;
   }
 
   /**
    * Initialize the HTTP transport server
-   * @param {object} mcpServer - MCP Server instance
+   * @param {Function} serverFactory - Builds an MCP Server for a given era
    */
-  async initialize(mcpServer) {
-    this.mcpServer = mcpServer;
+  async initialize(serverFactory) {
+    this.serverFactory = serverFactory;
+    // Legacy traffic never reaches this handler (it is routed to the session
+    // map first), so 'reject' only guards against a misrouted request.
+    this.modernHandler = toNodeHandler(
+      createMcpHandler(serverFactory, {
+        legacy: 'reject',
+        onerror: (error) =>
+          logger.error('Modern MCP request failed', { error }),
+      }),
+    );
     this.setupMiddleware();
     this.setupRoutes();
     return this;
@@ -160,6 +189,14 @@ export class HTTPTransportServer {
       });
     }
 
+    // Applied ahead of era routing so both eras get the same protection.
+    if (this.config.enableDnsRebindingProtection) {
+      const validateHost = hostHeaderValidation(this.config.allowedHosts);
+      this.app.use('/mcp', (req, res, next) => {
+        if (validateHost(req, res)) next();
+      });
+    }
+
     // CORS configuration for browser clients
     if (this.config.enableCors) {
       this.app.use(cors(this.config.corsOptions));
@@ -185,19 +222,34 @@ export class HTTPTransportServer {
    * Setup MCP HTTP routes
    */
   setupRoutes() {
-    // Main MCP endpoint - handles POST requests for client-to-server communication
-    this.app.post('/mcp', async (req, res) => {
-      await this.handleMcpRequest(req, res);
-    });
-
-    // SSE endpoint - handles GET requests for server-to-client notifications
-    this.app.get('/mcp', async (req, res) => {
-      await this.handleSseRequest(req, res);
-    });
+    this.app.all('/mcp', async (req, res) => {
+      try {
+        const webRequest = await toWebRequest(req, req.body);
+        if (!(await isLegacyRequest(webRequest, req.body))) {
+          await this.modernHandler(req, res, req.body);
+          return;
+        }
+      } catch (error) {
+        logger.error('Error classifying MCP request', { error });
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: 'Internal server error' },
+            id: null,
+          });
+        }
+        return;
+      }
 
-    // Session termination - handles DELETE requests
-    this.app.delete('/mcp', async (req, res) => {
-      await this.handleSessionTermination(req, res);
+      if (req.method === 'POST') {
+        await this.handleMcpRequest(req, res);
+      } else if (req.method === 'GET') {
+        await this.handleSseRequest(req, res);
+      } else if (req.method === 'DELETE') {
+        await this.handleSessionTermination(req, res);
+      } else {
+        res.status(405).set('Allow', 'GET, POST, DELETE').end();
+      }
     });
 
     // Health check endpoint
@@ -205,7 +257,7 @@ export class HTTPTransportServer {
       res.json({
         status: 'healthy',
         transport: 'http',
-        server: this.mcpServer ? 'connected' : 'disconnected',
+        server: this.serverFactory ? 'connected' : 'disconnected',
         sessions: this.transports.size,
         timestamp: new Date().toISOString(),
       });
@@ -214,8 +266,8 @@ export class HTTPTransportServer {
     // Server info endpoint
     this.app.get('/info', (req, res) => {
       res.json({
-        name: this.mcpServer?.serverCapabilities?.name || 'unknown',
-        version: this.mcpServer?.serverCapabilities?.version || 'unknown',
+        name: this.config.serverName || 'unknown',
+        version: this.config.serverVersion || 'unknown',
         transport: 'http-streaming',
         endpoints: {
           mcp: '/mcp',
@@ -363,7 +415,7 @@ export class HTTPTransportServer {
    * Create a new MCP transport with session management
    */
   async createNewTransport() {
-    const transport = new StreamableHTTPServerTransport({
+    const transport = new NodeStreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
       onsessioninitialized: (sessionId) => {
         this.transports.set(sessionId, transport);
@@ -372,8 +424,6 @@ export class HTTPTransportServer {
         registerTransportSession(transport, sessionId);
         logger.debug('Transport session initialized', { data: { sessionId } });
       },
-      enableDnsRebindingProtection: this.config.enableDnsRebindingProtection,
-      allowedHosts: this.config.allowedHosts,
     });
 
     // Clean up transport when closed
@@ -387,8 +437,7 @@ export class HTTPTransportServer {
       }
     };
 
-    // Connect to the MCP server
-    await this.mcpServer.connect(transport);
+    await this.serverFactory({ era: 'legacy' }).connect(transport);
 
     return transport;
   }
@@ -573,12 +622,12 @@ export class HTTPTransportServer {
 
 /**
  * Factory function to create and configure HTTP transport server
- * @param {object} mcpServer - MCP Server instance
+ * @param {Function} serverFactory - Builds an MCP Server for a given era
  * @param {object} config - HTTP transport configuration
  * @returns {Promise<HTTPTransportServer>}
  */
-export async function createHTTPTransport(mcpServer, config = {}) {
+export async function createHTTPTransport(serverFactory, config = {}) {
   const httpTransport = new HTTPTransportServer(config);
-  await httpTransport.initialize(mcpServer);
+  await httpTransport.initialize(serverFactory);
   return httpTransport;
 }