From 0e93b13426ac7535f9424f5d5986da520463322d Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 22:48:28 -0400
Subject: [PATCH 01/11] web: deep-link auto-connect + machine-readable
 connection status (#1576)

Closes #1576

Adds `?serverUrl=<url>&transport=http|sse&autoConnect=<token>` URL-driven
auto-connect so a driver can reach a connected inspector with one navigate.

- `clients/web/src/utils/deepLink.ts`: `parseDeepLink()` (http(s)-only
  serverUrl; `autoConnect` CSRF-gated on the per-launch API token),
  `deepLinkParseStatus()`, `deepLinkConfigEquals()`, `DEEP_LINK_SERVER_ID`
  (stable `deep-link` row so reloads reconnect to the same catalog row).
- App.tsx: ensure/connect effects (two-phase upsert-then-connect against the
  hydrated list), `serversRef` read in `onToggleConnection`,
  `connectErrorMessage` / `recordConnectError` recording connection-level
  failures.
- InspectorView header: `data-testid="connection-status"` with `data-status`,
  `data-error-message`, `data-deeplink` so drivers can `waitForSelector` and
  read failure reasons without scraping toasts.
- Docs: deep-link scheme + `data-*` contract in clients/web/README.md.

Re-implemented informed by PR #1510 (33fac3f); adapted to the post-#1417
lifted-tab architecture and dropping the non-existent `normalizeServerUrl`
import in favor of `URL.href` canonicalization. Coverage gate green
(deepLink.ts 97.8/95.1/100/97.4).

Part of the #1579 decomposition (Wave 4).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/web/README.md                         |  25 +++
 clients/web/src/App.tsx                       | 106 +++++++++-
 .../InspectorView/InspectorView.test.tsx      |  36 ++++
 .../views/InspectorView/InspectorView.tsx     |  32 ++-
 clients/web/src/utils/deepLink.test.ts        | 199 ++++++++++++++++++
 clients/web/src/utils/deepLink.ts             | 180 ++++++++++++++++
 6 files changed, 575 insertions(+), 3 deletions(-)
 create mode 100644 clients/web/src/utils/deepLink.test.ts
 create mode 100644 clients/web/src/utils/deepLink.ts

diff --git a/clients/web/README.md b/clients/web/README.md
index 329317e4c..346371349 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -71,6 +71,31 @@ The Apps screen exposes a small, stable set of `data-testid` / `data-*` attribut
 
 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
+
+A driver (launcher, CLI `--print-handoff`, CI review harness) can reach a **connected** inspector with a single navigate by encoding the target in the URL query string. Parsing + security gating live in `src/utils/deepLink.ts` (`parseDeepLink`), and a returned `DeepLink` is proof the link passed validation.
+
+```
+http://127.0.0.1:6274/?serverUrl=<url>&transport=http|sse&autoConnect=<token>
+```
+
+| Param | Meaning |
+| --- | --- |
+| `serverUrl` | The MCP server URL. Restricted to `http:` / `https:` (a crafted `javascript:` / `data:` / `file:` value is rejected). Canonicalized via `URL.href` so it matches the OAuth store's key form. |
+| `transport` | `http` (streamable-HTTP, the default) or `sse`. Unknown values fall back to `http`. |
+| `autoConnect` | **CSRF gate.** Must equal the per-launch `MCP_INSPECTOR_API_TOKEN`. The token is random per launch and only known to whatever started the server, so a third-party-minted link cannot satisfy it — this is the same exposure surface as the existing `?MCP_INSPECTOR_API_TOKEN=` param. Without a match the link is ignored. |
+
+The deep link upserts a stable `deep-link` catalog row (so a reload reconnects to the same row instead of accumulating duplicates) and connects. Connection-level outcomes are surfaced on the `AppShell.Header` as a machine-readable contract, so a driver can `waitForSelector` and read the failure reason without scraping a transient toast:
+
+| Attribute | Where | Meaning |
+| --- | --- | --- |
+| `data-testid="connection-status"` | header | The element carrying the attributes below. |
+| `data-status` | on `connection-status` | The live `ConnectionStatus` (`disconnected` → `connecting` → `connected` / `error`). Poll for `connected`. |
+| `data-error-message` | on `connection-status` | Why the last connect failed (handshake error, OAuth-start failure, deep-link automation failure); absent when there is no error. |
+| `data-deeplink` | on `connection-status` | `parsed` (a valid deep link drove this load), `rejected` (deep-link params present but the token/serverUrl gate failed), or `none`. Lets a driver distinguish "no deep link" from "rejected" — both otherwise leave `data-status` idle. |
+
+The `openApp` / `appArgs` / `autoOpen` params extend this to land on a rendered MCP App; see the [MCP Apps screen automation contract](#mcp-apps-screen-automation-contract) above for the app-side `data-*` signals.
+
 ## Theme (`src/theme/`)
 
 Each customized Mantine component has a `Theme<Name>.ts` file (`Button.ts`, `Text.ts`, …, ~21 total) exporting a `Theme<Name>` constant; the barrel `index.ts` re-exports them and `theme.ts` assembles the `MantineProvider` theme. Theme files hold app-wide defaults and **variants** (flat CSS-in-JS); only pseudo-selectors, nested child selectors, keyframes, and native-HTML styling belong in `App.css`. Element components import from `@mantine/core` (never from `theme/`) — the theme layer is applied transparently by the provider.
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 255d71e31..5eb7f760f 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -154,6 +154,12 @@ import {
 } from "./components/groups/PendingClientRequestModal/PendingClientRequestModal";
 import { buildExportFilename, downloadJsonFile } from "./lib/downloadFile";
 import { INSPECTOR_SERVERS_TAB } from "./utils/inspectorTabs";
+import {
+  parseDeepLink,
+  deepLinkConfigEquals,
+  deepLinkParseStatus,
+} from "./utils/deepLink";
+import type { DeepLink, DeepLinkParseStatus } from "./utils/deepLink";
 import {
   applyOAuthResumeUi,
   buildTabUiSnapshot,
@@ -1347,6 +1353,36 @@ function App() {
     serversRef.current = servers;
   }, [activeServer, activeServerId, servers]);
 
+  // Last connection-level error message, surfaced as `data-error-message` on
+  // the InspectorView header so an automated driver can read *why* a connect
+  // failed without scraping a transient toast. Cleared on the next connect
+  // attempt and on successful connection.
+  const [connectErrorMessage, setConnectErrorMessage] = useState<
+    string | undefined
+  >(undefined);
+  // Named writer so a single call site can be extended later (e.g. telemetry)
+  // and the intent (record a connection-level failure) stays explicit.
+  const recordConnectError = useCallback((message: string) => {
+    setConnectErrorMessage(message);
+  }, []);
+
+  // Deep-link parameters parsed once from the initial URL. Security gating
+  // (auth-token match, http(s)-only serverUrl) happens inside `parseDeepLink`,
+  // so a `DeepLink` value here is already validated. The parse status is
+  // surfaced as `data-deeplink` so an automated driver can tell "no deep link"
+  // from "deep link present but rejected" — both leave `data-status` idle.
+  const [deepLink, deepLinkStatus] = useMemo<
+    [DeepLink | undefined, DeepLinkParseStatus]
+  >(() => {
+    /* v8 ignore next -- SSR guard: happy-dom always defines window in tests */
+    if (typeof window === "undefined") return [undefined, "none"];
+    const search = window.location.search;
+    const parsed = parseDeepLink(search, getAuthToken());
+    return [parsed, deepLinkParseStatus(search, parsed)];
+  }, []);
+  const deepLinkEnsureRef = useRef(false);
+  const deepLinkConnectRef = useRef(false);
+
   const showReAuthBanner = useCallback(
     (
       serverId: string,
@@ -2338,7 +2374,11 @@ function App() {
         return;
       }
 
-      const target = servers.find((s) => s.id === id);
+      // Read from the ref so a caller that already awaited an
+      // addServer/updateServer in the same async tick (e.g. the deep-link
+      // auto-connect IIFE) sees the freshly-mutated list, not the stale array
+      // captured by this callback's closure.
+      const target = serversRef.current.find((s) => s.id === id);
       if (!target) return;
 
       // Always rebuild the InspectorClient on a (re)connect so the latest
@@ -2354,6 +2394,9 @@ function App() {
       // the red border on the last-failed card is removed (#1621). If this
       // attempt also fails, the catch below re-sets it for this server.
       setFailedServerId(undefined);
+      // Clear the machine-readable connect error for the same reason; a fresh
+      // attempt starts from a clean `data-error-message`.
+      setConnectErrorMessage(undefined);
 
       connectStartRef.current = Date.now();
       try {
@@ -2432,6 +2475,7 @@ function App() {
             }
             const message =
               authErr instanceof Error ? authErr.message : String(authErr);
+            setConnectErrorMessage(message);
             notifications.show({
               title: `OAuth authorization failed for "${target.name}"`,
               message,
@@ -2446,6 +2490,7 @@ function App() {
         // "disconnected", and flag the card with a red border (#1621).
         setFailedServerId(id);
         const message = err instanceof Error ? err.message : String(err);
+        setConnectErrorMessage(message);
         notifications.show({
           title: `Failed to connect to "${target.name}"`,
           message,
@@ -2457,7 +2502,6 @@ function App() {
       activeServerId,
       connectionStatus,
       inspectorClient,
-      servers,
       setupClientForServer,
       prepareOAuthRedirect,
       finalizeExplicitDisconnect,
@@ -2473,6 +2517,61 @@ function App() {
     }
   }, [inspectorClient, finalizeExplicitDisconnect]);
 
+  // Deep-link auto-connect (the URL-driven case of #1183). `useServers`
+  // hydrates asynchronously (initial `servers` is `[]`), so this effect runs
+  // in two phases: first render attempts a one-shot `addServer` (a 409 means
+  // the row already exists on disk and hydration will surface it); a later
+  // render where `servers` actually contains the deep-link row then updates the
+  // URL if it has changed and connects. Connecting in the same closure as
+  // `addServer` would resolve against a stale (empty) `servers` and silently
+  // no-op. The OAuth callback path takes precedence; a deep link on
+  // `/oauth/callback` would be a misconfiguration, and the callback handler
+  // clears the URL.
+  useEffect(() => {
+    if (!deepLink) return;
+    if (window.location.pathname === OAUTH_CALLBACK_PATH) return;
+
+    const existing = servers.find((s) => s.id === deepLink.serverId);
+    if (!existing) {
+      if (deepLinkEnsureRef.current) return;
+      deepLinkEnsureRef.current = true;
+      void addServer(deepLink.serverId, deepLink.serverConfig).catch(() => {
+        // 409 = already on disk; hydration will surface it on a later render.
+      });
+      return;
+    }
+
+    if (deepLinkConnectRef.current) return;
+    deepLinkConnectRef.current = true;
+    void (async () => {
+      if (!deepLinkConfigEquals(existing.config, deepLink.serverConfig)) {
+        await updateServer(
+          deepLink.serverId,
+          deepLink.serverId,
+          deepLink.serverConfig,
+        );
+      }
+      if (activeServerId !== deepLink.serverId) {
+        await onToggleConnection(deepLink.serverId);
+      }
+    })().catch((err) => {
+      // Surface deep-link automation failures (updateServer 5xx, connect throw)
+      // on the machine-readable error attribute instead of dropping them. The
+      // toast still fires from inside `onToggleConnection` for the common
+      // cases; this catch covers the rest.
+      const message = err instanceof Error ? err.message : String(err);
+      recordConnectError(message);
+    });
+  }, [
+    deepLink,
+    servers,
+    activeServerId,
+    addServer,
+    updateServer,
+    onToggleConnection,
+    recordConnectError,
+  ]);
+
   const onReauthenticateFromBanner = useCallback(() => {
     if (!reAuthBanner) return;
     const serverId = reAuthBanner.serverId;
@@ -3691,11 +3790,14 @@ function App() {
           </Box>
         ) : null}
         <InspectorView
+          deepLink={deepLink}
+          deepLinkStatus={deepLinkStatus}
           servers={servers}
           serverListWritable={serverListWritable}
           activeServer={activeServerId}
           erroredServerId={failedServerId}
           connectionStatus={connectionStatus}
+          connectErrorMessage={connectErrorMessage}
           initializeResult={initializeResult}
           latencyMs={latencyMs}
           tools={tools}
diff --git a/clients/web/src/components/views/InspectorView/InspectorView.test.tsx b/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
index 2cf66769c..367787ff0 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
@@ -259,6 +259,42 @@ describe("InspectorView", () => {
     expect(onToggleConnection).toHaveBeenCalledWith("alpha");
   });
 
+  it("exposes the machine-readable connection-status header attributes for drivers", () => {
+    renderWithMantine(
+      <StatefulInspectorViewHost
+        {...makeProps({
+          servers: [sampleServer],
+          connectionStatus: "error",
+          connectErrorMessage: "handshake failed: 500",
+          deepLinkStatus: "rejected",
+        })}
+      />,
+    );
+    const header = screen.getByTestId("connection-status");
+    expect(header).toHaveAttribute("data-status", "error");
+    expect(header).toHaveAttribute(
+      "data-error-message",
+      "handshake failed: 500",
+    );
+    expect(header).toHaveAttribute("data-deeplink", "rejected");
+  });
+
+  it("omits the error-message attribute when no connect error is recorded", () => {
+    renderWithMantine(
+      <StatefulInspectorViewHost
+        {...makeProps({
+          servers: [sampleServer],
+          connectionStatus: "disconnected",
+          deepLinkStatus: "none",
+        })}
+      />,
+    );
+    const header = screen.getByTestId("connection-status");
+    expect(header).toHaveAttribute("data-status", "disconnected");
+    expect(header).not.toHaveAttribute("data-error-message");
+    expect(header).toHaveAttribute("data-deeplink", "none");
+  });
+
   it("renders the connected header when connectionStatus + initializeResult are set", () => {
     renderWithMantine(
       <StatefulInspectorViewHost
diff --git a/clients/web/src/components/views/InspectorView/InspectorView.tsx b/clients/web/src/components/views/InspectorView/InspectorView.tsx
index 46e97d6ef..39fc74058 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.tsx
@@ -6,6 +6,7 @@ import {
   type ReactNode,
   type Ref,
 } from "react";
+import type { DeepLink, DeepLinkParseStatus } from "../../../utils/deepLink";
 import {
   AppShell,
   Flex,
@@ -304,6 +305,21 @@ const MonitorColumnGroup = Group.withProps({
 });
 
 export interface InspectorViewProps {
+  /**
+   * Validated deep-link parameters from the page URL. When present and
+   * `openApp` is set, the parent switches to the Apps tab and pre-selects that
+   * app (with `appArgs` as the form values) once the connection is up and the
+   * app list contains it. The connect itself is driven by the parent.
+   */
+  deepLink?: DeepLink;
+  /**
+   * Outcome of parsing the initial-URL deep link, surfaced as `data-deeplink`
+   * on the `connection-status` testid. Distinguishes "no deep link" from
+   * "rejected" (token mismatch / bad serverUrl) — both leave `data-status`
+   * idle, so an automated driver otherwise cannot tell them apart.
+   */
+  deepLinkStatus?: DeepLinkParseStatus;
+
   // Server list (static config; runtime connection state comes from the
   // separate fields below and is merged into each card by this component).
   servers: ServerEntry[];
@@ -324,6 +340,13 @@ export interface InspectorViewProps {
    */
   erroredServerId?: string;
   connectionStatus: ConnectionStatus;
+  /**
+   * Last connection-level error message (handshake failure, OAuth start
+   * failure, deep-link automation failure). Surfaced as `data-error-message`
+   * on the header's `connection-status` testid so an automated driver can read
+   * *why* a connect failed without scraping a transient toast.
+   */
+  connectErrorMessage?: string;
   initializeResult?: InitializeResult;
   latencyMs?: number;
 
@@ -497,11 +520,13 @@ export interface InspectorViewProps {
 }
 
 export function InspectorView({
+  deepLinkStatus,
   servers: serversInput,
   serverListWritable = true,
   activeServer,
   erroredServerId,
   connectionStatus,
+  connectErrorMessage,
   initializeResult,
   latencyMs,
   tools,
@@ -1037,7 +1062,12 @@ export function InspectorView({
     // Main-slot height clamp + overflow:hidden keep that scroll on the inner
     // ScrollArea regions only.
     <AppShell header={{ height: 60 }} padding={0}>
-      <AppShell.Header>
+      <AppShell.Header
+        data-testid="connection-status"
+        data-status={connectionStatus}
+        data-error-message={connectErrorMessage}
+        data-deeplink={deepLinkStatus}
+      >
         {connectionStatus === "connected" && initializeResult ? (
           <ViewHeader
             connected
diff --git a/clients/web/src/utils/deepLink.test.ts b/clients/web/src/utils/deepLink.test.ts
new file mode 100644
index 000000000..14d32dd15
--- /dev/null
+++ b/clients/web/src/utils/deepLink.test.ts
@@ -0,0 +1,199 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseDeepLink,
+  deepLinkConfigEquals,
+  deepLinkParseStatus,
+  DEEP_LINK_SERVER_ID,
+} from "./deepLink";
+
+const TOKEN = "tok-abc";
+
+describe("parseDeepLink", () => {
+  it("returns undefined when no serverUrl param is present", () => {
+    expect(parseDeepLink("?autoConnect=" + TOKEN, TOKEN)).toBeUndefined();
+  });
+
+  it("returns undefined when autoConnect is missing", () => {
+    expect(
+      parseDeepLink("?serverUrl=https%3A%2F%2Fexample.com%2Fmcp", TOKEN),
+    ).toBeUndefined();
+  });
+
+  it("rejects when autoConnect does not match the session token (CSRF guard)", () => {
+    expect(
+      parseDeepLink(
+        "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=1",
+        TOKEN,
+      ),
+    ).toBeUndefined();
+  });
+
+  it("rejects when there is no session token to compare against", () => {
+    expect(
+      parseDeepLink(
+        "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=" + TOKEN,
+        undefined,
+      ),
+    ).toBeUndefined();
+  });
+
+  it("rejects non-http(s) serverUrl schemes", () => {
+    for (const url of [
+      "javascript:alert(1)",
+      "file:///etc/passwd",
+      "data:text/html,<script>",
+      "not a url",
+    ]) {
+      expect(
+        parseDeepLink(
+          `?serverUrl=${encodeURIComponent(url)}&autoConnect=${TOKEN}`,
+          TOKEN,
+        ),
+      ).toBeUndefined();
+    }
+  });
+
+  it("parses a valid streamable-http deep link with the default transport", () => {
+    const link = parseDeepLink(
+      "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=" + TOKEN,
+      TOKEN,
+    );
+    expect(link).toEqual({
+      serverId: DEEP_LINK_SERVER_ID,
+      serverConfig: { type: "streamable-http", url: "https://example.com/mcp" },
+      openApp: undefined,
+      appArgs: {},
+      autoOpen: false,
+    });
+  });
+
+  it("sets autoOpen only when the param equals the session token (same CSRF gate as autoConnect)", () => {
+    const ok = parseDeepLink(
+      `?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=${TOKEN}&autoOpen=${TOKEN}`,
+      TOKEN,
+    );
+    expect(ok?.autoOpen).toBe(true);
+    const wrong = parseDeepLink(
+      `?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=${TOKEN}&autoOpen=1`,
+      TOKEN,
+    );
+    expect(wrong?.autoOpen).toBe(false);
+  });
+
+  it("honors transport=sse and ignores unknown transport values", () => {
+    const sse = parseDeepLink(
+      "?serverUrl=https%3A%2F%2Fexample.com%2Fsse&transport=sse&autoConnect=" +
+        TOKEN,
+      TOKEN,
+    );
+    expect(sse?.serverConfig).toEqual({
+      type: "sse",
+      url: "https://example.com/sse",
+    });
+    const bogus = parseDeepLink(
+      "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&transport=stdio&autoConnect=" +
+        TOKEN,
+      TOKEN,
+    );
+    expect(bogus?.serverConfig.type).toBe("streamable-http");
+  });
+
+  it("decodes base64url appArgs into an object", () => {
+    const args = { zip: "10001", category: "electrician" };
+    const encoded = btoa(JSON.stringify(args))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    const link = parseDeepLink(
+      `?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=${TOKEN}&openApp=get_pros&appArgs=${encoded}`,
+      TOKEN,
+    );
+    expect(link?.openApp).toBe("get_pros");
+    expect(link?.appArgs).toEqual(args);
+  });
+
+  it("falls back to {} for malformed or non-object appArgs", () => {
+    for (const bad of ["!!!", btoa("[1,2,3]"), btoa('"string"')]) {
+      const link = parseDeepLink(
+        `?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=${TOKEN}&appArgs=${encodeURIComponent(bad)}`,
+        TOKEN,
+      );
+      expect(link?.appArgs).toEqual({});
+    }
+  });
+
+  it("normalizes serverUrl (host case, trailing slash) to match the OAuth-store key form", () => {
+    const link = parseDeepLink(
+      "?serverUrl=" +
+        encodeURIComponent("https://Example.COM") +
+        "&autoConnect=" +
+        TOKEN,
+      TOKEN,
+    );
+    expect(link?.serverConfig).toEqual({
+      type: "streamable-http",
+      url: "https://example.com/",
+    });
+  });
+});
+
+describe("deepLinkParseStatus", () => {
+  it("returns 'none' when no deep-link params are present", () => {
+    expect(deepLinkParseStatus("", undefined)).toBe("none");
+    expect(deepLinkParseStatus("?foo=bar", undefined)).toBe("none");
+  });
+
+  it("returns 'rejected' when deep-link params are present but parsing failed", () => {
+    expect(
+      deepLinkParseStatus(
+        "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=wrong",
+        undefined,
+      ),
+    ).toBe("rejected");
+    expect(deepLinkParseStatus("?serverUrl=javascript:x", undefined)).toBe(
+      "rejected",
+    );
+  });
+
+  it("returns 'parsed' when a DeepLink was produced", () => {
+    const link = parseDeepLink(
+      "?serverUrl=https%3A%2F%2Fexample.com%2Fmcp&autoConnect=" + TOKEN,
+      TOKEN,
+    );
+    expect(deepLinkParseStatus("?serverUrl=x&autoConnect=" + TOKEN, link)).toBe(
+      "parsed",
+    );
+  });
+});
+
+describe("deepLinkConfigEquals", () => {
+  const URL_A = "https://example.com/mcp";
+  const URL_B = "https://example.com/sse";
+
+  it("matches when both type and url are identical", () => {
+    expect(
+      deepLinkConfigEquals(
+        { type: "streamable-http", url: URL_A },
+        { type: "streamable-http", url: URL_A },
+      ),
+    ).toBe(true);
+  });
+
+  it("differs when only the type changed (sse↔streamable-http)", () => {
+    expect(
+      deepLinkConfigEquals(
+        { type: "sse", url: URL_A },
+        { type: "streamable-http", url: URL_A },
+      ),
+    ).toBe(false);
+  });
+
+  it("differs when only the url changed", () => {
+    expect(
+      deepLinkConfigEquals(
+        { type: "streamable-http", url: URL_A },
+        { type: "streamable-http", url: URL_B },
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/clients/web/src/utils/deepLink.ts b/clients/web/src/utils/deepLink.ts
new file mode 100644
index 000000000..c663fafcc
--- /dev/null
+++ b/clients/web/src/utils/deepLink.ts
@@ -0,0 +1,180 @@
+import type { MCPServerConfig } from "@inspector/core/mcp/types.js";
+
+/**
+ * Parsed deep-link parameters that drive an automated session: the inspector
+ * connects to `serverConfig` on load, then (if `openApp` is set) switches to
+ * the Apps tab with that tool selected and `appArgs` pre-filled.
+ */
+export interface DeepLink {
+  serverId: string;
+  serverConfig: MCPServerConfig;
+  openApp?: string;
+  appArgs: Record<string, unknown>;
+  /**
+   * When true, the Apps screen opens the selected app automatically once it is
+   * pre-selected and `appArgs` are seeded — no explicit "Open App" click. Same
+   * CSRF gate as `autoConnect`: the URL value must equal the session's API
+   * token, so a third-party-minted link cannot auto-invoke a tool.
+   */
+  autoOpen: boolean;
+}
+
+/**
+ * Stable, URL-safe id for the ad-hoc server entry a deep link creates. Reusing
+ * one id (rather than a fresh uuid per load) means a reload reconnects to the
+ * same catalog row instead of accumulating duplicates.
+ */
+export const DEEP_LINK_SERVER_ID = "deep-link";
+
+const ALLOWED_TRANSPORTS = new Set(["http", "sse"]);
+
+function decodeAppArgs(encoded: string | null): Record<string, unknown> {
+  if (!encoded) return {};
+  // base64url → base64
+  const b64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+  let json: string;
+  try {
+    json = atob(padded);
+  } catch {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(json);
+    return parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Reject any `serverUrl` that is not a well-formed `http:`/`https:` URL. The
+ * connect form already accepts arbitrary URLs from the user, so this is not a
+ * new capability — but a deep link can be crafted by a third party, and we do
+ * not want a click to drive a `javascript:` / `file:` / `data:` value into the
+ * connect path.
+ *
+ * Loopback and private-range hosts are intentionally **not** blocked here:
+ * connecting to a locally running MCP server is the inspector's primary
+ * development use case, and the manual connect form imposes no such
+ * restriction either. The CSRF gate on `autoConnect` (see
+ * {@link parseDeepLink}) is what prevents a third-party page from driving a
+ * connect the user did not initiate.
+ *
+ * The returned value is `URL.href`, which canonicalizes host case and adds the
+ * root path for a bare-host URL — the same shape the OAuth store keys server
+ * URLs under, so a token saved by the web inspector is found by the CLI's
+ * `--use-stored-auth` lookup (and vice versa) regardless of how the URL was
+ * typed.
+ */
+function validateServerUrl(raw: string): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+  return url.href;
+}
+
+/**
+ * Shallow equality for the subset of {@link MCPServerConfig} a deep link can
+ * produce. Used by the auto-connect effect to decide whether the persisted
+ * `deep-link` catalog row needs updating before connecting — comparing only
+ * `url` (the previous behavior) misses a stale `type` (sse↔streamable-http)
+ * and would connect with the wrong transport.
+ */
+export function deepLinkConfigEquals(
+  a: MCPServerConfig,
+  b: MCPServerConfig,
+): boolean {
+  if (a.type !== b.type) return false;
+  const aUrl = "url" in a ? a.url : undefined;
+  const bUrl = "url" in b ? b.url : undefined;
+  return aUrl === bUrl;
+}
+
+/**
+ * Outcome of {@link parseDeepLink} for the page's initial URL, surfaced as
+ * `data-deeplink` on the `connection-status` testid so an automated driver can
+ * distinguish "no deep link" from "deep link present but rejected" (token
+ * mismatch / bad serverUrl) — both look the same to a poll on `data-status`.
+ */
+export type DeepLinkParseStatus = "none" | "parsed" | "rejected";
+
+/**
+ * Classify the initial-URL deep-link outcome without re-parsing. `undefined`
+ * from {@link parseDeepLink} is ambiguous (no params vs. rejected); this
+ * inspects the raw search string to tell them apart.
+ */
+export function deepLinkParseStatus(
+  search: string,
+  parsed: DeepLink | undefined,
+): DeepLinkParseStatus {
+  if (parsed) return "parsed";
+  const params = new URLSearchParams(search);
+  return params.has("serverUrl") || params.has("autoConnect")
+    ? "rejected"
+    : "none";
+}
+
+/**
+ * Parse the page's query string into a {@link DeepLink}. Returns `undefined`
+ * when no deep link is present **or** when the security gate fails.
+ *
+ * Security gate: `autoConnect` must equal the session's API auth token. The
+ * token is per-launch random and only known to whatever started the web server,
+ * so a deep link minted by an external page cannot satisfy this check — it
+ * defeats the "send a developer a crafted localhost URL" SSRF / auto-invocation
+ * vector while keeping the one-URL automated flow (the launcher knows the
+ * token, so it can always build a valid link).
+ *
+ * Carrying the token in the URL is the same exposure surface as the existing
+ * `?MCP_INSPECTOR_API_TOKEN=…` query param the launcher banner already prints
+ * (see `getAuthToken()` in `App.tsx`): the value is ephemeral (regenerated per
+ * launch), the page is loopback-only, and it never crosses to a third-party
+ * referer because the inspector's own backend serves every navigation.
+ */
+export function parseDeepLink(
+  search: string,
+  authToken: string | undefined,
+): DeepLink | undefined {
+  const params = new URLSearchParams(search);
+  const rawServerUrl = params.get("serverUrl");
+  const autoConnect = params.get("autoConnect");
+  if (!rawServerUrl || !autoConnect) return undefined;
+
+  if (!authToken || autoConnect !== authToken) return undefined;
+
+  const serverUrl = validateServerUrl(rawServerUrl);
+  if (!serverUrl) return undefined;
+
+  const transportParam = params.get("transport") ?? "http";
+  const transport = ALLOWED_TRANSPORTS.has(transportParam)
+    ? transportParam
+    : "http";
+  const serverConfig: MCPServerConfig =
+    transport === "sse"
+      ? { type: "sse", url: serverUrl }
+      : { type: "streamable-http", url: serverUrl };
+
+  const openApp = params.get("openApp") ?? undefined;
+  const appArgs = decodeAppArgs(params.get("appArgs"));
+  // autoOpen is gated on the same per-launch token as autoConnect (already
+  // validated above), so the mere presence of the param is sufficient here —
+  // a link that reached this line has already proven knowledge of the token.
+  const autoOpen = params.get("autoOpen") === authToken;
+
+  return {
+    serverId: DEEP_LINK_SERVER_ID,
+    serverConfig,
+    openApp,
+    appArgs,
+    autoOpen,
+  };
+}

From cbb2afe80c0954ebfbf8f69d3249cce59c06184c Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 22:58:34 -0400
Subject: [PATCH 02/11] =?UTF-8?q?web:=20deep-link=20openApp/appArgs/autoOp?=
 =?UTF-8?q?en=20=E2=80=94=20pre-select=20&=20pre-fill=20an=20app=20from=20?=
 =?UTF-8?q?the=20URL=20(#1577)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1577

Extends the deep link (#1576) to land on a rendered MCP App:

- `&openApp=<toolName>` — once connected and the tool appears in the app list,
  InspectorView switches to the Apps tab and pre-selects it.
- `&appArgs=<base64url(JSON)>` — pre-fills the tool form; values are merged
  **over** `collectSchemaDefaults()` so required-with-default fields don't
  disable "Open App".
- `&autoOpen=<token>` — token-gated auto-click of "Open App".

Adapted to the current architecture (differs from PR #1510's reference):
- Tab state is lifted to App.tsx (#1417), so the openApp effect lives in
  InspectorView and drives `onActiveTabChange("Apps")` + `onAppsUiChange` seed
  + `onSelectApp`, guarded by `deepLinkOpenAppRef` to fire once.
- AppsScreen owns the `running`/iframe state, so `autoOpen` is threaded to it
  as a prop; a fire-once effect defers the open one microtask past the
  synchronous effect body (satisfying `react-hooks/set-state-in-effect`,
  matching App.tsx's connect effect). `resetAppChannels` memoized so the
  effect's deps don't churn.

Tests: InspectorView (tab-switch + pre-select + appArgs-over-defaults merge +
non-app openApp ignored), AppsScreen (autoOpen fires once with seeded values;
no-selection stays idle). README documents the params. Coverage gate green.

Part of the #1579 decomposition (Wave 4).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/web/README.md                         | 16 ++-
 .../screens/AppsScreen/AppsScreen.test.tsx    | 34 +++++++
 .../screens/AppsScreen/AppsScreen.tsx         | 48 ++++++++-
 .../InspectorView/InspectorView.test.tsx      | 98 +++++++++++++++++++
 .../views/InspectorView/InspectorView.tsx     | 47 +++++++++
 5 files changed, 238 insertions(+), 5 deletions(-)

diff --git a/clients/web/README.md b/clients/web/README.md
index 346371349..a836f4329 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -94,7 +94,21 @@ The deep link upserts a stable `deep-link` catalog row (so a reload reconnects t
 | `data-error-message` | on `connection-status` | Why the last connect failed (handshake error, OAuth-start failure, deep-link automation failure); absent when there is no error. |
 | `data-deeplink` | on `connection-status` | `parsed` (a valid deep link drove this load), `rejected` (deep-link params present but the token/serverUrl gate failed), or `none`. Lets a driver distinguish "no deep link" from "rejected" — both otherwise leave `data-status` idle. |
 
-The `openApp` / `appArgs` / `autoOpen` params extend this to land on a rendered MCP App; see the [MCP Apps screen automation contract](#mcp-apps-screen-automation-contract) above for the app-side `data-*` signals.
+### Landing on a rendered app
+
+Three further params extend the deep link to pre-select — and optionally auto-open — an MCP App, so a driver reaches a rendered widget with zero clicks:
+
+```
+…&openApp=<toolName>&appArgs=<base64url(JSON)>&autoOpen=<token>
+```
+
+| Param | Meaning |
+| --- | --- |
+| `openApp` | The app-tool name. Once the connection is up and the tool appears in the app list, the inspector switches to the Apps tab and pre-selects it. |
+| `appArgs` | `base64url(JSON)` object of form values. Merged **over** the tool's schema defaults (`collectSchemaDefaults`) so a required-with-default field isn't left blank — which would otherwise disable "Open App". Malformed / non-object values fall back to `{}`. |
+| `autoOpen` | **Same CSRF gate as `autoConnect`** — must equal the session token. When set, "Open App" fires automatically (a tool call from a URL), so the token gate is mandatory. Without a match the app is pre-selected but not opened. |
+
+The app-side render lifecycle is observable through the [MCP Apps screen automation contract](#mcp-apps-screen-automation-contract) above (`data-app-status="ready"`), so a driver can `waitForSelector` the whole `connect → open → ready` chain deterministically.
 
 ## Theme (`src/theme/`)
 
diff --git a/clients/web/src/components/screens/AppsScreen/AppsScreen.test.tsx b/clients/web/src/components/screens/AppsScreen/AppsScreen.test.tsx
index 7c9c0dcfa..deaa3e8ff 100644
--- a/clients/web/src/components/screens/AppsScreen/AppsScreen.test.tsx
+++ b/clients/web/src/components/screens/AppsScreen/AppsScreen.test.tsx
@@ -274,6 +274,40 @@ describe("AppsScreen", () => {
     expect(screen.getByTitle("Ops Dashboard")).toBeInTheDocument();
   });
 
+  it("auto-opens the pre-selected app with its seeded form values when autoOpen is set (deep-link)", async () => {
+    const onOpenApp = vi.fn();
+    renderWithMantine(
+      <ControlledAppsScreen
+        autoOpen
+        ui={{
+          selectedAppName: "weather",
+          formValues: { city: "Reykjavik" },
+          search: "",
+        }}
+        onOpenApp={onOpenApp}
+      />,
+    );
+    // No click: the fire-once effect opens the seeded app with its form values.
+    await vi.waitFor(() =>
+      expect(onOpenApp).toHaveBeenCalledWith("weather", { city: "Reykjavik" }),
+    );
+    expect(onOpenApp).toHaveBeenCalledTimes(1);
+    // Renderer mounted; the Open App button is gone.
+    expect(
+      screen.queryByRole("button", { name: /Open App/ }),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTitle("Weather Widget")).toBeInTheDocument();
+  });
+
+  it("does not auto-open when autoOpen is set but no app is pre-selected", async () => {
+    const onOpenApp = vi.fn();
+    renderWithMantine(<ControlledAppsScreen autoOpen onOpenApp={onOpenApp} />);
+    // Give the effect a chance to run; with no selection it must stay idle.
+    await Promise.resolve();
+    expect(onOpenApp).not.toHaveBeenCalled();
+    expect(screen.getByText("Select an app to view details")).toBeVisible();
+  });
+
   it("invokes onOpenApp with form values when Open App is clicked", async () => {
     const user = userEvent.setup();
     const onOpenApp = vi.fn();
diff --git a/clients/web/src/components/screens/AppsScreen/AppsScreen.tsx b/clients/web/src/components/screens/AppsScreen/AppsScreen.tsx
index dd85b02ae..0a38c2eae 100644
--- a/clients/web/src/components/screens/AppsScreen/AppsScreen.tsx
+++ b/clients/web/src/components/screens/AppsScreen/AppsScreen.tsx
@@ -1,4 +1,4 @@
-import { useRef, useState, type Ref } from "react";
+import { useCallback, useEffect, useRef, useState, type Ref } from "react";
 import {
   ActionIcon,
   Button,
@@ -64,6 +64,14 @@ export interface AppsScreenProps {
   onCloseApp: () => void;
   /** Surfaces bridge/runtime failures from the renderer (e.g. no client). */
   onError?: (err: Error) => void;
+  /**
+   * Deep-link auto-open (#1577): when true and an app is already pre-selected
+   * (the parent seeds `ui.selectedAppName` + `ui.formValues` from the URL),
+   * the screen fires "Open App" automatically — no explicit click. Token-gated
+   * upstream in `parseDeepLink` (the URL value must equal the session token),
+   * so a third-party link cannot auto-invoke a tool. Fires exactly once.
+   */
+  autoOpen?: boolean;
 }
 
 // Selected app, its form values, and the sidebar search — controlled by the
@@ -333,6 +341,7 @@ export function AppsScreen({
   onOpenApp,
   onCloseApp,
   onError,
+  autoOpen = false,
 }: AppsScreenProps) {
   const { selectedAppName, formValues, search } = ui;
   const [running, setRunning] = useState(false);
@@ -415,8 +424,9 @@ export function AppsScreen({
   // Clear the message + log panels (and the reported height). Called when a run
   // ends or the selected app changes so a new run starts clean. `keepPartials`
   // is set for `handleOpen`, where the staged fragments are about to be consumed
-  // by the renderer and must not be cleared first.
-  function resetAppChannels(opts?: { keepPartials?: boolean }) {
+  // by the renderer and must not be cleared first. Memoized (stable setState
+  // calls only) so the deep-link auto-open effect's deps don't churn.
+  const resetAppChannels = useCallback((opts?: { keepPartials?: boolean }) => {
     setAppHeight(undefined);
     setMessages([]);
     setAppLogs([]);
@@ -424,7 +434,7 @@ export function AppsScreen({
     setAppStatus("idle");
     setAppError(undefined);
     if (!opts?.keepPartials) setPartialStages([]);
-  }
+  }, []);
 
   // Capture the error locally (so it can be shown in the card and surfaced as
   // `data-app-error`) and forward it to the parent's onError. The renderer
@@ -500,6 +510,36 @@ export function AppsScreen({
     onCloseApp();
   }
 
+  // Deep-link auto-open (#1577): the parent seeds `ui.selectedAppName` +
+  // `ui.formValues` from the URL and sets `autoOpen`; fire "Open App" here so
+  // the driver lands on a rendered widget with zero clicks. Ref-guarded to fire
+  // exactly once — a later manual close leaves `running` false without
+  // re-triggering. The open (running + channel resets + `onOpenApp`) is
+  // deferred one microtask past the synchronous effect body: it calls setState,
+  // which the set-state-in-effect lint rightly flags in general, but this is a
+  // ref-guarded run-once effect so the cascading-render concern doesn't apply
+  // (same pattern as App.tsx's deep-link connect effect). `resetAppChannels`
+  // changes identity each render, so the effect re-runs, but the ref guard
+  // makes every run after the first a no-op.
+  const autoOpenFiredRef = useRef(false);
+  useEffect(() => {
+    if (!autoOpen || autoOpenFiredRef.current) return;
+    if (!selectedTool || running) return;
+    autoOpenFiredRef.current = true;
+    void Promise.resolve().then(() => {
+      resetAppChannels({ keepPartials: true });
+      setRunning(true);
+      onOpenApp(selectedTool.name, formValues);
+    });
+  }, [
+    autoOpen,
+    selectedTool,
+    running,
+    formValues,
+    onOpenApp,
+    resetAppChannels,
+  ]);
+
   function handleBackToInput() {
     setRunning(false);
     setMaximized(false);
diff --git a/clients/web/src/components/views/InspectorView/InspectorView.test.tsx b/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
index 367787ff0..2f494904b 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.test.tsx
@@ -689,6 +689,104 @@ describe("InspectorView", () => {
     });
   });
 
+  it("deep-link openApp auto-switches to the Apps tab and pre-selects the app once connected", async () => {
+    const onSelectApp = vi.fn();
+    renderWithMantine(
+      <StatefulInspectorViewHost
+        {...makeProps({
+          servers: [sampleServer],
+          activeServer: "alpha",
+          connectionStatus: "connected",
+          initializeResult: connectedInit,
+          tools: [sampleAppTool],
+          onSelectApp,
+          deepLink: {
+            serverId: "deep-link",
+            serverConfig: {
+              type: "streamable-http",
+              url: "https://example.com/mcp",
+            },
+            openApp: "ops",
+            appArgs: {},
+            autoOpen: false,
+          },
+        })}
+      />,
+    );
+    // No click: the effect flips the lifted tab to Apps and seeds the selection.
+    expect(await screen.findByText("MCP Apps (1)")).toBeInTheDocument();
+    await waitFor(() => expect(onSelectApp).toHaveBeenCalledWith("ops"));
+  });
+
+  it("deep-link appArgs are merged over the schema defaults into the pre-filled form", async () => {
+    const fieldedAppTool: Tool = {
+      name: "cohorts",
+      title: "Cohort Data",
+      inputSchema: {
+        type: "object",
+        properties: {
+          metric: { type: "string", default: "retention" },
+          zip: { type: "string" },
+        },
+      },
+      _meta: { ui: { resourceUri: "ui://apps/cohorts" } },
+    };
+    renderWithMantine(
+      <StatefulInspectorViewHost
+        {...makeProps({
+          servers: [sampleServer],
+          activeServer: "alpha",
+          connectionStatus: "connected",
+          initializeResult: connectedInit,
+          tools: [fieldedAppTool],
+          deepLink: {
+            serverId: "deep-link",
+            serverConfig: {
+              type: "streamable-http",
+              url: "https://example.com/mcp",
+            },
+            openApp: "cohorts",
+            // Overrides no default (zip), leaving `metric`'s schema default intact.
+            appArgs: { zip: "10001" },
+            autoOpen: false,
+          },
+        })}
+      />,
+    );
+    // The form is pre-filled: `zip` from appArgs, `metric` from the schema default.
+    expect(await screen.findByDisplayValue("10001")).toBeInTheDocument();
+    expect(screen.getByDisplayValue("retention")).toBeInTheDocument();
+  });
+
+  it("ignores a deep-link openApp whose tool is not an app (no tab switch)", async () => {
+    renderWithMantine(
+      <StatefulInspectorViewHost
+        {...makeProps({
+          servers: [sampleServer],
+          activeServer: "alpha",
+          connectionStatus: "connected",
+          initializeResult: connectedInit,
+          tools: [sampleAppTool],
+          deepLink: {
+            serverId: "deep-link",
+            serverConfig: {
+              type: "streamable-http",
+              url: "https://example.com/mcp",
+            },
+            openApp: "does-not-exist",
+            appArgs: {},
+            autoOpen: false,
+          },
+        })}
+      />,
+    );
+    // The target app never appears, so the effect never switches tabs: the
+    // Apps screen is never activated even though the Apps tab is available.
+    const radios = await screen.findAllByRole("radio");
+    expect(radios.map((r) => r.getAttribute("value"))).toContain("Apps");
+    expect(screen.queryByText("MCP Apps (1)")).not.toBeInTheDocument();
+  });
+
   it("snaps activeTab back to Servers when the Apps tab disappears after a refresh", async () => {
     const user = userEvent.setup({ delay: null });
     const { rerender } = renderWithMantine(
diff --git a/clients/web/src/components/views/InspectorView/InspectorView.tsx b/clients/web/src/components/views/InspectorView/InspectorView.tsx
index 39fc74058..29d561196 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.tsx
@@ -89,6 +89,7 @@ import { MonitoringScreen } from "../../groups/MonitoringScreen/MonitoringScreen
 import { ResizeHandle } from "../../elements/ResizeHandle/ResizeHandle";
 import { getServerType } from "@inspector/core/mcp/config.js";
 import { INSPECTOR_SERVERS_TAB } from "../../../utils/inspectorTabs";
+import { collectSchemaDefaults } from "../../../utils/jsonUtils";
 import { MONITOR_COLUMN_ANIM_MS } from "./monitorColumnAnimation";
 
 const SORT_DEFAULT: SortDirection = "newest-first";
@@ -520,6 +521,7 @@ export interface InspectorViewProps {
 }
 
 export function InspectorView({
+  deepLink,
   deepLinkStatus,
   servers: serversInput,
   serverListWritable = true,
@@ -866,6 +868,48 @@ export function InspectorView({
       ? firstNonServersTab
       : SERVERS_TAB;
 
+  // Deep-link auto-open (#1577): once connected and the requested app appears in
+  // the app-tools list, switch to the Apps tab and pre-select it with the
+  // supplied form values. The `autoOpen` flag is forwarded to AppsScreen (which
+  // owns the running/iframe state) to fire the actual "Open App" — see its
+  // `autoOpen` prop. Guarded by a ref so it fires exactly once even though the
+  // effect re-runs as `appTools`/`availableTabs` settle.
+  const deepLinkOpenAppRef = useRef(false);
+  useEffect(() => {
+    if (!deepLink?.openApp) return;
+    if (deepLinkOpenAppRef.current) return;
+    if (connectionStatus !== "connected") return;
+    if (!availableTabs.includes("Apps")) return;
+    const target = appTools.find((t) => t.name === deepLink.openApp);
+    if (!target) return;
+    deepLinkOpenAppRef.current = true;
+    // Seed the schema's defaults THEN overlay the deep-link's appArgs. Without
+    // the defaults, a required field the form would display with its default
+    // value is absent from `formValues`, the schema-form's validity check
+    // fails, and Open App is silently disabled — an automated driver's click
+    // then no-ops and the iframe-wait spins forever.
+    const formValues = {
+      ...collectSchemaDefaults(target.inputSchema),
+      ...deepLink.appArgs,
+    };
+    onActiveTabChange("Apps");
+    onAppsUiChange({
+      ...appsUi,
+      selectedAppName: target.name,
+      formValues,
+    });
+    onSelectApp(target.name);
+  }, [
+    deepLink,
+    connectionStatus,
+    availableTabs,
+    appTools,
+    appsUi,
+    onActiveTabChange,
+    onAppsUiChange,
+    onSelectApp,
+  ]);
+
   // The monitor tab shown in the column, clamped to what's available (e.g. a
   // switch to a stdio server drops Network). `?? LOGS_TAB` is a types-only
   // fallback: the column only renders while `monitorAvailable.length > 0`.
@@ -1146,6 +1190,9 @@ export function InspectorView({
                 onOpenApp={onOpenApp}
                 onCloseApp={onCloseApp}
                 onError={onAppError}
+                autoOpen={
+                  Boolean(deepLink?.openApp) && (deepLink?.autoOpen ?? false)
+                }
               />
             </ScreenStage>
             <ScreenStage active={activeTab === "Prompts"}>

From 93f3fb64f2d3f10ead33374d7894fa80cfd4233e Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:02:45 -0400
Subject: [PATCH 03/11] cli: reconcile --print-handoff deep-link with #1576
 canonical format (#1666)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1666

#1575 shipped `--print-handoff` with an interim deep-link shape (hardcoded
`transport: "http"`, marked `TODO(#1576)`). Now that #1576 owns the canonical
`?serverUrl&transport&autoConnect` format, `--print-handoff` emits exactly it:

- New `deepLinkTransport(serverUrl, transport)` helper derives `http`|`sse`
  from the resolved server — explicit `--transport` wins, else auto-detect from
  the URL path (`/sse` → sse), else default `http`. Unlike the core resolver it
  defaults instead of throwing (the handoff is best-effort; the web parser
  defaults an unknown transport to http too).
- `buildHandoff` takes the transport, emits the normalized serverUrl +
  derived transport in the query, and keeps `autoConnect=<token>` (which #1576
  adopted as the canonical CSRF gate, so the interim guess was already correct).
- Removed the `TODO(#1576)` marker; updated the doc comment + CLI README.

Tests: handoff emits `transport=http` for `/mcp`, `transport=sse` for `/sse`
and for explicit `--transport sse`; `deepLinkTransport` unit tests cover the
explicit/auto/default/stdio/unparseable branches. CLI coverage gate green
(cli.ts 100/92.8/100/100).

Part of the #1579 decomposition (Wave 4).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/cli/README.md                     |  2 +-
 clients/cli/__tests__/stored-auth.test.ts | 52 ++++++++++++++++++++-
 clients/cli/src/cli.ts                    | 55 ++++++++++++++++++-----
 3 files changed, 96 insertions(+), 13 deletions(-)

diff --git a/clients/cli/README.md b/clients/cli/README.md
index 3563e870e..4494fb42d 100644
--- a/clients/cli/README.md
+++ b/clients/cli/README.md
@@ -204,7 +204,7 @@ For the common case where OAuth was already completed in the **web inspector on
 
 **Short-circuit modes.** `--list-stored-auth` and `--print-handoff` each print their output and exit without connecting to a server; they ignore the method/target flags. They are mutually exclusive — if both are passed, `--list-stored-auth` takes precedence.
 
-> The `deepLink` shape emitted by `--print-handoff` is interim, pending the web deep-link auto-connect work ([#1576](https://github.com/modelcontextprotocol/inspector/issues/1576)); it will be reconciled with that issue's canonical handoff format once it lands.
+The `deepLink` is the canonical web deep-link ([#1576](https://github.com/modelcontextprotocol/inspector/issues/1576)) — `http://<host>:<port>/?serverUrl=<url>&transport=<http|sse>&autoConnect=<token>` — so navigating it in a browser reaches a connected inspector in one shot. `transport` is derived from the resolved server (`--transport`, else auto-detected from the URL path: `/sse` → `sse`, else `http`), not hardcoded. `autoConnect` is set to `MCP_INSPECTOR_API_TOKEN`; when that env var is unset the link is still emitted but a `note` field flags that the web app's `autoConnect` gate will reject it until the inspector is launched with a known token.
 
 ```bash
 # On a remote VM: print what a human needs to complete OAuth in their browser.
diff --git a/clients/cli/__tests__/stored-auth.test.ts b/clients/cli/__tests__/stored-auth.test.ts
index 69be24f59..fe7c694c9 100644
--- a/clients/cli/__tests__/stored-auth.test.ts
+++ b/clients/cli/__tests__/stored-auth.test.ts
@@ -4,7 +4,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { runCli } from "./helpers/cli-runner.js";
 import { expectCliFailure, expectCliSuccess } from "./helpers/assertions.js";
-import { normalizeServerUrl } from "../src/cli.js";
+import { normalizeServerUrl, deepLinkTransport } from "../src/cli.js";
 import {
   createTestServerHttp,
   createEchoTool,
@@ -36,6 +36,27 @@ describe("normalizeServerUrl", () => {
   });
 });
 
+describe("deepLinkTransport", () => {
+  it("honors an explicit sse/http transport over the URL path", () => {
+    expect(deepLinkTransport("https://x.example/mcp", "sse")).toBe("sse");
+    expect(deepLinkTransport("https://x.example/sse", "http")).toBe("http");
+  });
+
+  it("auto-detects sse from a /sse path when no transport is given", () => {
+    expect(deepLinkTransport("https://x.example/sse", undefined)).toBe("sse");
+  });
+
+  it("defaults to http for a /mcp path, an ambiguous path, or stdio", () => {
+    expect(deepLinkTransport("https://x.example/mcp", undefined)).toBe("http");
+    expect(deepLinkTransport("https://x.example/", undefined)).toBe("http");
+    expect(deepLinkTransport("https://x.example/mcp", "stdio")).toBe("http");
+  });
+
+  it("defaults to http for an unparseable URL without throwing", () => {
+    expect(deepLinkTransport("not a url", undefined)).toBe("http");
+  });
+});
+
 describe("--use-stored-auth", () => {
   let server: ReturnType<typeof createTestServerHttp>;
   let serverUrl: string;
@@ -258,6 +279,8 @@ describe("--print-handoff", () => {
     expect(out.serverUrl).toBe("https://x.example/mcp");
     expect(out.deepLink).toContain("autoConnect=tok123");
     expect(out.deepLink).toContain("serverUrl=https%3A%2F%2Fx.example%2Fmcp");
+    // Canonical #1576 deep-link: a `/mcp` server hands off `transport=http`.
+    expect(out.deepLink).toContain("transport=http");
     expect(out.portForwardCmd).toContain("--tcp 16274:16274");
     expect(out.portForwardCmd).toContain("--tcp 16275:16275");
     expect(out.oauthStatePath).toBe(
@@ -266,6 +289,33 @@ describe("--print-handoff", () => {
     expect(out.apiToken).toBe("tok123");
   });
 
+  it("derives transport=sse for an SSE server (auto-detected from the /sse path)", async () => {
+    const result = await runCli(
+      ["--print-handoff", "--server-url", "https://x.example/sse"],
+      { env: { MCP_INSPECTOR_API_TOKEN: "tok123" } },
+    );
+    expectCliSuccess(result);
+    const out = JSON.parse(result.stdout) as { deepLink: string };
+    expect(out.deepLink).toContain("transport=sse");
+    expect(out.deepLink).not.toContain("transport=http");
+  });
+
+  it("honors an explicit --transport sse over the URL path", async () => {
+    const result = await runCli(
+      [
+        "--print-handoff",
+        "--server-url",
+        "https://x.example/mcp",
+        "--transport",
+        "sse",
+      ],
+      { env: { MCP_INSPECTOR_API_TOKEN: "tok123" } },
+    );
+    expectCliSuccess(result);
+    const out = JSON.parse(result.stdout) as { deepLink: string };
+    expect(out.deepLink).toContain("transport=sse");
+  });
+
   it("includes a note when MCP_INSPECTOR_API_TOKEN is unset", async () => {
     const result = await runCli(
       ["--print-handoff", "--server-url", "https://x.example/mcp"],
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 059338db5..c4ac4e7ac 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -539,28 +539,59 @@ async function waitForStoredToken(
   }
 }
 
+/**
+ * Derive the web deep-link `transport` value (`http` | `sse`) for a handoff.
+ * Mirrors {@link resolveServerConfig}'s URL-path auto-detection (`/sse` → sse,
+ * everything else → http) but, unlike that resolver, defaults to `http` instead
+ * of throwing on an ambiguous path — the handoff is best-effort, and the web
+ * {@link parseDeepLink} likewise defaults an unknown/missing transport to http.
+ */
+export function deepLinkTransport(
+  serverUrl: string,
+  transport: "sse" | "http" | "stdio" | undefined,
+): "http" | "sse" {
+  if (transport === "sse") return "sse";
+  if (transport === "http") return "http";
+  try {
+    if (new URL(serverUrl).pathname.endsWith("/sse")) return "sse";
+  } catch {
+    // Unparseable URL: fall through to the http default. The web parser rejects
+    // a non-http(s) serverUrl anyway, so guessing a transport for it is moot.
+  }
+  return "http";
+}
+
 /**
  * Build the JSON `--print-handoff` emits: everything an automated caller needs
  * to relay to a human so they can complete OAuth in a browser and have the
  * token land where the CLI will find it.
  *
- * NOTE: the `deepLink` query shape (serverUrl/transport/autoConnect) is the
- * interim format pending the web deep-link auto-connect work (#1576); reconcile
- * with that issue's canonical handoff format once it lands.
+ * The `deepLink` is the canonical web format owned by
+ * `clients/web/src/utils/deepLink.ts` (#1576): `?serverUrl&transport&autoConnect`,
+ * where `autoConnect` is the CSRF gate (must equal `MCP_INSPECTOR_API_TOKEN`).
+ * `transport` is derived from the resolved server via {@link deepLinkTransport}
+ * rather than hardcoded, so an SSE server hands off a `transport=sse` link.
  */
-function buildHandoff(serverUrl: string, statePath: string): McpResponse {
+function buildHandoff(
+  serverUrl: string,
+  statePath: string,
+  transport: "sse" | "http" | "stdio" | undefined,
+): McpResponse {
   const host = process.env.HOST || "127.0.0.1";
   const clientPort = process.env.CLIENT_PORT || "6274";
   const sandboxPort = process.env.MCP_SANDBOX_PORT || "6275";
   // Treat an empty MCP_INSPECTOR_API_TOKEN the same as unset — an empty token
   // can't satisfy the deep-link autoConnect gate.
   const apiToken = process.env.MCP_INSPECTOR_API_TOKEN || undefined;
-  // TODO(#1576): interim deep-link shape. `transport: "http"` is hardcoded even
-  // for SSE servers, and `autoConnect=<token>` is NOT one of the three token
-  // sources the web app reads (window.__INSPECTOR_API_TOKEN__ /
-  // ?MCP_INSPECTOR_API_TOKEN / sessionStorage — see CLAUDE.md). Reconcile both
-  // with #1576's canonical handoff/deep-link format once it lands.
-  const params = new URLSearchParams({ serverUrl, transport: "http" });
+  // Canonical #1576 deep-link shape: the normalized serverUrl (matching the
+  // OAuth-store key form the web app reuses) plus the resolved transport, gated
+  // by `autoConnect=<token>` — the same per-launch token the web parser
+  // requires. Omitted when no token is set; the `note` below flags that the
+  // link will be rejected until the web inspector is launched with a token.
+  const params = new URLSearchParams({
+    serverUrl: normalizeServerUrl(serverUrl),
+    transport: deepLinkTransport(serverUrl, transport),
+  });
   if (apiToken) params.set("autoConnect", apiToken);
   return {
     serverUrl: normalizeServerUrl(serverUrl),
@@ -897,7 +928,9 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
       throw new Error("--print-handoff requires --server-url");
     }
     await awaitableLog(
-      JSON.stringify(buildHandoff(options.serverUrl, oauthStatePath)) + "\n",
+      JSON.stringify(
+        buildHandoff(options.serverUrl, oauthStatePath, options.transport),
+      ) + "\n",
     );
     return { shortCircuit: true };
   }

From cdf124106ebde0535d132aa39457e23ccd37ab99 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:11:52 -0400
Subject: [PATCH 04/11] cli: stored-auth injection honors refresh_token, not
 just access_token (#1665)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1665

`--use-stored-auth` previously injected the stored access token blindly, so an
expired token failed even with a valid refresh_token on disk. Now, when a
`refresh_token` is stored, the CLI runs the OAuth refresh grant and injects the
fresh access token, persisting the rotation.

- New exported `refreshStoredAuthToken(serverUrl, statePath, deps?)`: reuses the
  SDK's `refreshAuthorization` (not a hand-rolled token request) with the stored
  `clientInformation` + `serverMetadata` (discovered via core
  `getAuthorizationServerUrl` + SDK `discoverAuthorizationServerMetadata` when
  the metadata wasn't persisted). Rotated tokens are written back through
  `serializeOAuthPersistBlob` under the same `{servers,idpSessions}` key, so web
  and CLI stay consistent. Missing refresh_token/clientInformation or a failed
  grant throw `CliExitCodeError(AUTH_REQUIRED)` with a clear message + envelope
  code (`no_stored_token` / `refresh_failed`).
- `--use-stored-auth` prefers refresh when a refresh_token is present (covers
  both absent and expired access tokens — the stored blob has no expiry, so the
  refresh token is the durable credential); falls back to injecting the stored
  access token otherwise (unchanged).
- `deps` are injectable so the refresh/discovery are unit-tested without a live
  token endpoint; an e2e test drives the real SDK path against a mock token
  endpoint and asserts the refreshed token is injected + the rotation persisted.
- CLI README updated (removed the "blind injection" caveat).

CLI coverage gate green (cli.ts 100/92/100/100).

Part of the #1579 decomposition (Wave 4, CLI lane).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/cli/README.md                     |   4 +-
 clients/cli/__tests__/stored-auth.test.ts | 203 +++++++++++++++++++++-
 clients/cli/src/cli.ts                    | 192 ++++++++++++++++----
 3 files changed, 365 insertions(+), 34 deletions(-)

diff --git a/clients/cli/README.md b/clients/cli/README.md
index 3563e870e..6e9126ab6 100644
--- a/clients/cli/README.md
+++ b/clients/cli/README.md
@@ -193,14 +193,14 @@ For the common case where OAuth was already completed in the **web inspector on
 
 | Option                  | Description                                                                                                                                                                                    |
 | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--use-stored-auth`     | Read the stored access token for `--server-url` and inject it as `Authorization: Bearer`. Exits `3` (`no_stored_token`) — listing the stored keys — when no token matches. Requires `--server-url`. |
+| `--use-stored-auth`     | Read the stored auth for `--server-url` and inject `Authorization: Bearer`. When a `refresh_token` is stored, the CLI runs the OAuth refresh grant first and injects the **fresh** access token (persisting the rotation); otherwise it injects the stored access token. Exits `3` (`no_stored_token`) — listing the stored keys — when nothing matches. Requires `--server-url`. |
 | `--wait-for-auth <sec>` | Poll the OAuth state file (500 ms interval) until a token for `--server-url` appears, then proceed as if `--use-stored-auth` were set. Times out at `<sec>` with exit `3` (`auth_wait_timeout`). Use after handing off to a human to complete OAuth in a browser. |
 | `--list-stored-auth`    | Print `{ oauthStatePath, storedServerUrls }` (the server keys that currently have a token) and exit. No server connection is made.                                                              |
 | `--print-handoff`       | Print a JSON handoff block (`deepLink`, `portForwardCmd`, `oauthStatePath`, `apiToken`) for `--server-url` and exit — everything a script/remote VM needs to drive the browser-side OAuth dance. Requires `--server-url`. |
 
 **State-file resolution** follows `MCP_INSPECTOR_OAUTH_STATE_PATH` → `<MCP_STORAGE_DIR>/oauth.json` → `~/.mcp-inspector/storage/oauth.json` — the same precedence the rest of the Inspector uses, so the CLI and web backend agree on the file. Server keys are canonicalised with `new URL().href` (the scheme the web store writes), so a trailing-slash or case mismatch between the URL a human opened and the one the agent passed still resolves.
 
-**Blind injection.** The token is injected as-is; the CLI does not validate or refresh it (a stored `refresh_token` is not yet used — a natural follow-up). A stale/expired access token surfaces as an HTTP `401` on the first request → exit `3` (`auth_required`). Re-complete the flow in the web inspector (or use `--wait-for-auth`) and retry.
+**Token refresh (#1665).** When the stored server state carries a `refresh_token` (plus the `clientInformation` the web inspector persists after a completed flow), `--use-stored-auth` runs the SDK's OAuth `refresh_token` grant to mint a fresh access token before connecting, then writes the rotated tokens back to the state file so web and CLI stay consistent. The auth-server metadata is reused from the stored state, or discovered from `--server-url` when absent. This covers both an absent and an expired stored access token — the persisted blob carries no expiry, so the refresh token is treated as the durable credential. A failed refresh (revoked/expired refresh token) exits `3` (`auth_required`, envelope `refresh_failed`); re-complete the flow in the web inspector and retry. Without a stored `refresh_token` the access token is injected as-is, and a stale one surfaces as an HTTP `401` → exit `3`.
 
 **Short-circuit modes.** `--list-stored-auth` and `--print-handoff` each print their output and exit without connecting to a server; they ignore the method/target flags. They are mutually exclusive — if both are passed, `--list-stored-auth` takes precedence.
 
diff --git a/clients/cli/__tests__/stored-auth.test.ts b/clients/cli/__tests__/stored-auth.test.ts
index 69be24f59..8e83f95d2 100644
--- a/clients/cli/__tests__/stored-auth.test.ts
+++ b/clients/cli/__tests__/stored-auth.test.ts
@@ -1,10 +1,11 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { createServer, type Server } from "node:http";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { runCli } from "./helpers/cli-runner.js";
 import { expectCliFailure, expectCliSuccess } from "./helpers/assertions.js";
-import { normalizeServerUrl } from "../src/cli.js";
+import { normalizeServerUrl, refreshStoredAuthToken } from "../src/cli.js";
 import {
   createTestServerHttp,
   createEchoTool,
@@ -36,6 +37,137 @@ describe("normalizeServerUrl", () => {
   });
 });
 
+describe("refreshStoredAuthToken", () => {
+  const SERVER = "https://api.example/mcp";
+  const freshTokens = {
+    access_token: "refreshed-access-token",
+    token_type: "Bearer",
+    refresh_token: "rotated-refresh-token",
+    expires_in: 3600,
+  };
+
+  it("runs the refresh grant, injects the fresh token, and persists the rotation", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+        clientInformation: { client_id: "cid", client_secret: "sec" },
+        serverMetadata: {
+          issuer: "https://auth.example",
+          token_endpoint: "https://auth.example/token",
+        },
+      },
+    });
+    try {
+      const refresh = vi.fn().mockResolvedValue(freshTokens);
+      const discover = vi.fn();
+      const token = await refreshStoredAuthToken(SERVER, path, {
+        refresh,
+        discover,
+      });
+      expect(token).toBe("refreshed-access-token");
+      // Stored metadata present → no discovery needed.
+      expect(discover).not.toHaveBeenCalled();
+      // Refresh called with the stored refresh token + client information.
+      expect(refresh).toHaveBeenCalledTimes(1);
+      const [, opts] = refresh.mock.calls[0]!;
+      expect(opts.refreshToken).toBe("old-refresh");
+      expect(opts.clientInformation).toEqual({
+        client_id: "cid",
+        client_secret: "sec",
+      });
+      // Rotation persisted back under the same key.
+      const persisted = JSON.parse(readFileSync(path, "utf8")) as {
+        servers: Record<string, { tokens?: { refresh_token?: string } }>;
+      };
+      expect(persisted.servers[SERVER]?.tokens?.refresh_token).toBe(
+        "rotated-refresh-token",
+      );
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
+  it("discovers the auth-server metadata when it was not persisted", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+        clientInformation: { client_id: "cid" },
+      },
+    });
+    try {
+      const refresh = vi.fn().mockResolvedValue(freshTokens);
+      const discover = vi.fn().mockResolvedValue({
+        issuer: "https://api.example",
+        token_endpoint: "https://api.example/token",
+      });
+      const token = await refreshStoredAuthToken(SERVER, path, {
+        refresh,
+        discover,
+      });
+      expect(token).toBe("refreshed-access-token");
+      expect(discover).toHaveBeenCalledTimes(1);
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
+  it("throws AUTH_REQUIRED when no refresh token is stored", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { access_token: "only-access", token_type: "Bearer" },
+      },
+    });
+    try {
+      await expect(
+        refreshStoredAuthToken(SERVER, path, { refresh: vi.fn() }),
+      ).rejects.toMatchObject({ exitCode: 3 });
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
+  it("throws AUTH_REQUIRED when a refresh token is present but client information is missing", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+      },
+    });
+    try {
+      await expect(
+        refreshStoredAuthToken(SERVER, path, { refresh: vi.fn() }),
+      ).rejects.toMatchObject({ exitCode: 3 });
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
+  it("surfaces a refresh-grant failure as AUTH_REQUIRED (refresh_failed)", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+        clientInformation: { client_id: "cid" },
+        serverMetadata: {
+          issuer: "https://auth.example",
+          token_endpoint: "https://auth.example/token",
+        },
+      },
+    });
+    try {
+      const refresh = vi
+        .fn()
+        .mockRejectedValue(new Error("invalid_grant: token revoked"));
+      await expect(
+        refreshStoredAuthToken(SERVER, path, { refresh }),
+      ).rejects.toMatchObject({
+        exitCode: 3,
+        envelope: { code: "refresh_failed" },
+      });
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+});
+
 describe("--use-stored-auth", () => {
   let server: ReturnType<typeof createTestServerHttp>;
   let serverUrl: string;
@@ -197,6 +329,71 @@ describe("--use-stored-auth", () => {
     const last = server.getRecordedRequests().at(-1)!;
     expect(last.headers?.authorization).toBe(`Bearer ${TOKEN}`);
   });
+
+  it("refreshes a stored refresh_token end-to-end and injects the fresh access token (#1665)", async () => {
+    // Minimal OAuth token endpoint: honors the refresh_token grant with a
+    // rotated token pair, so the CLI's real SDK refresh path has something to
+    // talk to (the MCP test server accepts any bearer, so a successful connect
+    // proves the refreshed token was injected).
+    let tokenRequests = 0;
+    const tokenServer: Server = createServer((req, res) => {
+      tokenRequests += 1;
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          access_token: "refreshed-access-token",
+          token_type: "Bearer",
+          refresh_token: "rotated-refresh-token",
+          expires_in: 3600,
+        }),
+      );
+    });
+    await new Promise<void>((resolve) => tokenServer.listen(0, resolve));
+    const addr = tokenServer.address();
+    const tokenBase =
+      typeof addr === "object" && addr ? `http://127.0.0.1:${addr.port}` : "";
+    const fixture = writeOAuthFixture({
+      [serverUrl]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+        clientInformation: { client_id: "cid", client_secret: "sec" },
+        serverMetadata: {
+          issuer: tokenBase,
+          token_endpoint: `${tokenBase}/token`,
+          response_types_supported: ["code"],
+          grant_types_supported: ["authorization_code", "refresh_token"],
+          token_endpoint_auth_methods_supported: ["client_secret_post"],
+        },
+      },
+    });
+    try {
+      const result = await runCli(
+        [
+          "--transport",
+          "http",
+          "--server-url",
+          serverUrl,
+          "--use-stored-auth",
+          "--method",
+          "tools/list",
+        ],
+        { env: { MCP_INSPECTOR_OAUTH_STATE_PATH: fixture } },
+      );
+      expectCliSuccess(result);
+      expect(tokenRequests).toBeGreaterThan(0);
+      const last = server.getRecordedRequests().at(-1)!;
+      expect(last.headers?.authorization).toBe("Bearer refreshed-access-token");
+      // Rotation persisted so a subsequent run reuses the new refresh token.
+      const persisted = JSON.parse(readFileSync(fixture, "utf8")) as {
+        servers: Record<string, { tokens?: { refresh_token?: string } }>;
+      };
+      expect(persisted.servers[serverUrl]?.tokens?.refresh_token).toBe(
+        "rotated-refresh-token",
+      );
+    } finally {
+      rmSync(fixture, { force: true });
+      await new Promise<void>((resolve) => tokenServer.close(() => resolve()));
+    }
+  });
 });
 
 describe("--list-stored-auth", () => {
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 059338db5..3e8f244aa 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -28,7 +28,21 @@ import type { JsonValue } from "@inspector/core/mcp/index.js";
 import { extractAppInfo } from "@inspector/core/mcp/apps.js";
 import type { AppInfo } from "@inspector/core/mcp/apps.js";
 import { getStateFilePath } from "@inspector/core/auth/node/storage-node.js";
-import { parseOAuthPersistBlob } from "@inspector/core/auth/oauth-persist.js";
+import {
+  parseOAuthPersistBlob,
+  serializeOAuthPersistBlob,
+  type OAuthPersistSnapshot,
+} from "@inspector/core/auth/oauth-persist.js";
+import { getAuthorizationServerUrl } from "@inspector/core/auth/discovery.js";
+import {
+  refreshAuthorization,
+  discoverAuthorizationServerMetadata,
+} from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformation,
+  OAuthMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
 import { CliExitCodeError, EXIT_CODES } from "./error-handler.js";
 import {
   ConsoleNavigation,
@@ -469,26 +483,59 @@ export function normalizeServerUrl(serverUrl: string): string {
   }
 }
 
+/** The subset of a stored server's OAuth state the CLI reads/refreshes. */
+type StoredServerState = {
+  tokens?: OAuthTokens;
+  clientInformation?: OAuthClientInformation;
+  serverMetadata?: OAuthMetadata;
+};
 /** The stored-server map shape the CLI reads out of the OAuth state file. */
-type StoredServers = Record<string, { tokens?: { access_token?: string } }>;
+type StoredServers = Record<string, StoredServerState>;
 
 /**
  * Read the OAuth state file directly (bypassing the Zustand store cache) so
  * each call sees the current on-disk state — required for `--wait-for-auth`
- * polling. Returns the `servers` map, or an empty object when the file is
- * absent or unreadable. Uses the shared {@link parseOAuthPersistBlob} so both
- * the plain `{servers,idpSessions}` and legacy `{state,version}` layouts are
+ * polling. Returns the full snapshot, or an empty one when the file is absent
+ * or unreadable. Uses the shared {@link parseOAuthPersistBlob} so both the
+ * plain `{servers,idpSessions}` and legacy `{state,version}` layouts are
  * accepted, matching whatever the web backend wrote.
  */
-async function readOAuthServers(statePath: string): Promise<StoredServers> {
+async function readOAuthSnapshot(
+  statePath: string,
+): Promise<OAuthPersistSnapshot> {
   const { readFile } = await import("node:fs/promises");
   try {
     const text = await readFile(statePath, "utf8");
     const snapshot = parseOAuthPersistBlob(text);
-    return (snapshot?.servers as StoredServers | undefined) ?? {};
+    if (snapshot) return snapshot;
   } catch {
-    return {};
+    // Absent/unreadable/malformed → fall through to the empty snapshot below.
   }
+  return { servers: {}, idpSessions: {} };
+}
+
+/**
+ * Read just the `servers` map. Thin wrapper over {@link readOAuthSnapshot} for
+ * the read-only lookups (`findStoredToken`, `--wait-for-auth`, key listing).
+ */
+async function readOAuthServers(statePath: string): Promise<StoredServers> {
+  return (await readOAuthSnapshot(statePath)).servers as StoredServers;
+}
+
+/**
+ * Look up a stored server's OAuth state, trying the URL-normalised key first
+ * (how the web store writes it) and the raw string second. Returns the matched
+ * key so a write-back updates the same entry.
+ */
+function findStoredServerState(
+  servers: StoredServers,
+  serverUrl: string,
+): { key: string; state: StoredServerState } | undefined {
+  const normalized = normalizeServerUrl(serverUrl);
+  if (servers[normalized])
+    return { key: normalized, state: servers[normalized] };
+  if (servers[serverUrl]) return { key: serverUrl, state: servers[serverUrl] };
+  return undefined;
 }
 
 /**
@@ -499,11 +546,89 @@ function findStoredToken(
   servers: StoredServers,
   serverUrl: string,
 ): string | undefined {
-  const key = normalizeServerUrl(serverUrl);
-  return (
-    servers[key]?.tokens?.access_token ??
-    servers[serverUrl]?.tokens?.access_token
-  );
+  return findStoredServerState(servers, serverUrl)?.state.tokens?.access_token;
+}
+
+/**
+ * Injectable dependencies for {@link refreshStoredAuthToken}, so the refresh
+ * grant + auth-server discovery can be faked in unit tests without standing up
+ * a real OAuth token endpoint. Both default to the SDK implementations.
+ */
+export interface RefreshStoredAuthDeps {
+  refresh?: typeof refreshAuthorization;
+  discover?: typeof discoverAuthorizationServerMetadata;
+}
+
+/**
+ * Run the OAuth `refresh_token` grant for a stored server and persist the
+ * rotated tokens back to `statePath` (same `{servers,idpSessions}` shape the
+ * web backend writes), returning the fresh access token.
+ *
+ * Reuses the SDK's {@link refreshAuthorization} (not a hand-rolled token
+ * request) with the stored `clientInformation` + `serverMetadata`; when the
+ * metadata wasn't persisted it is discovered from the resolved authorization
+ * server. A missing refresh token or client information, or a failed grant,
+ * throws {@link CliExitCodeError} with {@link EXIT_CODES.AUTH_REQUIRED} so the
+ * caller exits with the documented code and a clear message.
+ */
+export async function refreshStoredAuthToken(
+  serverUrl: string,
+  statePath: string,
+  deps: RefreshStoredAuthDeps = {},
+): Promise<string> {
+  const refresh = deps.refresh ?? refreshAuthorization;
+  const discover = deps.discover ?? discoverAuthorizationServerMetadata;
+
+  const snapshot = await readOAuthSnapshot(statePath);
+  const servers = snapshot.servers as StoredServers;
+  const found = findStoredServerState(servers, serverUrl);
+  const refreshToken = found?.state.tokens?.refresh_token;
+  const clientInformation = found?.state.clientInformation;
+  if (!found || !refreshToken) {
+    throw new CliExitCodeError(
+      EXIT_CODES.AUTH_REQUIRED,
+      `No stored refresh token for ${normalizeServerUrl(serverUrl)} in ${statePath}. Complete the OAuth flow in the web inspector first.`,
+      { code: "no_stored_token", url: serverUrl },
+    );
+  }
+  if (!clientInformation) {
+    throw new CliExitCodeError(
+      EXIT_CODES.AUTH_REQUIRED,
+      `Stored auth for ${normalizeServerUrl(serverUrl)} has a refresh token but no client information; cannot refresh. Re-authorize in the web inspector.`,
+      { code: "no_stored_token", url: serverUrl },
+    );
+  }
+
+  const authServerUrl = found.state.serverMetadata?.issuer
+    ? new URL(found.state.serverMetadata.issuer)
+    : getAuthorizationServerUrl(serverUrl);
+  const metadata =
+    found.state.serverMetadata ?? (await discover(authServerUrl)) ?? undefined;
+
+  let tokens: OAuthTokens;
+  try {
+    tokens = await refresh(authServerUrl, {
+      metadata,
+      clientInformation,
+      refreshToken,
+      resource: new URL(serverUrl),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new CliExitCodeError(
+      EXIT_CODES.AUTH_REQUIRED,
+      `Failed to refresh the stored OAuth token for ${normalizeServerUrl(serverUrl)}: ${message}. Re-authorize in the web inspector.`,
+      { code: "refresh_failed", url: serverUrl },
+    );
+  }
+
+  // Persist the rotated tokens back under the same key, preserving every other
+  // server entry and the idpSessions block, so web and CLI stay consistent.
+  servers[found.key] = { ...found.state, tokens };
+  const { writeFile } = await import("node:fs/promises");
+  await writeFile(statePath, serializeOAuthPersistBlob(snapshot), "utf8");
+
+  return tokens.access_token;
 }
 
 /**
@@ -934,11 +1059,13 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     }
     // Read the OAuth state file directly so the lookup is normalised the same
     // way the web inspector wrote it (`new URL().href`), and so `--wait-for-
-    // auth` sees fresh on-disk state on each poll. Header injection is the
-    // prototype path — only the access token is injected, blindly; a stale one
-    // surfaces as HTTP 401 → exit 3 (auth_required). Follow-up: when the stored
-    // `tokens.refresh_token` is present and the access token is expired, mint a
-    // fresh one instead of injecting the stale token.
+    // auth` sees fresh on-disk state on each poll. When a `refresh_token` is
+    // stored, the CLI runs the SDK refresh grant and injects the fresh access
+    // token (persisting the rotation) rather than blindly injecting a possibly-
+    // stale stored access token (#1665) — the stored blob carries no expiry, so
+    // the refresh token is the durable credential. Without a refresh token it
+    // falls back to injecting the stored access token; a stale one surfaces as
+    // HTTP 401 → exit 3 (auth_required).
     let token: string;
     if (options.waitForAuth !== undefined) {
       token = await waitForStoredToken(
@@ -948,18 +1075,25 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
       );
     } else {
       const servers = await readOAuthServers(oauthStatePath);
-      const found = findStoredToken(servers, options.serverUrl);
-      if (!found) {
-        const key = normalizeServerUrl(options.serverUrl);
-        const stored = Object.keys(servers);
-        throw new CliExitCodeError(
-          EXIT_CODES.AUTH_REQUIRED,
-          `No stored OAuth token for ${key} in ${oauthStatePath}. Complete the OAuth flow in the web inspector first.` +
-            (stored.length > 0 ? ` Stored keys: ${stored.join(", ")}.` : ""),
-          { code: "no_stored_token", url: options.serverUrl },
-        );
+      const stored = findStoredServerState(servers, options.serverUrl);
+      if (stored?.state.tokens?.refresh_token) {
+        token = await refreshStoredAuthToken(options.serverUrl, oauthStatePath);
+      } else {
+        const found = findStoredToken(servers, options.serverUrl);
+        if (!found) {
+          const key = normalizeServerUrl(options.serverUrl);
+          const storedKeys = Object.keys(servers);
+          throw new CliExitCodeError(
+            EXIT_CODES.AUTH_REQUIRED,
+            `No stored OAuth token for ${key} in ${oauthStatePath}. Complete the OAuth flow in the web inspector first.` +
+              (storedKeys.length > 0
+                ? ` Stored keys: ${storedKeys.join(", ")}.`
+                : ""),
+            { code: "no_stored_token", url: options.serverUrl },
+          );
+        }
+        token = found;
       }
-      token = found;
     }
     serverOptions.headers = {
       ...(serverOptions.headers ?? {}),

From a30a5760174259d108574b472da54c9f38b6e7aa Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:14:51 -0400
Subject: [PATCH 05/11] docs: MCP App review recipe + root README pointer
 (#1578)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1578

Adds docs/mcp-app-review.md — the CLI-first → one-shot-web recipe for automated
MCP App review: `--app-info` probe → deep-link navigate → rendered widget, plus
OAuth-gated servers (stored-auth handoff, now honoring refresh_token per #1665),
SSH port-forward (both ports), and HTTP proxy support.

Adapted from PR #1510's reference doc to only document what actually merged and
to match the current implementation:
- Correct driver contract: `data-testid="connection-status"` + `data-status`
  /`data-error-message`/`data-deeplink`, `data-testid="open-app"`, and the
  `data-app-status="ready"` app lifecycle (not the reference's stale selectors).
- The zero-click `autoOpen` path (#1577) alongside the click-to-open variant.
- `--use-stored-auth` now refreshes a stored refresh_token (#1665), so the
  "token is not refreshed" caveat is replaced.

The per-client READMEs (web deep-link scheme + data-* contract, CLI handoff +
refresh + proxy) were updated in their own Wave 4 PRs; this adds the root README
pointer to docs/. Proxy/undici is already documented in the CLI README.

Part of the #1579 decomposition (Wave 4, docs — lands last).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 README.md              |  16 ++--
 docs/mcp-app-review.md | 206 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 215 insertions(+), 7 deletions(-)
 create mode 100644 docs/mcp-app-review.md

diff --git a/README.md b/README.md
index 1cc32ed6e..2e2b35419 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,8 @@ inspector/
 Each client has its own README with client-specific detail:
 [web](./clients/web/README.md) · [cli](./clients/cli/README.md) · [tui](./clients/tui/README.md) · [launcher](./clients/launcher/README.md).
 
+Task-oriented guides live under [`docs/`](./docs): [MCP server configuration](./docs/mcp-server-configuration.md) (the shared catalog/config/ad-hoc flags) and [Reviewing an MCP App](./docs/mcp-app-review.md) (the CLI-first → one-shot-web recipe for automated App-tool review: `--app-info` probe → deep-link navigate → rendered widget, plus OAuth handoff and proxy support).
+
 ## Setup
 
 Requires Node `>=22.19.0`.
@@ -120,13 +122,13 @@ Individual clients: `build:web`, `build:cli`, `build:tui`, `build:launcher`. The
 
 Each client self-validates from its own folder; the root scripts chain them. There is **no** aggregate root `test` script — use `validate` (fast) or `coverage` (the gate).
 
-| Script | What it does |
-| --- | --- |
-| `npm run validate` | `format:check` + `lint` + `build` + fast unit tests, per client. 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. |
-| `npm run smoke` | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web). |
-| `npm run ci` | **Mandatory pre-push command.** `validate` → `coverage` → `smoke` → Storybook. A true superset of GitHub CI. |
-| `npm run pack:verify` | Publish smoke — see [Publishing](#publishing). |
+| Script                | What it does                                                                                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run validate`    | `format:check` + `lint` + `build` + fast unit tests, per client. 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. |
+| `npm run smoke`       | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web).                                                                                |
+| `npm run ci`          | **Mandatory pre-push command.** `validate` → `coverage` → `smoke` → Storybook. A true superset of GitHub CI.                                                        |
+| `npm run pack:verify` | Publish smoke — see [Publishing](#publishing).                                                                                                                      |
 
 Per-client scripts exist too (`validate:web`, `coverage:cli`, `smoke:tui`, …). Run `npm run format` (per client) before committing — `validate` runs the non-fixing `format:check` and fails CI on any unformatted file.
 
diff --git a/docs/mcp-app-review.md b/docs/mcp-app-review.md
new file mode 100644
index 000000000..3e8ba6349
--- /dev/null
+++ b/docs/mcp-app-review.md
@@ -0,0 +1,206 @@
+# Reviewing an MCP App with the Inspector
+
+This recipe is for automated reviewers (CI, agents) that need to inspect an MCP
+server's **App tools** — the tools that bind a UI widget to a tool result via
+`_meta.ui.resourceUri`. It uses the **CLI for everything that has a JSON
+answer** and drops to a browser **only** to render the widget itself.
+
+The flow: probe with `--app-info` → build a deep link → drive the rendered
+widget, with no manual form-filling in between. It is the composition of the
+Wave-2 (spec-conformant Apps host) and Wave-3/4 (programmatic review path)
+work; each surface below links to the client README that owns its full contract.
+
+## 1. Probe: does the tool have an App, and what is its security posture?
+
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  --transport http --server-url https://example.com/mcp \
+  --method tools/call --tool-name <tool> --app-info
+```
+
+Stdout is one JSON line; the process exits **0** when the tool has an App and
+**2** (`no_app`) when it does not, so a shell `&&` chain can short-circuit.
+Example output for an App tool:
+
+```json
+{
+  "hasApp": true,
+  "toolName": "get_pros",
+  "resourceUri": "ui://pros/view.html",
+  "csp": { "connectDomains": ["https://api.example.com"] },
+  "permissions": { "clipboard": false },
+  "prefersBorder": true,
+  "resourceMimeType": "text/html"
+}
+```
+
+`csp` / `permissions` / `domain` come from the UI **resource** (per the spec
+they live on the resource, not the tool); `--app-info` reads the resource for
+you. Nothing here invokes the tool. To probe every tool at once, use
+`--method tools/list --app-info` (NDJSON, one line per tool, single
+connection). See [clients/cli/README.md](../clients/cli/README.md) for the full
+flag reference and exit-code map.
+
+## 2. Full result payload (still no browser)
+
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  --transport http --server-url https://example.com/mcp \
+  --method tools/call --tool-name <tool> --tool-args-json '{"zip":"10001"}'
+```
+
+Stdout is the pretty-printed `CallToolResult`; for App tools an
+`--- MCP App Info ---` block is appended. Add `--format json` to emit a single
+`{ "result": …, "appInfo": … }` object that pipes cleanly into `jq`.
+`--tool-args-json` passes the arguments verbatim (no `key=value` coercion), so
+`"012"` stays a string.
+
+## 3. Launch the web inspector once, loopback-only
+
+```bash
+TOKEN="$(openssl rand -hex 24)"
+HOST=127.0.0.1 CLIENT_PORT=6274 MCP_SANDBOX_PORT=6275 \
+MCP_AUTO_OPEN_ENABLED=false MCP_INSPECTOR_API_TOKEN="$TOKEN" \
+npx @modelcontextprotocol/inspector --web &
+```
+
+`HOST=127.0.0.1` binds the API and sandbox servers to loopback only. The token
+is also the deep-link auth gate (next step).
+
+## 4. One deep-link navigate → a rendered widget
+
+The deep-link URL shape (owned by
+[clients/web/README.md](../clients/web/README.md#deep-link-auto-connect)):
+
+```
+http://127.0.0.1:6274/?serverUrl=<url-encoded server URL>
+  &transport=http|sse
+  &autoConnect=<TOKEN>
+  &openApp=<tool name>
+  &appArgs=<base64url(JSON args)>
+  &autoOpen=<TOKEN>
+```
+
+`autoConnect` **must equal** `MCP_INSPECTOR_API_TOKEN`; the page rejects any
+other value, so a link minted by a third party cannot drive the connect.
+Loading the URL connects to the server, switches to the **Apps** tab, selects
+`openApp`, and pre-fills `appArgs` (merged **over** the tool's schema defaults,
+so a required-with-default field doesn't leave "Open App" disabled).
+
+`appArgs` is `base64url(JSON)`:
+
+```js
+const args = Buffer.from(JSON.stringify({ zip: "10001" }))
+  .toString("base64")
+  .replace(/\+/g, "-")
+  .replace(/\//g, "_")
+  .replace(/=+$/, "");
+```
+
+`autoOpen=<TOKEN>` (same token gate) fires "Open App" automatically — a tool
+call from a URL, which is why it is gated. Omit it to stop at the pre-filled
+form and click "Open App" yourself.
+
+The inspector exposes a stable `data-testid` / `data-*` contract (documented in
+[clients/web/README.md](../clients/web/README.md)) so a driver waits on
+deterministic signals instead of sleeping:
+
+```js
+// Playwright (or any driver). With autoOpen set, no click is needed.
+const url =
+  `http://127.0.0.1:6274/?serverUrl=${encodeURIComponent(serverUrl)}` +
+  `&transport=http&autoConnect=${TOKEN}` +
+  `&openApp=${tool}&appArgs=${args}&autoOpen=${TOKEN}`;
+
+await page.goto(url);
+// Connection surface: poll data-status; read data-error-message on failure.
+await page.waitForSelector(
+  '[data-testid="connection-status"][data-status="connected"]',
+);
+// App render lifecycle: idle → loading → ready (or error).
+await page.waitForSelector('[data-app-status="ready"]');
+await page.locator('[data-testid="apps-form"]').screenshot({ path: out });
+```
+
+Without `autoOpen`, click the button first:
+`await page.click('[data-testid="open-app"]')`, then wait on
+`[data-app-status="ready"]`. If the connect is rejected (bad token / non-http
+serverUrl), `[data-testid="connection-status"]` carries
+`data-deeplink="rejected"` and `data-error-message` — read those instead of
+scraping a toast.
+
+## 5. OAuth-gated servers
+
+When the target server requires OAuth, complete the flow once in the **web**
+inspector — the credential is written through the backend to
+`~/.mcp-inspector/storage/oauth.json`, so the **CLI** on the same machine can
+reuse it:
+
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  --transport http --server-url "$SERVER_URL" \
+  --use-stored-auth --method tools/list
+```
+
+`--use-stored-auth` looks up the stored state for `$SERVER_URL` (keyed by
+`new URL().href` normalization, so pass the same URL you gave the web
+inspector). When a `refresh_token` is stored it runs the OAuth refresh grant
+and injects the **fresh** access token, persisting the rotation back to the
+state file; otherwise it injects the stored access token. A failed refresh
+(revoked token) exits `3` (`auth_required`). Use `--wait-for-auth <sec>` to
+block until a human completes the flow in a browser, and `--print-handoff` to
+emit the deep link + port-forward command a remote VM needs (see
+[clients/cli/README.md](../clients/cli/README.md)).
+
+Connection state persists in `~/.mcp-inspector/` between runs. For a clean
+slate between reviews of different servers, `rm -rf ~/.mcp-inspector` before
+launching.
+
+## 6. Reaching the web inspector remotely (SSH port-forward)
+
+When the backend runs on another host and you want to complete OAuth or
+visually inspect a rendered App from your local browser, forward **both**
+ports:
+
+```bash
+ssh -L 6274:127.0.0.1:6274 -L 6275:127.0.0.1:6275 <remote-host>
+```
+
+Then open `http://127.0.0.1:6274/?MCP_INSPECTOR_API_TOKEN=$TOKEN` locally.
+
+- Use `127.0.0.1`, **not** `localhost` — the backend's origin guard checks the
+  literal `Origin` header against the configured `HOST`.
+- Forward `:6275` (`MCP_SANDBOX_PORT`) as well: the Apps tab renders widgets in
+  an iframe served from that second origin; without it the App frame stays
+  blank.
+- Forward the **same** local port number you bind on the remote — the browser
+  sends `Origin: http://127.0.0.1:<local-port>` and the backend compares it to
+  its own port.
+- The OAuth credential ends up in `~/.mcp-inspector/storage/oauth.json` on the
+  **remote** host, so a CLI invocation there can pick it up with
+  `--use-stored-auth` (§ 5).
+
+## 7. Reaching the target server through an HTTP proxy
+
+The CLI's outbound connections honor the standard `HTTPS_PROXY` / `HTTP_PROXY`
+/ `NO_PROXY` environment variables:
+
+```bash
+HTTPS_PROXY=http://proxy.example:3128 \
+npx @modelcontextprotocol/inspector --cli \
+  --transport http --server-url "$SERVER_URL" --method tools/list
+```
+
+Per-scheme routing and `NO_PROXY` exclusions are handled by undici's
+`EnvHttpProxyAgent`, imported lazily only when a proxy variable is set — runs
+without a proxy pay no cost. See
+[clients/cli/README.md](../clients/cli/README.md#http-proxy-support).
+
+## Local fixture
+
+The bundled test server includes an `mcp_app_demo` tool (preset `mcp_app_demo`
+
+- resource preset `mcp_app_demo_widget`) whose widget reports `size-changed`,
+  sends one `ui/message`, emits one log notification, and renders its received
+  `hostContext` — useful for verifying the host side of the UI protocol
+  end-to-end without a remote server.

From 0beb6e65afa4b1532a63856d766b302cd1f078c8 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:19:13 -0400
Subject: [PATCH 06/11] =?UTF-8?q?web:=20address=20#1670=20review=20?=
 =?UTF-8?q?=E2=80=94=20observable=20deep-link=20failures=20+=20correct=20s?=
 =?UTF-8?q?tale-config=20connect?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The ensure-phase addServer catch now records non-409 failures (read-only
  catalog, backend 5xx) on data-error-message instead of swallowing every
  error and leaving the deep link permanently stuck at the guard with no
  signal (review finding #1).
- Split the update and connect phases across renders (new deepLinkUpdateRef):
  connect only once servers reflects the updated config, so onToggleConnection
  (which reads serversRef, synced by an earlier passive effect) builds the
  client from the fresh transport rather than the pre-update config (finding
  #2 — the exact case deepLinkConfigEquals was added for).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/web/src/App.tsx | 75 ++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 30 deletions(-)

diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 5eb7f760f..1511ce27c 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -1381,6 +1381,7 @@ function App() {
     return [parsed, deepLinkParseStatus(search, parsed)];
   }, []);
   const deepLinkEnsureRef = useRef(false);
+  const deepLinkUpdateRef = useRef(false);
   const deepLinkConnectRef = useRef(false);
 
   const showReAuthBanner = useCallback(
@@ -2518,15 +2519,20 @@ function App() {
   }, [inspectorClient, finalizeExplicitDisconnect]);
 
   // Deep-link auto-connect (the URL-driven case of #1183). `useServers`
-  // hydrates asynchronously (initial `servers` is `[]`), so this effect runs
-  // in two phases: first render attempts a one-shot `addServer` (a 409 means
-  // the row already exists on disk and hydration will surface it); a later
-  // render where `servers` actually contains the deep-link row then updates the
-  // URL if it has changed and connects. Connecting in the same closure as
-  // `addServer` would resolve against a stale (empty) `servers` and silently
-  // no-op. The OAuth callback path takes precedence; a deep link on
-  // `/oauth/callback` would be a misconfiguration, and the callback handler
-  // clears the URL.
+  // hydrates asynchronously (initial `servers` is `[]`), so this effect runs in
+  // discrete phases keyed on what `servers` currently reflects, one per render:
+  //   1. ensure — no row yet: one-shot `addServer`.
+  //   2. update — row present but its persisted config differs from the deep
+  //      link (a stale transport/url from an earlier load under the stable
+  //      `deep-link` id): `updateServer`, then return so the effect re-runs.
+  //   3. connect — row present AND its config already matches: connect.
+  // Splitting update and connect across renders (rather than awaiting both in
+  // one closure) is what makes the connect correct: `onToggleConnection` reads
+  // the target from `serversRef`, which an earlier passive effect syncs from
+  // `servers` — so connecting only once `servers` reflects the updated config
+  // guarantees the client is built from the fresh transport, not the stale one.
+  // The OAuth callback path takes precedence; a deep link on `/oauth/callback`
+  // would be a misconfiguration, and the callback handler clears the URL.
   useEffect(() => {
     if (!deepLink) return;
     if (window.location.pathname === OAUTH_CALLBACK_PATH) return;
@@ -2535,33 +2541,42 @@ function App() {
     if (!existing) {
       if (deepLinkEnsureRef.current) return;
       deepLinkEnsureRef.current = true;
-      void addServer(deepLink.serverId, deepLink.serverConfig).catch(() => {
-        // 409 = already on disk; hydration will surface it on a later render.
+      void addServer(deepLink.serverId, deepLink.serverConfig).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        // A 409 ("already exists") means the row is on disk and hydration will
+        // surface it on a later render, so the connect phase still proceeds —
+        // swallow it. Any other failure (read-only catalog, backend 5xx) would
+        // otherwise leave the deep link permanently stuck at this guard with no
+        // signal, so record it on the machine-readable error surface.
+        if (!message.includes("already exists")) recordConnectError(message);
+      });
+      return;
+    }
+
+    if (!deepLinkConfigEquals(existing.config, deepLink.serverConfig)) {
+      if (deepLinkUpdateRef.current) return;
+      deepLinkUpdateRef.current = true;
+      void updateServer(
+        deepLink.serverId,
+        deepLink.serverId,
+        deepLink.serverConfig,
+      ).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        recordConnectError(message);
       });
       return;
     }
 
     if (deepLinkConnectRef.current) return;
     deepLinkConnectRef.current = true;
-    void (async () => {
-      if (!deepLinkConfigEquals(existing.config, deepLink.serverConfig)) {
-        await updateServer(
-          deepLink.serverId,
-          deepLink.serverId,
-          deepLink.serverConfig,
-        );
-      }
-      if (activeServerId !== deepLink.serverId) {
-        await onToggleConnection(deepLink.serverId);
-      }
-    })().catch((err) => {
-      // Surface deep-link automation failures (updateServer 5xx, connect throw)
-      // on the machine-readable error attribute instead of dropping them. The
-      // toast still fires from inside `onToggleConnection` for the common
-      // cases; this catch covers the rest.
-      const message = err instanceof Error ? err.message : String(err);
-      recordConnectError(message);
-    });
+    if (activeServerId !== deepLink.serverId) {
+      void onToggleConnection(deepLink.serverId).catch((err) => {
+        // The toast fires from inside `onToggleConnection` for the common
+        // cases; this catch covers the rest (surfaced on `data-error-message`).
+        const message = err instanceof Error ? err.message : String(err);
+        recordConnectError(message);
+      });
+    }
   }, [
     deepLink,
     servers,

From 59f3bd92a4df7df23b650711167654e08dfd8f1a Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:21:59 -0400
Subject: [PATCH 07/11] =?UTF-8?q?cli:=20address=20#1673=20review=20?=
 =?UTF-8?q?=E2=80=94=20refresh=20fallback,=200600=20write,=20distinct=20co?=
 =?UTF-8?q?de?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Refresh failure now falls back to injecting a still-present stored access
  token instead of hard-exiting 3, so a transient auth-server hiccup doesn't
  regress a previously-working invocation (review #1). Only a failure with no
  access token to fall back on surfaces as exit 3.
- Persist rotated tokens via the shared writeStoreFile (0o600 + mkdir -p)
  instead of a raw writeFile, so the secrets file keeps owner-only perms
  identical to the web backend (review #2).
- Missing clientInformation now throws the distinct no_client_information
  envelope code rather than reusing no_stored_token (review #5a).
- Docs: --wait-for-auth no longer claims parity with --use-stored-auth (it
  injects the freshly-landed token without refreshing); noted the
  always-refresh rotation/concurrency caveat (review #3, #4).
- Tests: discovery-returns-undefined metadata path, no_client_information
  code, and an e2e refresh-failure → access-token fallback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/cli/README.md                     |  6 +-
 clients/cli/__tests__/stored-auth.test.ts | 90 +++++++++++++++++++++++
 clients/cli/src/cli.ts                    | 26 ++++++-
 3 files changed, 116 insertions(+), 6 deletions(-)

diff --git a/clients/cli/README.md b/clients/cli/README.md
index 6e9126ab6..83dbe53d6 100644
--- a/clients/cli/README.md
+++ b/clients/cli/README.md
@@ -194,13 +194,15 @@ For the common case where OAuth was already completed in the **web inspector on
 | Option                  | Description                                                                                                                                                                                    |
 | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--use-stored-auth`     | Read the stored auth for `--server-url` and inject `Authorization: Bearer`. When a `refresh_token` is stored, the CLI runs the OAuth refresh grant first and injects the **fresh** access token (persisting the rotation); otherwise it injects the stored access token. Exits `3` (`no_stored_token`) — listing the stored keys — when nothing matches. Requires `--server-url`. |
-| `--wait-for-auth <sec>` | Poll the OAuth state file (500 ms interval) until a token for `--server-url` appears, then proceed as if `--use-stored-auth` were set. Times out at `<sec>` with exit `3` (`auth_wait_timeout`). Use after handing off to a human to complete OAuth in a browser. |
+| `--wait-for-auth <sec>` | Poll the OAuth state file (500 ms interval) until an access token for `--server-url` appears, then inject it. Times out at `<sec>` with exit `3` (`auth_wait_timeout`). Use after handing off to a human to complete OAuth in a browser. Unlike `--use-stored-auth`, this injects the freshly-landed access token directly (a token that just completed the browser flow is not expired), so it does **not** run the refresh grant. |
 | `--list-stored-auth`    | Print `{ oauthStatePath, storedServerUrls }` (the server keys that currently have a token) and exit. No server connection is made.                                                              |
 | `--print-handoff`       | Print a JSON handoff block (`deepLink`, `portForwardCmd`, `oauthStatePath`, `apiToken`) for `--server-url` and exit — everything a script/remote VM needs to drive the browser-side OAuth dance. Requires `--server-url`. |
 
 **State-file resolution** follows `MCP_INSPECTOR_OAUTH_STATE_PATH` → `<MCP_STORAGE_DIR>/oauth.json` → `~/.mcp-inspector/storage/oauth.json` — the same precedence the rest of the Inspector uses, so the CLI and web backend agree on the file. Server keys are canonicalised with `new URL().href` (the scheme the web store writes), so a trailing-slash or case mismatch between the URL a human opened and the one the agent passed still resolves.
 
-**Token refresh (#1665).** When the stored server state carries a `refresh_token` (plus the `clientInformation` the web inspector persists after a completed flow), `--use-stored-auth` runs the SDK's OAuth `refresh_token` grant to mint a fresh access token before connecting, then writes the rotated tokens back to the state file so web and CLI stay consistent. The auth-server metadata is reused from the stored state, or discovered from `--server-url` when absent. This covers both an absent and an expired stored access token — the persisted blob carries no expiry, so the refresh token is treated as the durable credential. A failed refresh (revoked/expired refresh token) exits `3` (`auth_required`, envelope `refresh_failed`); re-complete the flow in the web inspector and retry. Without a stored `refresh_token` the access token is injected as-is, and a stale one surfaces as an HTTP `401` → exit `3`.
+**Token refresh (#1665).** When the stored server state carries a `refresh_token` (plus the `clientInformation` the web inspector persists after a completed flow), `--use-stored-auth` runs the SDK's OAuth `refresh_token` grant to mint a fresh access token before connecting, then writes the rotated tokens back to the state file (owner-only `0o600`, via the shared store writer) so web and CLI stay consistent. The auth-server metadata is reused from the stored state, or discovered from `--server-url` when absent. This covers both an absent and an expired stored access token — the persisted blob carries no expiry, so the refresh token is treated as the durable credential. If the refresh fails (revoked token, transient auth-server error) **and** a stored access token is also present, the CLI falls back to injecting that token rather than hard-failing; only when there is nothing to fall back on does it exit `3` (`auth_required`, envelope `refresh_failed`). Without a stored `refresh_token` the access token is injected as-is, and a stale one surfaces as an HTTP `401` → exit `3`.
+
+Because there is no stored expiry, a `refresh_token` is refreshed on every `--use-stored-auth` run. Two consequences with rotating refresh tokens: two concurrent invocations against the same state file race the single-use token (one wins), and a crash between a successful grant and the write-back leaves the rotated token unsaved. Both are narrow; re-authorize in the web inspector to recover.
 
 **Short-circuit modes.** `--list-stored-auth` and `--print-handoff` each print their output and exit without connecting to a server; they ignore the method/target flags. They are mutually exclusive — if both are passed, `--list-stored-auth` takes precedence.
 
diff --git a/clients/cli/__tests__/stored-auth.test.ts b/clients/cli/__tests__/stored-auth.test.ts
index 8e83f95d2..0661ac061 100644
--- a/clients/cli/__tests__/stored-auth.test.ts
+++ b/clients/cli/__tests__/stored-auth.test.ts
@@ -111,6 +111,46 @@ describe("refreshStoredAuthToken", () => {
     }
   });
 
+  it("passes metadata=undefined to the refresh grant when discovery returns nothing", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+        clientInformation: { client_id: "cid" },
+      },
+    });
+    try {
+      const refresh = vi.fn().mockResolvedValue(freshTokens);
+      const discover = vi.fn().mockResolvedValue(undefined);
+      const token = await refreshStoredAuthToken(SERVER, path, {
+        refresh,
+        discover,
+      });
+      expect(token).toBe("refreshed-access-token");
+      const [, opts] = refresh.mock.calls[0]!;
+      expect(opts.metadata).toBeUndefined();
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
+  it("uses the distinct no_client_information code when client info is missing", async () => {
+    const path = writeOAuthFixture({
+      [SERVER]: {
+        tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
+      },
+    });
+    try {
+      await expect(
+        refreshStoredAuthToken(SERVER, path, { refresh: vi.fn() }),
+      ).rejects.toMatchObject({
+        exitCode: 3,
+        envelope: { code: "no_client_information" },
+      });
+    } finally {
+      rmSync(path, { force: true });
+    }
+  });
+
   it("throws AUTH_REQUIRED when no refresh token is stored", async () => {
     const path = writeOAuthFixture({
       [SERVER]: {
@@ -394,6 +434,56 @@ describe("--use-stored-auth", () => {
       await new Promise<void>((resolve) => tokenServer.close(() => resolve()));
     }
   });
+
+  it("falls back to the stored access token when the refresh grant fails (#1665 review #1)", async () => {
+    // Token endpoint that rejects the refresh grant, so the CLI must fall back
+    // to the still-present stored access token instead of hard-failing.
+    const tokenServer: Server = createServer((_req, res) => {
+      res.writeHead(400, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "invalid_grant" }));
+    });
+    await new Promise<void>((resolve) => tokenServer.listen(0, resolve));
+    const addr = tokenServer.address();
+    const tokenBase =
+      typeof addr === "object" && addr ? `http://127.0.0.1:${addr.port}` : "";
+    const fixture = writeOAuthFixture({
+      [serverUrl]: {
+        tokens: {
+          access_token: "still-usable-access",
+          refresh_token: "old-refresh",
+          token_type: "Bearer",
+        },
+        clientInformation: { client_id: "cid", client_secret: "sec" },
+        serverMetadata: {
+          issuer: tokenBase,
+          token_endpoint: `${tokenBase}/token`,
+          response_types_supported: ["code"],
+          grant_types_supported: ["authorization_code", "refresh_token"],
+          token_endpoint_auth_methods_supported: ["client_secret_post"],
+        },
+      },
+    });
+    try {
+      const result = await runCli(
+        [
+          "--transport",
+          "http",
+          "--server-url",
+          serverUrl,
+          "--use-stored-auth",
+          "--method",
+          "tools/list",
+        ],
+        { env: { MCP_INSPECTOR_OAUTH_STATE_PATH: fixture } },
+      );
+      expectCliSuccess(result);
+      const last = server.getRecordedRequests().at(-1)!;
+      expect(last.headers?.authorization).toBe("Bearer still-usable-access");
+    } finally {
+      rmSync(fixture, { force: true });
+      await new Promise<void>((resolve) => tokenServer.close(() => resolve()));
+    }
+  });
 });
 
 describe("--list-stored-auth", () => {
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 3e8f244aa..f9bafd5ea 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -34,6 +34,7 @@ import {
   type OAuthPersistSnapshot,
 } from "@inspector/core/auth/oauth-persist.js";
 import { getAuthorizationServerUrl } from "@inspector/core/auth/discovery.js";
+import { writeStoreFile } from "@inspector/core/storage/store-io.js";
 import {
   refreshAuthorization,
   discoverAuthorizationServerMetadata,
@@ -595,7 +596,7 @@ export async function refreshStoredAuthToken(
     throw new CliExitCodeError(
       EXIT_CODES.AUTH_REQUIRED,
       `Stored auth for ${normalizeServerUrl(serverUrl)} has a refresh token but no client information; cannot refresh. Re-authorize in the web inspector.`,
-      { code: "no_stored_token", url: serverUrl },
+      { code: "no_client_information", url: serverUrl },
     );
   }
 
@@ -624,9 +625,11 @@ export async function refreshStoredAuthToken(
 
   // Persist the rotated tokens back under the same key, preserving every other
   // server entry and the idpSessions block, so web and CLI stay consistent.
+  // Route through the shared `writeStoreFile` (not a raw `writeFile`) so the
+  // secrets file keeps its owner-only `0o600` mode + `mkdir -p`, identical to
+  // how the web backend's OAuth persist backend writes it.
   servers[found.key] = { ...found.state, tokens };
-  const { writeFile } = await import("node:fs/promises");
-  await writeFile(statePath, serializeOAuthPersistBlob(snapshot), "utf8");
+  await writeStoreFile(statePath, serializeOAuthPersistBlob(snapshot));
 
   return tokens.access_token;
 }
@@ -1077,7 +1080,22 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
       const servers = await readOAuthServers(oauthStatePath);
       const stored = findStoredServerState(servers, options.serverUrl);
       if (stored?.state.tokens?.refresh_token) {
-        token = await refreshStoredAuthToken(options.serverUrl, oauthStatePath);
+        const storedAccess = stored.state.tokens.access_token;
+        try {
+          token = await refreshStoredAuthToken(
+            options.serverUrl,
+            oauthStatePath,
+          );
+        } catch (err) {
+          // A failed refresh (transient auth-server hiccup, missing client
+          // info) shouldn't turn a previously-working invocation into a hard
+          // failure when a still-usable access token is also on disk — fall
+          // back to injecting it (a genuinely stale one surfaces as HTTP 401 →
+          // exit 3, the same as without a refresh token). With no stored access
+          // token to fall back on, the refresh error stands.
+          if (!storedAccess) throw err;
+          token = storedAccess;
+        }
       } else {
         const found = findStoredToken(servers, options.serverUrl);
         if (!found) {

From ac49000738e63a46185b803e56d087b16a67f60d Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:23:19 -0400
Subject: [PATCH 08/11] =?UTF-8?q?cli:=20address=20#1672=20review=20nits=20?=
 =?UTF-8?q?=E2=80=94=20correct=20doc=20ref=20+=20hoist=20normalizeServerUr?=
 =?UTF-8?q?l?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The JSDoc referenced a non-existent `resolveServerConfig`; name the real
  `resolveServerConfigs` (core/mcp/node/config.ts) in plain text (it isn't
  imported here, so an @link wouldn't resolve).
- Hoist the doubly-computed `normalizeServerUrl(serverUrl)` in buildHandoff to
  a single `normalizedUrl` reused for the query param and the serverUrl field.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/cli/src/cli.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index c4ac4e7ac..cfdc2c3cd 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -541,7 +541,8 @@ async function waitForStoredToken(
 
 /**
  * Derive the web deep-link `transport` value (`http` | `sse`) for a handoff.
- * Mirrors {@link resolveServerConfig}'s URL-path auto-detection (`/sse` → sse,
+ * Mirrors `resolveServerConfigs` (core/mcp/node/config.ts) URL-path
+ * auto-detection (`/sse` → sse,
  * everything else → http) but, unlike that resolver, defaults to `http` instead
  * of throwing on an ambiguous path — the handoff is best-effort, and the web
  * {@link parseDeepLink} likewise defaults an unknown/missing transport to http.
@@ -583,18 +584,19 @@ function buildHandoff(
   // Treat an empty MCP_INSPECTOR_API_TOKEN the same as unset — an empty token
   // can't satisfy the deep-link autoConnect gate.
   const apiToken = process.env.MCP_INSPECTOR_API_TOKEN || undefined;
+  const normalizedUrl = normalizeServerUrl(serverUrl);
   // Canonical #1576 deep-link shape: the normalized serverUrl (matching the
   // OAuth-store key form the web app reuses) plus the resolved transport, gated
   // by `autoConnect=<token>` — the same per-launch token the web parser
   // requires. Omitted when no token is set; the `note` below flags that the
   // link will be rejected until the web inspector is launched with a token.
   const params = new URLSearchParams({
-    serverUrl: normalizeServerUrl(serverUrl),
+    serverUrl: normalizedUrl,
     transport: deepLinkTransport(serverUrl, transport),
   });
   if (apiToken) params.set("autoConnect", apiToken);
   return {
-    serverUrl: normalizeServerUrl(serverUrl),
+    serverUrl: normalizedUrl,
     deepLink: `http://${host}:${clientPort}/?${params.toString()}`,
     portForwardCmd: `coder port-forward <workspace> --tcp ${clientPort}:${clientPort} --tcp ${sandboxPort}:${sandboxPort}`,
     oauthStatePath: statePath,

From b8cd4fd431223bab1715af697ab919b92732b62c Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:24:20 -0400
Subject: [PATCH 09/11] =?UTF-8?q?web:=20address=20#1671=20review=20nit=20?=
 =?UTF-8?q?=E2=80=94=20simplify=20redundant=20autoOpen=20guard?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DeepLink.autoOpen is a non-optional boolean, so the `?? false` was dead once
openApp was truthy. Collapse to Boolean(deepLink?.openApp && deepLink.autoOpen)
— still false when there's no deep link, still gated on openApp so a malformed
autoOpen-without-openApp link can't fire.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 .../web/src/components/views/InspectorView/InspectorView.tsx  | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/clients/web/src/components/views/InspectorView/InspectorView.tsx b/clients/web/src/components/views/InspectorView/InspectorView.tsx
index 29d561196..cd18bdedc 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.tsx
@@ -1190,9 +1190,7 @@ export function InspectorView({
                 onOpenApp={onOpenApp}
                 onCloseApp={onCloseApp}
                 onError={onAppError}
-                autoOpen={
-                  Boolean(deepLink?.openApp) && (deepLink?.autoOpen ?? false)
-                }
+                autoOpen={Boolean(deepLink?.openApp && deepLink.autoOpen)}
               />
             </ScreenStage>
             <ScreenStage active={activeTab === "Prompts"}>

From e6278aea0fd2251217f67643c72a7b22fcd73f46 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:25:20 -0400
Subject: [PATCH 10/11] =?UTF-8?q?docs:=20address=20#1674=20review=20?=
 =?UTF-8?q?=E2=80=94=20fix=20broken=20link=20+=20list=20rendering?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Root README no longer links to docs/mcp-server-configuration.md (not yet
  ported to v2); keep only the mcp-app-review.md pointer (review #3).
- Collapse the Local-fixture parenthetical onto one line so prettier no longer
  renders '- resource preset …' as a mid-sentence bullet (review #5).

Findings #1/#2 (documents unmerged #1576/#1577/#1665 behavior) and #4 (the
web-README #deep-link-auto-connect anchor) resolve in the Wave 4 rollup, which
lands this doc together with those code PRs — the reviewer noted the same.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 README.md              |  2 +-
 docs/mcp-app-review.md | 11 +++++------
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 2e2b35419..f9bf664de 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ inspector/
 Each client has its own README with client-specific detail:
 [web](./clients/web/README.md) · [cli](./clients/cli/README.md) · [tui](./clients/tui/README.md) · [launcher](./clients/launcher/README.md).
 
-Task-oriented guides live under [`docs/`](./docs): [MCP server configuration](./docs/mcp-server-configuration.md) (the shared catalog/config/ad-hoc flags) and [Reviewing an MCP App](./docs/mcp-app-review.md) (the CLI-first → one-shot-web recipe for automated App-tool review: `--app-info` probe → deep-link navigate → rendered widget, plus OAuth handoff and proxy support).
+Task-oriented guides live under [`docs/`](./docs) — see [Reviewing an MCP App](./docs/mcp-app-review.md), the CLI-first → one-shot-web recipe for automated App-tool review: `--app-info` probe → deep-link navigate → rendered widget, plus OAuth handoff and proxy support.
 
 ## Setup
 
diff --git a/docs/mcp-app-review.md b/docs/mcp-app-review.md
index 3e8ba6349..c6ca251bd 100644
--- a/docs/mcp-app-review.md
+++ b/docs/mcp-app-review.md
@@ -198,9 +198,8 @@ without a proxy pay no cost. See
 
 ## Local fixture
 
-The bundled test server includes an `mcp_app_demo` tool (preset `mcp_app_demo`
-
-- resource preset `mcp_app_demo_widget`) whose widget reports `size-changed`,
-  sends one `ui/message`, emits one log notification, and renders its received
-  `hostContext` — useful for verifying the host side of the UI protocol
-  end-to-end without a remote server.
+The bundled test server includes an `mcp_app_demo` tool (presets `mcp_app_demo`
+and `mcp_app_demo_widget`) whose widget reports `size-changed`, sends one
+`ui/message`, emits one log notification, and renders its received `hostContext`
+— useful for verifying the host side of the UI protocol end-to-end without a
+remote server.

From 7411fc886e86108ad013e7f2231a7c8898d6884a Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sat, 11 Jul 2026 23:41:10 -0400
Subject: [PATCH 11/11] =?UTF-8?q?web:=20address=20rollup=20review=20#1=20?=
 =?UTF-8?q?=E2=80=94=20deep-link=20reconnect=20on=20restored=20activeServe?=
 =?UTF-8?q?rId?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gate the deep-link connect phase on 'not already connected' rather than on
activeServerId identity: if a prior session restored activeServerId to the
'deep-link' id while disconnected, the old guard marked the ref consumed and
never connected, so reloading the same deep-link URL silently didn't auto-
connect. onToggleConnection only disconnects when the id is active AND status
is connected, so the new condition also avoids toggling a live connection off.

Also documents (rollup review #3) that pre-selecting a deep-linked app
deliberately bypasses AppsScreen.handleSelect's no-input auto-launch — a URL
must not fire a tool call without the token-gated autoOpen.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BrihGWcrM9JGRyu41nzZYw
---
 clients/web/src/App.tsx                              | 12 +++++++++++-
 .../components/views/InspectorView/InspectorView.tsx |  7 +++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 1511ce27c..350213f4c 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -2569,7 +2569,16 @@ function App() {
 
     if (deepLinkConnectRef.current) return;
     deepLinkConnectRef.current = true;
-    if (activeServerId !== deepLink.serverId) {
+    // Connect unless we're already *connected* to the deep-link server. Gating
+    // on `activeServerId` identity alone would skip the connect when a prior
+    // session restored `activeServerId` to the `deep-link` id while the socket
+    // is disconnected — a reload of the same deep-link URL would then silently
+    // never connect. `onToggleConnection` only disconnects when the id is the
+    // active one AND the status is connected, so this condition also avoids
+    // toggling a live connection off.
+    const alreadyConnected =
+      activeServerId === deepLink.serverId && connectionStatus === "connected";
+    if (!alreadyConnected) {
       void onToggleConnection(deepLink.serverId).catch((err) => {
         // The toast fires from inside `onToggleConnection` for the common
         // cases; this catch covers the rest (surfaced on `data-error-message`).
@@ -2581,6 +2590,7 @@ function App() {
     deepLink,
     servers,
     activeServerId,
+    connectionStatus,
     addServer,
     updateServer,
     onToggleConnection,
diff --git a/clients/web/src/components/views/InspectorView/InspectorView.tsx b/clients/web/src/components/views/InspectorView/InspectorView.tsx
index cd18bdedc..d8d335cd0 100644
--- a/clients/web/src/components/views/InspectorView/InspectorView.tsx
+++ b/clients/web/src/components/views/InspectorView/InspectorView.tsx
@@ -892,6 +892,13 @@ export function InspectorView({
       ...collectSchemaDefaults(target.inputSchema),
       ...deepLink.appArgs,
     };
+    // Seed the selection directly rather than routing through
+    // AppsScreen.handleSelect. This deliberately bypasses handleSelect's
+    // no-input-app auto-launch: a deep link must never invoke a tool against
+    // the target server unless the token-gated `autoOpen` is set — even a
+    // no-input app waits for that explicit signal (or a manual "Open App"
+    // click), matching the security stance that a crafted URL alone can't fire
+    // a tool call.
     onActiveTabChange("Apps");
     onAppsUiChange({
       ...appsUi,