feat(apps): negotiated app-rendered form elicitations

README.md

@@ -140,6 +140,7 @@ Each config below is a ready-made server for exercising one feature by hand. Loa
 | Config                                    | Demonstrates                                       | Issue                                                                  |
 | ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
 | `mcp-app-http.json` **(legacy era)**      | An MCP App (UI resource + app tool) in the Apps tab | [#1859](https://github.com/modelcontextprotocol/inspector/issues/1859) |
+| `app-elicitation-http.json` **(legacy era)** | An MCP App rendering a form elicitation           | [#1854](https://github.com/modelcontextprotocol/inspector/issues/1854) |
 | `modern-mrtr-http.json`                   | A single MRTR round-trip                           | —                                                                      |
 | `mrtr-showcase-http.json`                 | Every MRTR preset in one server                    | [#1860](https://github.com/modelcontextprotocol/inspector/issues/1860) |
 | `modern-network-http.json`                | Network tab: `Mcp-*` headers + error taxonomy      | [#1628](https://github.com/modelcontextprotocol/inspector/issues/1628) |
@@ -162,6 +163,25 @@ Open the Apps tab, select `mcp_app_demo`, give it a title and click **Open App**
 
 For the scripted version of the same flow (`--app-info` probe → deep link → rendered widget), see [Reviewing an MCP App](./docs/mcp-app-review.md).
 
+#### App-rendered form elicitations
+
+`app-elicitation-http.json` serves `app_choose_option` alongside the `choose_option_app` UI resource (`ui://demo/choose-option.html`). The tool sends a completely ordinary form `elicitation/create` — the only thing added is `_meta.ui.resourceUri` naming that app. Plain streamable-HTTP; connect with the **default (legacy)** protocol era.
+
+Run `app_choose_option` from the Tools tab. The server's app renders in a modal instead of the built-in elicitation form, and clicking **Option A**, **Decline**, or **Cancel** returns the standard `ElicitResult` straight to the server, which echoes it into the tool result.
+
+App rendering is selected only when **all four** conditions hold ([#1854](https://github.com/modelcontextprotocol/inspector/issues/1854), per [ext-apps#733](https://github.com/modelcontextprotocol/ext-apps/pull/733) / SEP-3118):
+
+1. the client advertises `elicitation.form`;
+2. the client advertises `extensions["io.modelcontextprotocol/ui"].mimeTypes` including `text/html;profile=mcp-app`;
+3. **both** the client and the server advertise the nested `elicitation` setting on that same extension;
+4. the request carries a valid absolute `ui://` URI in `_meta.ui.resourceUri`.
+
+Only the **web** client advertises the nested client-side setting, and only because it has a sandbox renderer to back it; the CLI and TUI advertise the MIME type (they know what an App is) but never claim they can resolve an elicitation through one, so the same server falls back to their native prompts. Turning **Server Settings → Advertised Extensions → MCP Apps UI** off, or turning form elicitation off, removes the claim on web too.
+
+Everything else falls back to the built-in elicitation form, by design: metadata that is absent or not an absolute `ui://` URI, a resource that fails to load, a sandbox or bridge that fails to initialize, an app that did not advertise `elicitation`, a request that times out, and any result that is not a valid `ElicitResult` for the requested schema. An explicit `decline` or `cancel` is **not** a fallback — it is a completed elicitation and goes back to the server as-is.
+
+> The Inspector speaks the ext-apps#733 wire protocol but does not yet consume its helpers: the released `@modelcontextprotocol/ext-apps` (1.7.5) predates that PR. `core/mcp/appElicitation.ts` and `clients/web/src/components/elements/AppRenderer/requestAppElicitation.ts` mirror it exactly and are marked for deletion in favour of the package's own exports once a release containing it ships.
+
 #### MRTR
 
 `modern-mrtr-http.json` serves the `mrtr_confirm` tool (preset `mrtr_confirm`, `createMrtrTool`) over the modern leg. Its handler returns `inputRequired(...)` embedding a form elicitation, so invoking it produces a real round-trip: `input_required` → the client fulfils the embedded elicitation and retries with a new id → `complete`.
@@ -343,7 +363,7 @@ Each client self-validates from its own folder; the root scripts chain them. The
 | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `npm run validate`                  | Runs the three durable guards first — `verify:format-coverage` (every tracked source file is format-gated), `verify:typecheck-coverage` (every one lands in a tsconfig project), `verify:dep-lockstep` (no dependency reaching one `tsc` program from two installs skews across them) — then `test:scripts` (the guards' own parser unit tests), then `validate:core` (the shared `core/` `format:check` + `lint` gate), then per client: `format:check` + `lint` + **`typecheck`** (cli/tui/launcher; web typechecks via `tsc -b` inside its `build`) + `build` + fast unit tests. The quick inner-loop check.                                                                                                                                                                                                                                                                                                                                                                                |
 | `npm run coverage`                  | The **per-file ≥90% gate** (lines/statements/functions/branches) under v8 instrumentation, per client. CI-enforced. For web this also runs the integration project and covers the shared `core/` runtime (including `core/json` and `core/client`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `npm run smoke`                     | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web), plus two headless-Chromium smokes: a boot smoke that runs the prod web bundle and asserts a clean first render (no uncaught error — sync exception or unhandled rejection, how a Node built-in reaching the browser bundle manifests), and an **MCP Apps** smoke (`smoke:web:app`) that drives connect → open app → `data-app-status="ready"` against a composable App server, covering the sandbox proxy and UI-protocol bridge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `npm run smoke`                     | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web), plus three headless-Chromium smokes: a boot smoke that runs the prod web bundle and asserts a clean first render (no uncaught error — sync exception or unhandled rejection, how a Node built-in reaching the browser bundle manifests), and an **MCP Apps** smoke (`smoke:web:app`) that drives connect → open app → `data-app-status="ready"` against a composable App server, covering the sandbox proxy and UI-protocol bridge, and an **app-rendered elicitation** smoke (`smoke:web:elicit`) that drives one end to end — call the tool, answer inside the sandboxed app, see the app's `ElicitResult` reach the server — and then the same tool against a server that never advertised the capability, which must fall back to the native elicitation form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `npm run verify:build-gate`         | Runs a real `vite build` with a Node built-in forced into the browser graph and asserts the build **fails** via the #1769 gate (which turns Vite's browser-externalization warning into a hard error). Guards against the warning phrasing drifting in a Vite bump and silently disabling the gate. Part of `npm run ci`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `npm run verify:format-coverage`    | Parses the `format:check` globs out of every `package.json` (only those reachable from `validate`), enumerates all tracked source files, and **fails** listing any not covered by a glob — the durable guard for the "every first-party source file is format-gated" invariant (#1792). Runs first in `validate`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `npm run test:scripts`              | Table-driven unit tests (`node --test`) for the guard's own pure parsers (`scripts/lib/npm-scripts.mjs`, `scripts/lib/tsc-program.mjs` + the exported helpers of `verify-typecheck-coverage.mjs` and `verify-dep-lockstep.mjs`), one case per rule they encode, plus `scripts/lib/resolve-node-bin.test.mjs` — the cross-platform bin resolver (#1939), pinned against the real `bin`/`exports` shapes of the packages the scripts actually spawn. Runs in `validate` — and `verify:typecheck-coverage` guards *this* gate in turn (reachable from `validate`, non-empty test set, every test file matched by the `test:scripts` glob), since `node --test` silently skips a file its glob misses and still exits 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

clients/web/README.md

@@ -85,6 +85,15 @@ The Apps screen exposes a small, stable set of `data-testid` / `data-*` attribut
 | `data-testid="apps-messages"` | messages panel | `ui/message` submissions from the running view. |
 | `data-testid="apps-logs"` | app-logs panel | `notifications/message` log entries (default-expanded). |
 
+App-rendered **elicitations** (#1854) render through the same `AppRenderer` but outside the Apps screen — one modal per request, from `AppElicitationHost` — and carry their own pair:
+
+| Attribute | Where | Meaning |
+| --- | --- | --- |
+| `data-testid="app-elicitation"` | the elicitation modal | One per in-flight app-rendered elicitation. **Absent** means the request was answered by the native elicitation form instead, which is what a driver asserts to prove the negotiation gate held. |
+| `data-app-elicitation-status` | on `app-elicitation` | The same `AppRendererStatus` for that modal's app. `ready` is when the host forwards the `elicitation/create` through its bridge. |
+
+`scripts/smoke-web-elicitation.mjs` drives both halves against the public fixture (`test-servers/configs/app-elicitation-http.json` and its `-native-` sibling).
+
 The renderer lifecycle itself is `AppRendererStatus` (`loading` | `ready` | `error`) reported via `AppRenderer`'s `onAppStatusChange`; the screen maps it to `data-app-status`. Resource-read failures (malformed/404 UI resource) are surfaced as a toast via the bridge factory's `onResourceError`; because the app never reaches `ready` in that case, a driver times out on `data-app-status` and reads the toast.
 
 ## Deep-link auto-connect

clients/web/src/App.tsx

@@ -1,4 +1,11 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import {
   Anchor,
   Box,
@@ -134,6 +141,8 @@ import {
 import { clearScrollMemory } from "./hooks/useScrollMemory";
 import type { AppRendererHandle } from "./components/elements/AppRenderer/AppRenderer";
 import { createAppBridgeFactory } from "./components/elements/AppRenderer/createAppBridgeFactory";
+import { AppElicitationHost } from "./components/elements/AppElicitation/AppElicitationHost";
+import { AppElicitationController } from "./lib/appElicitationController";
 import type { LogEntryData } from "./components/elements/LogEntry/LogEntry";
 import {
   ServerConfigModal,
@@ -792,6 +801,70 @@ function App() {
     [inspectorClient],
   );
 
+  // App-rendered form elicitations (#1854). The controller is created once and
+  // handed to every InspectorClient at construction — its `render` is what opts
+  // this client into advertising the nested MCP Apps `elicitation` capability,
+  // which is why only the web client (the one with a sandbox) claims it.
+  const appElicitationControllerRef = useRef<AppElicitationController>(null);
+  appElicitationControllerRef.current ??= new AppElicitationController();
+  const appElicitationController = appElicitationControllerRef.current;
+  const appElicitations = useSyncExternalStore(
+    appElicitationController.subscribe,
+    appElicitationController.getEntries,
+  );
+  // A SECOND factory, differing from `sandboxBridgeFactory` only in that it
+  // advertises `hostCapabilities.elicitation`. An App-tool frame is never handed
+  // an elicitation, so telling those apps otherwise would be a false claim.
+  const elicitationBridgeFactory = useMemo(
+    () =>
+      createAppBridgeFactory({
+        advertiseElicitation: true,
+        getClient: () => inspectorClient?.getAppRendererClient() ?? null,
+        readResource: async (uri) => {
+          if (!inspectorClient) throw new Error("No MCP client connected.");
+          const invocation = await inspectorClient.readResource(uri);
+          return invocation.result;
+        },
+        // Unlike the Apps tab there is no persistent surface to show the
+        // failure on — the modal is about to be replaced by the native form —
+        // so the toast is the only place the user learns why.
+        onResourceError: (err) => {
+          notifications.show({
+            title: "Elicitation app failed to load",
+            message: err.message,
+            color: "red",
+          });
+        },
+      }),
+    [inspectorClient],
+  );
+  const handleAppElicitationSettle = useCallback(
+    (requestId: string, result: ElicitResult) => {
+      appElicitationController.settle(requestId, result);
+    },
+    [appElicitationController],
+  );
+  const handleAppElicitationFail = useCallback(
+    (requestId: string, error: Error) => {
+      appElicitationController.fail(requestId, error);
+    },
+    [appElicitationController],
+  );
+  // Request ownership must not cross connections. `elicitationBridgeFactory`
+  // resolves its client at call time, so an entry queued by a previous
+  // InspectorClient would otherwise be able to rebuild against the NEXT one and
+  // read (or answer) through a different server. Core aborts its own pending
+  // app requests during teardown, but that teardown is awaited asynchronously
+  // while the swap here is synchronous — so drop them on the swap instead of
+  // racing it. The one client alive at a time owns every live entry.
+  useEffect(() => {
+    return () => {
+      appElicitationController.failAll(
+        new Error("Connection replaced before the app answered"),
+      );
+    };
+  }, [appElicitationController, inspectorClient]);
+
   const [managedToolsState, setManagedToolsState] =
     useState<ManagedToolsState | null>(null);
   const [managedPromptsState, setManagedPromptsState] =
@@ -2410,6 +2483,11 @@ function App() {
         // Sampling / elicitation are on by default; keep the parameterized
         // options off until the UI grows the surface to render them.
         elicit: { form: true, url: true },
+        // Web only: hands form elicitations that name a `ui://` resource to the
+        // MCP App the server chose, and advertises the nested MCP Apps
+        // `elicitation` capability that makes a server willing to send one
+        // (#1854). The native elicitation queue stays the fallback.
+        appElicitation: appElicitationController.render,
         // Always advertise the roots capability (even with no configured
         // roots) so the server can issue roots/list and receive
         // roots/list_changed; the configured roots are the answer to
@@ -2511,6 +2589,7 @@ function App() {
       sessionStorageAdapter,
       onBeforeOAuthRedirect,
       clientConfig,
+      appElicitationController.render,
     ],
   );
 
@@ -4571,6 +4650,13 @@ function App() {
           onRefreshApps={onRefreshTools}
         />
       </Box>
+      <AppElicitationHost
+        entries={appElicitations}
+        sandboxPath={sandboxUrl}
+        bridgeFactory={elicitationBridgeFactory}
+        onSettle={handleAppElicitationSettle}
+        onFail={handleAppElicitationFail}
+      />
       <ServerConfigModal
         opened={configModal !== null}
         mode={configModal?.mode ?? "add"}