Refresh app elicitation for SDK 2 and extension-only specification

Author: krubenok

specification/draft/apps.mdx

@@ -2315,6 +2315,12 @@ extension, the standard MCP elicitation request and result, and the existing
 View↔Host JSON-RPC channel. It defines no new method, result, or extension
 identifier.
 
+This feature is specified entirely by MCP Apps. It uses core capability
+extension points and request metadata without changing the core MCP protocol.
+The MCP Apps bridge version is negotiated independently of the core version;
+app rendering also works with initialized sessions that deliver elicitations as
+direct server-to-client requests.
+
 #### Associating an App with an Elicitation
 
 The server attaches the app resource URI at `_meta.ui.resourceUri` on the

src/app-bridge.test.ts

@@ -233,6 +233,91 @@ describe("App <-> AppBridge integration", () => {
       });
     });
 
+    it.each(["decline", "cancel"] as const)(
+      "preserves the user's %s result",
+      async (action) => {
+        bridge = new AppBridge(createMockClient() as Client, testHostInfo, {
+          ...testHostCapabilities,
+          elicitation: {},
+        });
+        app.onelicitation = async () => ({ action });
+        await bridge.connect(bridgeTransport);
+        await app.connect(appTransport);
+        await expect(
+          bridge.requestElicitation({
+            message: "Choose",
+            requestedSchema: { type: "object", properties: {} },
+          }),
+        ).resolves.toEqual({ action });
+      },
+    );
+
+    it("keeps metadata and cancellation bound to the bridge request", async () => {
+      bridge = new AppBridge(createMockClient() as Client, testHostInfo, {
+        ...testHostCapabilities,
+        elicitation: {},
+      });
+      const controller = new AbortController();
+      let received!: () => void;
+      const started = new Promise<void>((resolve) => {
+        received = resolve;
+      });
+      let cancelled!: () => void;
+      const aborted = new Promise<void>((resolve) => {
+        cancelled = resolve;
+      });
+      app.onelicitation = async (params, ctx) => {
+        expect(params._meta?.ui).toEqual({
+          resourceUri: "ui://delivery/choose.html",
+        });
+        ctx.mcpReq.signal.addEventListener("abort", cancelled, { once: true });
+        received();
+        await aborted;
+        return { action: "cancel" };
+      };
+      await bridge.connect(bridgeTransport);
+      await app.connect(appTransport);
+      // SDK 2.0.0 ignores cancellation for request ID 0. Use a nonzero
+      // request ID here to test propagation independently of that SDK bug.
+      await bridge.request({ method: "ping" });
+      const pending = bridge.requestElicitation(
+        {
+          message: "Choose",
+          requestedSchema: { type: "object", properties: {} },
+          _meta: { ui: { resourceUri: "ui://delivery/choose.html" } },
+        },
+        { signal: controller.signal },
+      );
+      const rejection = pending.then(
+        () => {
+          throw new Error("Expected cancellation");
+        },
+        () => {},
+      );
+      await started;
+      controller.abort("test cancellation");
+      await rejection;
+      await aborted;
+    });
+
+    it("rejects URL-mode requests before forwarding them", async () => {
+      bridge = new AppBridge(createMockClient() as Client, testHostInfo, {
+        ...testHostCapabilities,
+        elicitation: {},
+      });
+      app.onelicitation = async () => ({ action: "cancel" });
+      await bridge.connect(bridgeTransport);
+      await app.connect(appTransport);
+      expect(() =>
+        bridge.requestElicitation({
+          mode: "url",
+          message: "Open",
+          elicitationId: "test",
+          url: "https://example.com",
+        }),
+      ).toThrow("form-mode");
+    });
+
     it("fails closed when the app did not advertise elicitation", async () => {
       bridge = new AppBridge(createMockClient() as Client, testHostInfo, {
         ...testHostCapabilities,

src/app-bridge.ts

@@ -583,8 +583,13 @@ export class AppBridge extends Protocol<BaseContext> {
    * @internal
    */
   protected assertCapabilityForMethod(method: string): void {
-    if (method === "elicitation/create" && !this._appCapabilities?.elicitation) {
-      throw new Error(`App does not support elicitation capability (required for ${method})`);
+    if (
+      method === "elicitation/create" &&
+      !this._appCapabilities?.elicitation
+    ) {
+      throw new Error(
+        `App does not support elicitation capability (required for ${method})`,
+      );
     }
   }
 
@@ -634,7 +639,10 @@ export class AppBridge extends Protocol<BaseContext> {
    *
    * Hosts should call this only from the core MCP client's handler for the
    * originating `elicitation/create` request. The returned value is the
-   * standard MCP `ElicitResult` and can be returned directly to the server.
+   * standard MCP `ElicitResult`. Before returning an accepted result to the
+   * server, hosts must validate its content against `params.requestedSchema`.
+   * Invalid results should fall back to native form rendering; explicit
+   * `decline` and `cancel` results must be preserved.
    */
   requestElicitation(
     params: ElicitRequest["params"],
@@ -654,8 +662,8 @@ export class AppBridge extends Protocol<BaseContext> {
     }
     return this.request(
       { method: "elicitation/create", params },
+      ElicitResultSchema,
       options,
-    ).then((result) => ElicitResultSchema.parse(result)
     );
   }
 

src/app.ts

@@ -8,6 +8,8 @@ import {
   type CreateMessageRequest,
   type CreateMessageResult,
   type CreateMessageResultWithTools,
+  type ElicitRequest,
+  type ElicitResult,
   type Implementation,
   type ListResourcesRequest,
   type ListResourcesResult,
@@ -21,7 +23,11 @@ import {
   type ToolListChangedNotification,
   type Transport,
 } from "@modelcontextprotocol/client";
-import { ElicitRequestParamsSchema, ElicitResultSchema, EmptyResultSchema } from "@modelcontextprotocol/core";
+import {
+  ElicitRequestParamsSchema,
+  ElicitResultSchema,
+  EmptyResultSchema,
+} from "@modelcontextprotocol/core";
 export { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "./constants.js";
 import { EventDispatcher, MethodRegistry } from "./events.js";
 import {
@@ -34,7 +40,7 @@ export type {
   LegacyNotificationHandler,
   LegacyNotificationHandlerSetter,
   LegacyRequestHandler,
-  LegacyBaseContext,
+  LegacyRequestHandlerExtra,
   LegacyRequestHandlerSetter,
 } from "./legacy-handlers.js";
 export { EventDispatcher } from "./events.js";
@@ -198,10 +204,10 @@ export type AppToolCallback<
 > = In extends StandardSchemaV1
   ? (
       args: StandardSchemaV1.InferOutput<In>,
-      extra: BaseContext,
+      extra: RequestHandlerExtra,
     ) => AppToolResult<Out> | Promise<AppToolResult<Out>>
   : (
-      extra: BaseContext,
+      extra: RequestHandlerExtra,
     ) => AppToolResult<Out> | Promise<AppToolResult<Out>>;
 
 /**
@@ -224,7 +230,7 @@ export type RegisteredAppTool = {
   /** @internal */
   handler: (
     args: unknown,
-    extra: BaseContext,
+    extra: RequestHandlerExtra,
   ) => Promise<CallToolResult>;
 };
 
@@ -1072,7 +1078,7 @@ export class App extends Protocol<BaseContext> {
    */
   private _onteardown?: (
     params: McpUiResourceTeardownRequest["params"],
-    extra: BaseContext,
+    extra: RequestHandlerExtra,
   ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>;
   get onteardown() {
     return this._onteardown;
@@ -1081,7 +1087,7 @@ export class App extends Protocol<BaseContext> {
     callback:
       | ((
           params: McpUiResourceTeardownRequest["params"],
-          extra: BaseContext,
+          extra: RequestHandlerExtra,
         ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>)
       | undefined,
   ) {
@@ -1110,7 +1116,7 @@ export class App extends Protocol<BaseContext> {
    */
   private _onelicitation?: (
     params: ElicitRequest["params"],
-    extra: BaseContext,
+    extra: RequestHandlerExtra,
   ) => ElicitResult | Promise<ElicitResult>;
   get onelicitation() {
     return this._onelicitation;
@@ -1119,7 +1125,7 @@ export class App extends Protocol<BaseContext> {
     callback:
       | ((
           params: ElicitRequest["params"],
-          extra: BaseContext,
+          extra: RequestHandlerExtra,
         ) => ElicitResult | Promise<ElicitResult>)
       | undefined,
   ) {
@@ -1132,15 +1138,19 @@ export class App extends Protocol<BaseContext> {
     if (callback && !this._appCapabilities.elicitation && !this.transport) {
       this._appCapabilities.elicitation = {};
     }
-    this.replaceRequestHandler("elicitation/create", { params: ElicitRequestParamsSchema, result: ElicitResultSchema }, (params, extra) => {
-      if (!this._onelicitation) {
-        throw new Error("No onelicitation handler set");
-      }
-      if (params.mode !== undefined && params.mode !== "form") {
-        throw new Error("MCP Apps only support form-mode elicitations");
-      }
-      return this._onelicitation(params, extra);
-    });
+    this.replaceRequestHandler(
+      "elicitation/create",
+      { params: ElicitRequestParamsSchema, result: ElicitResultSchema },
+      (params, extra) => {
+        if (!this._onelicitation) {
+          throw new Error("No onelicitation handler set");
+        }
+        if (params.mode !== undefined && params.mode !== "form") {
+          throw new Error("MCP Apps only support form-mode elicitations");
+        }
+        return this._onelicitation(params, extra);
+      },
+    );
   }
 
   /**
@@ -1173,7 +1183,7 @@ export class App extends Protocol<BaseContext> {
    */
   private _oncalltool?: (
     params: CallToolRequest["params"],
-    extra: BaseContext,
+    extra: RequestHandlerExtra,
   ) => Promise<CallToolResult>;
   get oncalltool() {
     return this._oncalltool;
@@ -1182,7 +1192,7 @@ export class App extends Protocol<BaseContext> {
     callback:
       | ((
           params: CallToolRequest["params"],
-          extra: BaseContext,
+          extra: RequestHandlerExtra,
         ) => Promise<CallToolResult>)
       | undefined,
   ) {
@@ -1240,7 +1250,7 @@ export class App extends Protocol<BaseContext> {
    */
   private _onlisttools?: (
     params: ListToolsRequest["params"],
-    extra: BaseContext,
+    extra: RequestHandlerExtra,
   ) => Promise<ListToolsResult>;
   get onlisttools() {
     return this._onlisttools;
@@ -1249,7 +1259,7 @@ export class App extends Protocol<BaseContext> {
     callback:
       | ((
           params: ListToolsRequest["params"],
-          extra: BaseContext,
+          extra: RequestHandlerExtra,
         ) => Promise<ListToolsResult>)
       | undefined,
   ) {
@@ -1297,7 +1307,9 @@ export class App extends Protocol<BaseContext> {
         return;
       case "elicitation/create":
         if (!this._appCapabilities.elicitation) {
-          throw new Error(`App does not support elicitation capability (required for ${method})`);
+          throw new Error(
+            `App does not support elicitation capability (required for ${method})`,
+          );
         }
         return;
       default: