@absolutejs/mcp 0.8.0 → 0.10.0

package/README.md

@@ -1,11 +1,17 @@
 # @absolutejs/mcp
 
+MCP tool discovery preserves the OpenID AuthZEN COAZ `coaz` marker and
+`x-coaz-mapping` JSON Schema extension end to end. Use `@absolutejs/policy` to
+validate and evaluate the mapping before dispatching an authorized tool call.
+
 Serve a remote [Model Context Protocol](https://modelcontextprotocol.io) endpoint
 — streamable HTTP, stateless — from a tool/prompt/resource registry. You supply
 **which** tools to expose and **how** to authorize a request into a caller; the
 package owns the JSON-RPC protocol, protocol-version negotiation, RFC 9728
 discovery metadata, and the `401` challenge that lets a client find your
-authorization server.
+authorization server. The default negotiated revision is the current finalized
+`2025-11-25` specification; older finalized revisions remain available when
+explicitly requested.
 
 ## Agent action enforcement
 
@@ -36,10 +42,11 @@ mcpServer<Caller>({
 
 ## Durable Tasks
 
-The package implements the final `io.modelcontextprotocol/tasks` extension from
-SEP-2663: server-directed task creation, `tasks/get`, `tasks/update`, and
-`tasks/cancel`. There is intentionally no `tasks/list`; task handles are bound
-to an authorization key and checked on every request.
+The package implements native MCP `2025-11-25` task augmentation:
+`execution.taskSupport`, client-requested task creation, `tasks/get`,
+`tasks/result`, authorization-bound `tasks/list`, and terminal-safe
+`tasks/cancel`. It also retains the older `io.modelcontextprotocol/tasks`
+SEP-2663 wire shape only when an older protocol revision is negotiated.
 
 ```ts
 tasks: {
@@ -48,8 +55,20 @@ tasks: {
   store: createMemoryMcpTaskStore(), // use a durable shared store in production
   ttlMs: 60 * 60 * 1000,
 }
+
+tools: () => ({
+  long_running_report: {
+    taskSupport: "optional", // "required" and "forbidden" are also supported
+    // normal tool definition…
+  },
+})
 ```
 
+Clients can use `callToolAsTask`, then `getTask`, `listTasks`, `cancelTask`, and
+`getTaskResult`. Task status never exposes the stored result or authorization
+key; the final result is returned only by `tasks/result` with required
+`io.modelcontextprotocol/related-task` metadata.
+
 For multi-instance production deployments, use
 `createPostgresMcpTaskStore()` and `createPostgresMcpSessionStore()` after
 applying `mcpPostgresSchemaSql()`. Task updates and cancellation protect
@@ -224,6 +243,13 @@ dismissed it), or `unsupported` (this client can't ask anyone — check
 `canElicit` and take another path). Never fabricate an answer for the user; the
 spec also forbids eliciting **sensitive information**.
 
+For credentials, third-party OAuth, or payment flows, use `mode: "url"` with a
+unique `elicitationId` and HTTPS URL. The client advertises form and URL modes
+separately, never prefetches the URL, and returns only the user's consent—not
+credentials or page contents. Tool handlers can check `canElicitUrl` before
+starting the flow. The server rejects non-HTTPS URLs except localhost
+development URLs and rejects URLs containing embedded credentials.
+
 **The trade-off, stated plainly.** Elicitation is the one MCP feature a
 stateless server cannot do: the question goes out on the SSE stream of an
 in-flight `tools/call`, and the client answers on a _separate_ HTTP POST. Two

package/dist/index.js

@@ -46,7 +46,7 @@ var verifyBearer = async (config) => {
 };
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 30000;
-var DEFAULT_PROTOCOL = "2025-06-18";
+var DEFAULT_PROTOCOL = "2025-11-25";
 
 class McpClientError extends Error {
   code;
@@ -152,12 +152,19 @@ var createMcpClient = (options) => {
   const answerServer = async (message) => {
     if (message.method !== "elicitation/create")
       return;
-    const request = isRecord(message.params) ? {
-      message: typeof message.params.message === "string" ? message.params.message : "",
-      requestedSchema: isRecord(message.params.requestedSchema) ? message.params.requestedSchema : {}
-    } : { message: "", requestedSchema: {} };
+    const params = isRecord(message.params) ? message.params : {};
+    const request = params.mode === "url" && typeof params.elicitationId === "string" && typeof params.url === "string" ? {
+      elicitationId: params.elicitationId,
+      message: typeof params.message === "string" ? params.message : "",
+      mode: "url",
+      url: params.url
+    } : {
+      message: typeof params.message === "string" ? params.message : "",
+      mode: "form",
+      requestedSchema: isRecord(params.requestedSchema) ? params.requestedSchema : {}
+    };
     const result = options.onElicit ? await options.onElicit(request) : { action: "decline" };
-    await respond(message.id, result);
+    await respond(message.id, request.mode === "url" && result.action === "accept" ? { action: "accept" } : result);
   };
   const rpc = async (method, params) => {
     const controller = new AbortController;
@@ -243,7 +250,7 @@ var createMcpClient = (options) => {
   };
   const initialize = async () => {
     const result = await rpc("initialize", {
-      capabilities: options.onElicit ? { elicitation: {} } : {},
+      capabilities: options.onElicit ? { elicitation: { form: {}, url: {} } } : {},
       clientInfo: options.clientInfo ?? {
         name: "@absolutejs/mcp",
         version: "0"
@@ -265,10 +272,12 @@ var createMcpClient = (options) => {
       const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
       collected.push(...tools.filter(isRecord).map((tool) => ({
         annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
+        coaz: typeof tool.coaz === "boolean" ? tool.coaz : undefined,
         description: typeof tool.description === "string" ? tool.description : undefined,
         inputSchema: isRecord(tool.inputSchema) ? tool.inputSchema : undefined,
         name: typeof tool.name === "string" ? tool.name : "",
-        outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined
+        outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined,
+        taskSupport: isRecord(tool.execution) && (tool.execution.taskSupport === "forbidden" || tool.execution.taskSupport === "optional" || tool.execution.taskSupport === "required") ? tool.execution.taskSupport : undefined
       })));
       const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
       if (next === undefined)
@@ -284,6 +293,44 @@ var createMcpClient = (options) => {
     }
     return { content: [], isError: false };
   };
+  const taskFrom = (value) => {
+    if (!isRecord(value) || typeof value.taskId !== "string") {
+      throw new McpClientError("Malformed MCP task response");
+    }
+    return value;
+  };
+  const callToolAsTask = async (name, args, options2 = {}) => {
+    const result = await rpc("tools/call", {
+      arguments: args ?? {},
+      name,
+      task: options2.ttl === undefined ? {} : { ttl: options2.ttl }
+    });
+    return taskFrom(isRecord(result) ? result.task : undefined);
+  };
+  const getTask = async (taskId) => taskFrom(await rpc("tasks/get", { taskId }));
+  const cancelTask = async (taskId) => taskFrom(await rpc("tasks/cancel", { taskId }));
+  const getTaskResult = async (taskId) => {
+    const result = await rpc("tasks/result", { taskId });
+    if (!isRecord(result) || !Array.isArray(result.content)) {
+      throw new McpClientError("Malformed MCP task result");
+    }
+    return result;
+  };
+  const listTasks = async () => {
+    const collected = [];
+    let cursor;
+    for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
+      const result = await rpc("tasks/list", cursor === undefined ? undefined : { cursor });
+      if (isRecord(result) && Array.isArray(result.tasks)) {
+        collected.push(...result.tasks.map(taskFrom));
+      }
+      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      if (next === undefined)
+        break;
+      cursor = next;
+    }
+    return collected;
+  };
   const listResources = async () => {
     const collected = [];
     let cursor;
@@ -303,7 +350,19 @@ var createMcpClient = (options) => {
   const ping = async () => {
     await rpc("ping");
   };
-  return { callTool, initialize, listResources, listTools, ping, readResource };
+  return {
+    callTool,
+    callToolAsTask,
+    cancelTask,
+    getTask,
+    getTaskResult,
+    initialize,
+    listResources,
+    listTasks,
+    listTools,
+    ping,
+    readResource
+  };
 };
 // src/oauth.ts
 var splitChallenges = (value) => {
@@ -657,6 +716,7 @@ var createMemoryMcpTaskStore = () => {
       const task = tasks.get(taskId);
       return task === undefined ? null : clone(task);
     },
+    list: (authorizationKey, { limit, offset }) => [...tasks.values()].filter((task) => task.authorizationKey === authorizationKey).sort((left, right) => right.lastUpdatedAt.localeCompare(left.lastUpdatedAt)).slice(offset, offset + limit).map(clone),
     save: (task) => {
       tasks.set(task.taskId, clone(task));
     },
@@ -678,11 +738,22 @@ var createMemoryMcpTaskStore = () => {
   };
 };
 var publicMcpTask = ({ authorizationKey, ...task }) => {
-  return task;
+  const { error, inputRequests, pollIntervalMs, result, ttlMs, ...rest } = task;
+  return {
+    ...rest,
+    ...pollIntervalMs === undefined ? {} : { pollInterval: pollIntervalMs },
+    ttl: ttlMs
+  };
 };
 
 // src/dispatch.ts
-var DEFAULT_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var MCP_LATEST_PROTOCOL_VERSION = "2025-11-25";
+var DEFAULT_PROTOCOLS = [
+  MCP_LATEST_PROTOCOL_VERSION,
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05"
+];
 var DEFAULT_RESOURCE_MIME = "text/markdown";
 var DEFAULT_LIST_PAGE_SIZE = 50;
 var decodeCursor = (params) => {
@@ -729,18 +800,34 @@ var normalizeResult = (value) => {
     return { content: value, isError: false };
   return { isError: false, ...value };
 };
-var clientCanElicit = (params) => {
-  if (!isRecord(params) || !isRecord(params.capabilities))
-    return false;
-  return isRecord(params.capabilities.elicitation);
+var clientElicitation = (params) => {
+  if (!isRecord(params) || !isRecord(params.capabilities)) {
+    return { form: false, url: false };
+  }
+  const elicitation = params.capabilities.elicitation;
+  if (!isRecord(elicitation))
+    return { form: false, url: false };
+  return {
+    form: Object.keys(elicitation).length === 0 || isRecord(elicitation.form),
+    url: isRecord(elicitation.url)
+  };
 };
 var initialize = async (config, id, params, context) => {
   const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
+  const protocolVersion = negotiateProtocol(supported, params);
   const capabilities = {
     tools: { listChanged: false }
   };
   if (config.tasks !== undefined) {
-    capabilities.extensions = { "io.modelcontextprotocol/tasks": {} };
+    if (protocolVersion === MCP_LATEST_PROTOCOL_VERSION) {
+      capabilities.tasks = {
+        cancel: {},
+        list: {},
+        requests: { tools: { call: {} } }
+      };
+    } else {
+      capabilities.extensions = { "io.modelcontextprotocol/tasks": {} };
+    }
   }
   if (config.prompts)
     capabilities.prompts = { listChanged: false };
@@ -750,23 +837,26 @@ var initialize = async (config, id, params, context) => {
   const response = rpcResult(id, {
     capabilities,
     ...config.instructions === undefined ? {} : { instructions: config.instructions },
-    protocolVersion: negotiateProtocol(supported, params),
+    protocolVersion,
     serverInfo: config.serverInfo
   });
   if (!config.elicitation?.enabled || !context.sessions)
     return response;
-  const sessionId = await context.sessions.create(clientCanElicit(params));
+  const elicitation = clientElicitation(params);
+  const sessionId = await context.sessions.create(elicitation.form || elicitation.url, elicitation.url);
   response.headers.set("Mcp-Session-Id", sessionId);
   return response;
 };
-var toolsList = async (config, caller, scopes, id, params) => {
+var toolsList = async (config, caller, scopes, id, params, protocolVersion) => {
   const tools = await config.tools({ caller, meta: {} });
   const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes) && agencyAllows(config, tool, scopes)).map(([name, tool]) => ({
     annotations: tool.annotations,
+    ...tool.coaz === undefined ? {} : { coaz: tool.coaz },
     description: tool.description,
     inputSchema: tool.inputSchema,
     name,
-    ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }
+    ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema },
+    ...protocolVersion === MCP_LATEST_PROTOCOL_VERSION && tool.taskSupport !== undefined ? { execution: { taskSupport: tool.taskSupport } } : {}
   }));
   const { items, nextCursor } = paginate(visible, decodeCursor(params), config.listPageSize ?? DEFAULT_LIST_PAGE_SIZE);
   return rpcResult(id, {
@@ -777,6 +867,7 @@ var toolsList = async (config, caller, scopes, id, params) => {
 var errorResult = (id, text) => rpcResult(id, { content: [{ text, type: "text" }], isError: true });
 var noElicit = {
   canElicit: false,
+  canElicitUrl: false,
   elicit: () => Promise.resolve({ action: "unsupported" })
 };
 var SSE_HEADERS = {
@@ -869,7 +960,7 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
     await config.onCall({ args, caller, meta, name, ok });
   return payload;
 };
-var toolsCallStreaming = (config, caller, scopes, id, name, args, meta, tool, sessions, canElicit) => {
+var toolsCallStreaming = (config, caller, scopes, id, name, args, meta, tool, sessions, canElicit, canElicitUrl) => {
   const encoder = new TextEncoder;
   const body = new ReadableStream({
     async start(controller) {
@@ -885,9 +976,24 @@ var toolsCallStreaming = (config, caller, scopes, id, name, args, meta, tool, se
       };
       const context = {
         canElicit,
+        canElicitUrl,
         elicit: async (request) => {
           if (!canElicit)
             return { action: "unsupported" };
+          if (request.mode === "url") {
+            if (!canElicitUrl)
+              return { action: "unsupported" };
+            let url;
+            try {
+              url = new URL(request.url);
+            } catch {
+              throw new Error("URL elicitation requires a valid URL");
+            }
+            const localDevelopment = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+            if (url.protocol !== "https:" && !localDevelopment || url.username !== "" || url.password !== "") {
+              throw new Error("URL elicitation requires HTTPS without embedded credentials");
+            }
+          }
           const pending = sessions.startElicit(request);
           send({
             id: pending.id,
@@ -929,8 +1035,22 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
     return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${name}`);
   }
   const tasks = config.tasks;
-  if (tasks !== undefined && await tasks.shouldCreate({ args, caller, name })) {
-    if (!supportsTasks(params)) {
+  const nativeTasks = context.protocolVersion === MCP_LATEST_PROTOCOL_VERSION;
+  const requestedTaskParams = isRecord(params.task) ? params.task : undefined;
+  const requestedTask = requestedTaskParams !== undefined;
+  const taskSupport = tool.taskSupport ?? "forbidden";
+  if (nativeTasks && requestedTask && tasks === undefined) {
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "Tasks are not configured");
+  }
+  if (nativeTasks && requestedTask && taskSupport === "forbidden") {
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "Tool does not support task execution");
+  }
+  if (nativeTasks && !requestedTask && taskSupport === "required") {
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "Tool requires task execution");
+  }
+  const shouldCreateTask = tasks !== undefined && (nativeTasks ? requestedTask && taskSupport !== "forbidden" : await tasks.shouldCreate({ args, caller, name }));
+  if (tasks !== undefined && shouldCreateTask) {
+    if (!nativeTasks && !supportsTasks(params)) {
       return rpcError(id, JSONRPC_MISSING_REQUIRED_CLIENT_CAPABILITY, "Missing required client capability", {
         requiredCapabilities: {
           extensions: { "io.modelcontextprotocol/tasks": {} }
@@ -938,6 +1058,7 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
       });
     }
     const createdAt = new Date().toISOString();
+    const requestedTtl = requestedTaskParams !== undefined && typeof requestedTaskParams.ttl === "number" && requestedTaskParams.ttl >= 0 ? requestedTaskParams.ttl : undefined;
     const task = {
       authorizationKey: await tasks.authorizationKey(caller),
       createdAt,
@@ -945,7 +1066,7 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
       pollIntervalMs: tasks.pollIntervalMs,
       status: "working",
       taskId: crypto.randomUUID(),
-      ttlMs: tasks.ttlMs ?? null
+      ttlMs: tasks.ttlMs ?? requestedTtl ?? null
     };
     await tasks.store.save(task);
     setTimeout(() => {
@@ -953,7 +1074,7 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
         const result = isRecord(payload2) && isRecord(payload2.result) ? payload2.result : { content: [], isError: true };
         await tasks.store.update(task.taskId, {
           result,
-          status: "completed"
+          status: result.isError === true ? "failed" : "completed"
         });
       }).catch(async (error) => {
         await tasks.store.update(task.taskId, {
@@ -965,12 +1086,12 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
         });
       });
     }, 0);
-    return rpcResult(id, { ...publicMcpTask(task), resultType: "task" });
+    return nativeTasks ? rpcResult(id, { task: publicMcpTask(task) }) : rpcResult(id, { ...publicMcpTask(task), resultType: "task" });
   }
   const sessions = context.sessions;
   const session = sessions ? await sessions.get(context.sessionId ?? null) : null;
   if (tool.mayElicit === true && config.elicitation?.enabled === true && sessions && session) {
-    return toolsCallStreaming(config, caller, scopes, id, name, args, meta, tool, sessions, session.canElicit);
+    return toolsCallStreaming(config, caller, scopes, id, name, args, meta, tool, sessions, session.canElicit, session.canElicitUrl ?? false);
   }
   const payload = await runTool(config, caller, scopes, id, name, args, meta, tool, noElicit);
   return new Response(JSON.stringify(payload), {
@@ -995,11 +1116,70 @@ var authorizedTask = async (config, caller, params) => {
   const authorizationKey = await config.tasks.authorizationKey(caller);
   return task.authorizationKey === authorizationKey ? task : null;
 };
-var tasksGet = async (config, caller, id, params) => {
+var tasksGet = async (config, caller, id, params, native) => {
   const task = await authorizedTask(config, caller, params);
   if (task === null)
     return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
-  return rpcResult(id, { ...publicMcpTask(task), resultType: "complete" });
+  return rpcResult(id, native ? publicMcpTask(task) : { ...publicMcpTask(task), resultType: "complete" });
+};
+var tasksResult = async (config, caller, id, params, signal) => {
+  let task = await authorizedTask(config, caller, params);
+  if (task === null)
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
+  while (task.status === "working" || task.status === "input_required") {
+    if (signal?.aborted) {
+      return rpcError(id, JSONRPC_INTERNAL_ERROR, "Task result request cancelled");
+    }
+    await new Promise((resolve) => setTimeout(resolve, task?.pollIntervalMs ?? 100));
+    task = await authorizedTask(config, caller, params);
+    if (task === null)
+      return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
+  }
+  if (task.error !== undefined) {
+    return rpcError(id, typeof task.error.code === "number" ? task.error.code : JSONRPC_INTERNAL_ERROR, typeof task.error.message === "string" ? task.error.message : "Task failed");
+  }
+  const result = task.result ?? {
+    content: [],
+    isError: task.status !== "completed"
+  };
+  return rpcResult(id, {
+    ...result,
+    _meta: {
+      ...isRecord(result._meta) ? result._meta : {},
+      "io.modelcontextprotocol/related-task": { taskId: task.taskId }
+    }
+  });
+};
+var tasksList = async (config, caller, id, params) => {
+  if (config.tasks === undefined) {
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "Tasks are not configured");
+  }
+  const authorizationKey = await config.tasks.authorizationKey(caller);
+  let offset = 0;
+  if (isRecord(params) && params.cursor !== undefined) {
+    if (typeof params.cursor !== "string") {
+      return rpcError(id, JSONRPC_INVALID_PARAMS, "Invalid task cursor");
+    }
+    try {
+      offset = Number.parseInt(atob(params.cursor), 10);
+    } catch {
+      offset = -1;
+    }
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+      return rpcError(id, JSONRPC_INVALID_PARAMS, "Invalid task cursor");
+    }
+  }
+  const pageSize = Math.min(100, Math.max(1, config.tasks.listPageSize ?? 50));
+  const fetched = await config.tasks.store.list(authorizationKey, {
+    limit: pageSize + 1,
+    offset
+  });
+  const items = fetched.slice(0, pageSize);
+  const nextCursor = fetched.length > pageSize ? encodeCursor(offset + pageSize) : undefined;
+  return rpcResult(id, {
+    tasks: items.map(publicMcpTask),
+    ...nextCursor === undefined ? {} : { nextCursor }
+  });
 };
 var tasksUpdate = async (config, caller, id, params) => {
   const task = await authorizedTask(config, caller, params);
@@ -1013,12 +1193,16 @@ var tasksUpdate = async (config, caller, id, params) => {
   });
   return rpcResult(id, { resultType: "complete" });
 };
-var tasksCancel = async (config, caller, id, params) => {
+var tasksCancel = async (config, caller, id, params, native) => {
   const task = await authorizedTask(config, caller, params);
   if (task === null)
     return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
+  if (["cancelled", "completed", "failed"].includes(task.status)) {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "Task is already terminal");
+  }
   await config.tasks?.store.cancel(task.taskId);
-  return rpcResult(id, { resultType: "complete" });
+  const cancelled = await config.tasks?.store.get(task.taskId);
+  return rpcResult(id, native && cancelled !== null && cancelled !== undefined ? publicMcpTask(cancelled) : { resultType: "complete" });
 };
 var promptsList = (config, id, params) => {
   const definitions = config.prompts?.definitions ?? {};
@@ -1089,7 +1273,10 @@ var elicitAnswer = async (message, context) => {
     return notificationAck();
   const result = isRecord(message.result) ? message.result : null;
   const action = result?.action;
-  const answer = action === "accept" && isRecord(result?.content) ? { action: "accept", content: result.content } : action === "decline" ? { action: "decline" } : { action: "cancel" };
+  const answer = action === "accept" ? {
+    action: "accept",
+    content: isRecord(result?.content) ? result.content : {}
+  } : action === "decline" ? { action: "decline" } : { action: "cancel" };
   await context.sessions.resolveElicit({
     requestId,
     result: answer,
@@ -1106,6 +1293,7 @@ var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   if (!("method" in message))
     return elicitAnswer(message, context);
   const id = idOf(message);
+  const protocolVersion = context.protocolVersion ?? "2025-06-18";
   const method = typeof message.method === "string" ? message.method : "";
   const { params } = message;
   if (method === "initialize") {
@@ -1122,17 +1310,24 @@ var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   if (method === "ping")
     return rpcResult(id, {});
   if (method === "tools/list") {
-    return toolsList(config, caller, scopes, id, params);
+    return toolsList(config, caller, scopes, id, params, protocolVersion);
   }
   if (method === "tools/call") {
-    return toolsCall(config, caller, scopes, id, params, context);
+    return toolsCall(config, caller, scopes, id, params, {
+      ...context,
+      protocolVersion
+    });
   }
   if (method === "tasks/get")
-    return tasksGet(config, caller, id, params);
-  if (method === "tasks/update")
+    return tasksGet(config, caller, id, params, protocolVersion === MCP_LATEST_PROTOCOL_VERSION);
+  if (method === "tasks/result" && protocolVersion === MCP_LATEST_PROTOCOL_VERSION)
+    return tasksResult(config, caller, id, params, context.requestSignal);
+  if (method === "tasks/list" && protocolVersion === MCP_LATEST_PROTOCOL_VERSION)
+    return tasksList(config, caller, id, params);
+  if (method === "tasks/update" && protocolVersion !== MCP_LATEST_PROTOCOL_VERSION)
     return tasksUpdate(config, caller, id, params);
   if (method === "tasks/cancel")
-    return tasksCancel(config, caller, id, params);
+    return tasksCancel(config, caller, id, params, protocolVersion === MCP_LATEST_PROTOCOL_VERSION);
   if (method === "prompts/list")
     return promptsList(config, id, params);
   if (method === "prompts/get")
@@ -1261,7 +1456,11 @@ var createMemoryStore = (ttlMs) => {
     create: (session) => {
       sweep();
       const id = crypto.randomUUID();
-      sessions.set(id, { canElicit: session.canElicit, lastSeen: Date.now() });
+      sessions.set(id, {
+        canElicit: session.canElicit,
+        canElicitUrl: session.canElicitUrl ?? false,
+        lastSeen: Date.now()
+      });
       return id;
     },
     drop: (id) => {
@@ -1272,7 +1471,10 @@ var createMemoryStore = (ttlMs) => {
       if (!session)
         return null;
       session.lastSeen = Date.now();
-      return { canElicit: session.canElicit };
+      return {
+        canElicit: session.canElicit,
+        canElicitUrl: session.canElicitUrl
+      };
     }
   };
 };
@@ -1307,9 +1509,9 @@ var createSessionRegistry = (options) => {
       });
       pending.clear();
     },
-    create: async (canElicit) => {
+    create: async (canElicit, canElicitUrl = false) => {
       await ready;
-      return await store.create({ canElicit });
+      return await store.create({ canElicit, canElicitUrl });
     },
     drop: async (id) => {
       await ready;
@@ -1388,12 +1590,27 @@ var runMcpPost = async (config, request, body) => {
   if (Array.isArray(body)) {
     return rpcError(null, JSONRPC_INVALID_REQUEST, "Batching is not supported");
   }
+  const isInitialize = typeof body === "object" && body !== null && "method" in body && body.method === "initialize";
+  const protocolVersion = request.headers.get("mcp-protocol-version");
+  const supportedProtocols = config.supportedProtocols ?? [
+    MCP_LATEST_PROTOCOL_VERSION,
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05"
+  ];
+  if (!isInitialize && (protocolVersion === null || !supportedProtocols.includes(protocolVersion))) {
+    return new Response("Missing or unsupported MCP-Protocol-Version", {
+      status: 400
+    });
+  }
   const sessions = registryFor(config);
   const sessionId = request.headers.get("mcp-session-id");
   if (sessions && sessionId && !await sessions.get(sessionId)) {
     return new Response(null, { status: HTTP_NOT_FOUND });
   }
   return dispatchMcp(config, auth.caller, auth.scopes ?? [], body, {
+    protocolVersion: protocolVersion ?? MCP_LATEST_PROTOCOL_VERSION,
+    requestSignal: request.signal,
     sessionId,
     sessions
   }).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
@@ -1470,10 +1687,12 @@ CREATE INDEX IF NOT EXISTS tasks_expiry_idx ON ${ns}.tasks (expires_at) WHERE ex
 CREATE TABLE IF NOT EXISTS ${ns}.sessions (
   session_id text PRIMARY KEY,
   can_elicit boolean NOT NULL,
+  can_elicit_url boolean NOT NULL DEFAULT false,
   created_at timestamptz NOT NULL DEFAULT now(),
   last_seen_at timestamptz NOT NULL DEFAULT now(),
   expires_at timestamptz NOT NULL
 );
+ALTER TABLE ${ns}.sessions ADD COLUMN IF NOT EXISTS can_elicit_url boolean NOT NULL DEFAULT false;
 CREATE INDEX IF NOT EXISTS sessions_expiry_idx ON ${ns}.sessions (expires_at);`;
 };
 var createPostgresMcpTaskStore = ({
@@ -1492,6 +1711,7 @@ var createPostgresMcpTaskStore = ({
       ]);
     },
     get: async (taskId) => (await client.query(`SELECT data FROM ${ns}.tasks WHERE task_id = $1 AND (expires_at IS NULL OR expires_at > $2::timestamptz)`, [taskId, now().toISOString()])).rows[0]?.data ?? null,
+    list: async (authorizationKey, { limit, offset }) => (await client.query(`SELECT data FROM ${ns}.tasks WHERE authorization_key = $1 AND (expires_at IS NULL OR expires_at > $2::timestamptz) ORDER BY updated_at DESC LIMIT $3 OFFSET $4`, [authorizationKey, now().toISOString(), limit, offset])).rows.map((row) => row.data),
     save: async (task) => {
       const expiresAt = task.ttlMs === null ? null : new Date(new Date(task.createdAt).getTime() + task.ttlMs).toISOString();
       await client.query(`INSERT INTO ${ns}.tasks (task_id, authorization_key, status, created_at, updated_at, expires_at, data) VALUES ($1, $2, $3, $4::timestamptz, $5::timestamptz, $6::timestamptz, $7::jsonb) ON CONFLICT (task_id) DO NOTHING`, [
@@ -1522,12 +1742,13 @@ var createPostgresMcpSessionStore = ({
 }) => {
   const ns = namespaceOf(namespace);
   return {
-    create: async ({ canElicit }) => {
+    create: async ({ canElicit, canElicitUrl }) => {
       const id = crypto.randomUUID();
       const current = now();
-      await client.query(`INSERT INTO ${ns}.sessions (session_id, can_elicit, created_at, last_seen_at, expires_at) VALUES ($1, $2, $3::timestamptz, $3::timestamptz, $4::timestamptz)`, [
+      await client.query(`INSERT INTO ${ns}.sessions (session_id, can_elicit, can_elicit_url, created_at, last_seen_at, expires_at) VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz, $5::timestamptz)`, [
         id,
         canElicit,
+        canElicitUrl ?? false,
         current.toISOString(),
         new Date(current.getTime() + ttlMs).toISOString()
       ]);
@@ -1540,13 +1761,16 @@ var createPostgresMcpSessionStore = ({
     },
     get: async (id) => {
       const current = now();
-      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit`, [
+      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit, can_elicit_url`, [
         id,
         current.toISOString(),
         new Date(current.getTime() + ttlMs).toISOString()
       ]);
       const row = result.rows[0];
-      return row === undefined ? null : { canElicit: row.can_elicit };
+      return row === undefined ? null : {
+        canElicit: row.can_elicit,
+        canElicitUrl: row.can_elicit_url
+      };
     }
   };
 };
@@ -1571,5 +1795,6 @@ export {
   createMcpClient,
   createMcpAuthorizationRequest,
   McpClientError,
+  MCP_LATEST_PROTOCOL_VERSION,
   FEEDBACK_INSTRUCTIONS
 };

package/dist/manifest.js

@@ -5916,6 +5916,14 @@ var serializedTool = Type.Object({
 });
 var manifestSchema = Type.Object({
   contract: Type.Union([Type.Literal(1), Type.Literal(2)]),
+  discovery: Type.Optional(Type.Object({
+    audiences: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    certificationUrl: Type.Optional(Type.String()),
+    intents: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    keywords: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    protocols: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    url: Type.Optional(Type.String())
+  })),
   identity: Type.Object({
     accent: Type.Optional(Type.String({ pattern: "^#[0-9a-fA-F]{3,8}$" })),
     category: Type.String({ minLength: 1 }),

package/dist/src/client.d.ts

@@ -34,10 +34,21 @@ export type McpClientOptions = {
 };
 export type McpRemoteTool = {
     annotations?: McpToolAnnotations;
+    coaz?: boolean;
     description?: string;
     inputSchema?: Record<string, unknown>;
     name: string;
     outputSchema?: Record<string, unknown>;
+    taskSupport?: "forbidden" | "optional" | "required";
+};
+export type McpRemoteTask = {
+    createdAt: string;
+    lastUpdatedAt: string;
+    pollInterval?: number;
+    status: "working" | "input_required" | "completed" | "failed" | "cancelled";
+    statusMessage?: string;
+    taskId: string;
+    ttl: number | null;
 };
 export type McpInitializeResult = {
     capabilities?: Record<string, unknown>;
@@ -51,7 +62,14 @@ export type McpInitializeResult = {
 };
 export type McpClient = {
     callTool: (name: string, args?: unknown) => Promise<McpToolResult>;
+    callToolAsTask: (name: string, args?: unknown, options?: {
+        ttl?: number;
+    }) => Promise<McpRemoteTask>;
+    cancelTask: (taskId: string) => Promise<McpRemoteTask>;
+    getTask: (taskId: string) => Promise<McpRemoteTask>;
+    getTaskResult: (taskId: string) => Promise<McpToolResult>;
     initialize: () => Promise<McpInitializeResult>;
+    listTasks: () => Promise<McpRemoteTask[]>;
     listResources: () => Promise<unknown[]>;
     listTools: () => Promise<McpRemoteTool[]>;
     ping: () => Promise<void>;

package/dist/src/dispatch.d.ts

@@ -4,7 +4,10 @@ import type { McpServerConfig } from "./types";
  *  Only elicitation uses it; without it the dispatcher is exactly as stateless
  *  as it was. */
 export type McpDispatchContext = {
+    protocolVersion?: string;
+    requestSignal?: AbortSignal;
     sessionId?: string | null;
     sessions?: SessionRegistry;
 };
+export declare const MCP_LATEST_PROTOCOL_VERSION: "2025-11-25";
 export declare const dispatchMcp: <Caller>(config: McpServerConfig<Caller>, caller: Caller, scopes: string[], message: unknown, context?: McpDispatchContext) => Promise<Response>;

package/dist/src/index.d.ts

@@ -31,9 +31,9 @@
  * depends on a model.
  */
 export { verifyBearer, type BearerResult, type BearerVerifier, type VerifiedJwt, type VerifyBearerConfig, } from "./auth";
-export { createMcpClient, McpClientError, type McpClient, type McpClientOptions, type McpInitializeResult, type McpRemoteTool, } from "./client";
+export { createMcpClient, McpClientError, type McpClient, type McpClientOptions, type McpInitializeResult, type McpRemoteTask, type McpRemoteTool, } from "./client";
 export * from "./oauth";
-export { dispatchMcp, type McpDispatchContext } from "./dispatch";
+export { dispatchMcp, MCP_LATEST_PROTOCOL_VERSION, type McpDispatchContext, } from "./dispatch";
 export { FEEDBACK_INSTRUCTIONS, feedbackTools, type McpFeedbackRating, type McpFeedbackReport, type McpFeedbackStore, type McpProblemReport, } from "./feedback";
 export { createMcpHandler } from "./handler";
 export { metadataPathFor, protectedResourceMetadata, type ProtectedResourceMetadata, } from "./metadata";
@@ -41,4 +41,4 @@ export { mcpServer } from "./server";
 export { createSessionRegistry, type SessionRegistry } from "./sessions";
 export { createMemoryMcpTaskStore, publicMcpTask } from "./tasks";
 export { createPostgresMcpSessionStore, createPostgresMcpTaskStore, mcpPostgresSchemaSql, type McpSqlClient, type McpSqlResult, } from "./postgres";
-export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTask, McpTaskStatus, McpTaskStore, McpTasksOptions, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";
+export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpFormElicitationRequest, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTask, McpTaskStatus, McpTaskStore, McpTasksOptions, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, McpUrlElicitationRequest, } from "./types";

package/dist/src/sessions.d.ts

@@ -8,10 +8,11 @@ export declare const createSessionRegistry: (options?: {
 }) => {
     ready: Promise<void>;
     close: () => Promise<void>;
-    create: (canElicit: boolean) => Promise<string>;
+    create: (canElicit: boolean, canElicitUrl?: boolean) => Promise<string>;
     drop: (id: string) => Promise<void>;
     get: (id: string | null) => Promise<{
         canElicit: boolean;
+        canElicitUrl?: boolean;
     } | null>;
     /** The client answered. If the call that asked is running HERE, resolve it.
      *  If not, put the answer on the bus so the instance that is waiting can —

package/dist/src/tasks.d.ts

@@ -1,14 +1,11 @@
 import type { McpTask, McpTaskStore } from "./types";
 export declare const createMemoryMcpTaskStore: () => McpTaskStore;
 export declare const publicMcpTask: ({ authorizationKey, ...task }: McpTask) => {
+    ttl: number | null;
+    pollInterval?: number | undefined;
     createdAt: string;
-    error?: Record<string, unknown>;
-    inputRequests?: Record<string, unknown>;
     lastUpdatedAt: string;
-    pollIntervalMs?: number;
-    result?: Record<string, unknown>;
     status: import("./types").McpTaskStatus;
     statusMessage?: string;
     taskId: string;
-    ttlMs: number | null;
 };

package/dist/src/types.d.ts

@@ -49,10 +49,18 @@ export type McpToolReturn = McpContent[] | McpToolResult | string;
  *  arrays are not allowed by the spec.
  *
  *  Servers MUST NOT elicit sensitive information (spec, Security). */
-export type McpElicitationRequest = {
+export type McpFormElicitationRequest = {
     message: string;
+    mode?: "form";
     requestedSchema: Record<string, unknown>;
 };
+export type McpUrlElicitationRequest = {
+    elicitationId: string;
+    message: string;
+    mode: "url";
+    url: string;
+};
+export type McpElicitationRequest = McpFormElicitationRequest | McpUrlElicitationRequest;
 /** What came back. `unsupported` is ours, not the spec's: it is what you get
  *  when the client never declared the elicitation capability, so a tool can
  *  fall back instead of pretending the user declined. */
@@ -78,12 +86,15 @@ export type McpElicitAnswer = {
 export type McpSessionStore = {
     create: (session: {
         canElicit: boolean;
+        canElicitUrl?: boolean;
     }) => Promise<string> | string;
     drop: (id: string) => Promise<void> | void;
     get: (id: string) => Promise<{
         canElicit: boolean;
+        canElicitUrl?: boolean;
     } | null> | {
         canElicit: boolean;
+        canElicitUrl?: boolean;
     } | null;
 };
 /** How an answer reaches the instance that asked the question. The tool call
@@ -102,6 +113,8 @@ export type McpToolCallContext = {
     /** True when this client can actually show the user a form. Check it before
      *  designing a flow around elicit(). */
     canElicit: boolean;
+    /** True only when the client negotiated secure URL-mode elicitation. */
+    canElicitUrl: boolean;
     /** Ask the user a question and wait for the answer. Resolves to
      *  `{action:"unsupported"}` immediately when the client can't elicit, and to
      *  `{action:"cancel"}` if they never answer. */
@@ -110,6 +123,9 @@ export type McpToolCallContext = {
 /** One callable tool. `inputSchema` is a JSON Schema object. */
 export type McpTool = {
     annotations?: McpToolAnnotations;
+    /** OpenID AuthZEN COAZ opt-in marker. When true, inputSchema MUST carry an
+     *  `x-coaz-mapping`; hosts should evaluate it before invoking the handler. */
+    coaz?: boolean;
     /** Enforceable semantic effects from manifest contract 2. A tool carrying
      *  this is hidden unless the server configures `agency`. */
     authorization?: ToolAuthorization;
@@ -123,6 +139,9 @@ export type McpTool = {
     mayElicit?: boolean;
     /** JSON Schema for `structuredContent`, advertised on `tools/list`. */
     outputSchema?: Record<string, unknown>;
+    /** MCP 2025-11-25 task augmentation support for this tool. Omitted means
+     *  forbidden, as required by the specification. */
+    taskSupport?: "forbidden" | "optional" | "required";
     /** If set, the tool is only listed and callable when the caller's scopes
      *  include this. Tools without a scope are always available. Fails closed:
      *  a scoped tool is hidden when the caller's scopes are unknown. */
@@ -195,6 +214,11 @@ export type McpTask = {
 export type McpTaskStore = {
     cancel: (taskId: string) => Promise<void> | void;
     get: (taskId: string) => Promise<McpTask | null> | McpTask | null;
+    /** List only tasks owned by this authorization context, newest first. */
+    list: (authorizationKey: string, options: {
+        limit: number;
+        offset: number;
+    }) => Promise<McpTask[]> | McpTask[];
     save: (task: McpTask) => Promise<void> | void;
     update: (taskId: string, update: Partial<Omit<McpTask, "authorizationKey" | "createdAt" | "taskId">>) => Promise<McpTask | null> | McpTask | null;
 };
@@ -206,6 +230,8 @@ export type McpTasksOptions<Caller> = {
         task: McpTask;
     }) => Promise<void> | void;
     pollIntervalMs?: number;
+    /** Maximum tasks returned by one tasks/list page (default 50, max 100). */
+    listPageSize?: number;
     shouldCreate: (context: {
         args: unknown;
         caller: Caller;
@@ -295,7 +321,8 @@ export type McpServerConfig<Caller> = {
     /** Protocol versions this endpoint accepts; the first is the preferred one.
      *  Defaults to the versions this package knows. */
     supportedProtocols?: string[];
-    /** Final SEP-2663 `io.modelcontextprotocol/tasks` extension support. */
+    /** MCP 2025-11-25 native tasks plus legacy SEP-2663 compatibility for
+     *  older negotiated protocol versions. */
     tasks?: McpTasksOptions<Caller>;
     /** Build the tool registry for this caller. Called once per request. */
     tools: (ctx: McpToolContext<Caller>) => McpToolRegistry | Promise<McpToolRegistry>;

package/package.json

@@ -11,8 +11,8 @@
     "elysia": ">=1.1.0"
   },
   "dependencies": {
-    "@absolutejs/agency": "^0.3.0",
-    "@absolutejs/manifest": "^0.2.0",
+    "@absolutejs/agency": "^0.4.0",
+    "@absolutejs/manifest": "^0.3.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "license": "BUSL-1.1",
@@ -58,5 +58,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.8.0"
+  "version": "0.10.0"
 }