@modelcontextprotocol/inspector 2.0.0 → 2.2.0

package/clients/cli/build/index.js

@@ -83,9 +83,6 @@ function withConnectTimeout(settings, connectionTimeout) {
   };
 }
 
-// ../../core/auth/node/secret-store.ts
-import { AsyncEntry, findCredentialsAsync } from "@napi-rs/keyring";
-
 // ../../core/auth/secret-fields.ts
 var SECRET_FIELD_OAUTH_CLIENT_SECRET = "oauth-client-secret";
 var SECRET_FIELD_IDP_CLIENT_SECRET = "idp-client-secret";
@@ -93,6 +90,41 @@ var envSecretField = (envKey) => `env:${envKey}`;
 
 // ../../core/auth/node/secret-store.ts
 var SERVICE_NAME = "mcp-inspector";
+var keyringLoad;
+var KeyringModuleShapeError = class extends Error {
+  constructor(detail, options) {
+    super(`@napi-rs/keyring loaded but ${detail}`, options);
+    this.name = "KeyringModuleShapeError";
+  }
+};
+var checkKeyringShape = (mod) => {
+  try {
+    if (typeof mod.AsyncEntry === "function" && typeof mod.findCredentialsAsync === "function") {
+      return { ok: true, mod };
+    }
+    return {
+      ok: false,
+      err: new KeyringModuleShapeError(
+        "did not expose AsyncEntry / findCredentialsAsync"
+      )
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      err: new KeyringModuleShapeError(
+        `its exports could not be read: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      )
+    };
+  }
+};
+var loadKeyring = () => {
+  keyringLoad ??= import("@napi-rs/keyring").then(
+    checkKeyringShape,
+    (err) => ({ ok: false, err })
+  );
+  return keyringLoad;
+};
 function parseAccount(account) {
   const idx = account.indexOf(":");
   if (idx <= 0 || idx === account.length - 1) return null;
@@ -104,16 +136,31 @@ function parseAccount(account) {
 var buildAccount = (serverId, field) => `${serverId}:${field}`;
 var KeychainUnavailableError = class extends Error {
   constructor(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
     super(
-      `OS keychain is not available. On Linux, install libsecret / gnome-keyring. Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`
+      `OS keychain is not available. ${hintFor(cause, message)} Underlying error: ${message}`
     );
     this.name = "KeychainUnavailableError";
   }
 };
+var hintFor = (cause, message) => {
+  if (cause instanceof KeyringModuleShapeError) {
+    return `The @napi-rs/keyring package loaded but does not expose the API this build expects \u2014 most likely a version or packaging mismatch; reinstall the Inspector, and report this if it persists.`;
+  }
+  if (message.includes("Cannot find native binding")) {
+    return `The @napi-rs/keyring platform package for this OS is missing or unavailable \u2014 reinstall the Inspector (for npx, clear the npx cache under your npm cache directory first).`;
+  }
+  return `On Linux, install libsecret / gnome-keyring.`;
+};
 var KeyringSecretStore = class {
   async get(serverId, field) {
-    const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
     try {
+      const keyring = await loadKeyring();
+      if (!keyring.ok) return null;
+      const entry = new keyring.mod.AsyncEntry(
+        SERVICE_NAME,
+        buildAccount(serverId, field)
+      );
       const v2 = await entry.getPassword();
       return v2 ?? null;
     } catch {
@@ -121,16 +168,27 @@ var KeyringSecretStore = class {
     }
   }
   async set(serverId, field, value) {
-    const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
     try {
+      const keyring = await loadKeyring();
+      if (!keyring.ok) throw new KeychainUnavailableError(keyring.err);
+      const entry = new keyring.mod.AsyncEntry(
+        SERVICE_NAME,
+        buildAccount(serverId, field)
+      );
       await entry.setPassword(value);
     } catch (err) {
+      if (err instanceof KeychainUnavailableError) throw err;
       throw new KeychainUnavailableError(err);
     }
   }
   async delete(serverId, field) {
-    const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
     try {
+      const keyring = await loadKeyring();
+      if (!keyring.ok) return;
+      const entry = new keyring.mod.AsyncEntry(
+        SERVICE_NAME,
+        buildAccount(serverId, field)
+      );
       await entry.deleteCredential();
     } catch {
     }
@@ -138,7 +196,9 @@ var KeyringSecretStore = class {
   async deleteAllForServer(serverId) {
     let creds;
     try {
-      creds = await findCredentialsAsync(SERVICE_NAME);
+      const keyring = await loadKeyring();
+      if (!keyring.ok) return;
+      creds = await keyring.mod.findCredentialsAsync(SERVICE_NAME);
     } catch {
       return;
     }
@@ -536,9 +596,13 @@ function loadMcpServersConfig(configPath, writable) {
     return { ...config, mcpServers: normalizedServers };
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Error loading configuration: ${error.message}`);
+      throw new Error(`Error loading configuration: ${error.message}`, {
+        cause: error
+      });
     }
-    throw new Error("Error loading configuration: Unknown error");
+    throw new Error("Error loading configuration: Unknown error", {
+      cause: error
+    });
   }
 }
 function loadServerFromConfig(configPath, serverName, writable) {
@@ -1067,7 +1131,9 @@ function parseHttpUrl(value, label) {
     return new URL(trimmed);
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid ${label}: "${trimmed}" (${detail})`);
+    throw new Error(`Invalid ${label}: "${trimmed}" (${detail})`, {
+      cause: err
+    });
   }
 }
 var parseOAuthCallbackParams = (location) => {
@@ -2100,6 +2166,7 @@ import { Client } from "@modelcontextprotocol/client";
 
 // ../../core/json/xMcpHeader.ts
 var X_MCP_HEADER_KEY = "x-mcp-header";
+var MCP_PARAM_HEADER_PREFIX = "Mcp-Param-";
 var RFC9110_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 var PERMITTED_X_MCP_HEADER_TYPES = /* @__PURE__ */ new Set([
   "string",
@@ -2189,6 +2256,66 @@ function scanXMcpHeaderDeclarations(inputSchema) {
   const fault = visit(inputSchema, [], true);
   return fault === void 0 ? { valid: true, declarations } : { valid: false, reason: fault };
 }
+var BASE64_SENTINEL_PREFIX = "=?base64?";
+var BASE64_SENTINEL_SUFFIX = "?=";
+function mcpParamPrimitiveToString(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return void 0;
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      return void 0;
+    }
+    return String(value);
+  }
+  return void 0;
+}
+function needsBase64(s2) {
+  if (s2.length === 0) return true;
+  if (s2.startsWith(BASE64_SENTINEL_PREFIX) && s2.endsWith(BASE64_SENTINEL_SUFFIX)) {
+    return true;
+  }
+  if (s2 !== s2.trim()) return true;
+  for (let i2 = 0; i2 < s2.length; i2++) {
+    const c = s2.codePointAt(i2);
+    if (c === 9 || c >= 32 && c <= 126) continue;
+    return true;
+  }
+  return false;
+}
+function utf8ToBase64(s2) {
+  const bytes = new TextEncoder().encode(s2);
+  let bin = "";
+  for (const b2 of bytes) bin += String.fromCodePoint(b2);
+  return btoa(bin);
+}
+function encodeMcpParamValue(value) {
+  return needsBase64(value) ? `${BASE64_SENTINEL_PREFIX}${utf8ToBase64(value)}${BASE64_SENTINEL_SUFFIX}` : value;
+}
+function valueAtPath(root, path2) {
+  let node = root;
+  for (const key of path2) {
+    if (node === null || typeof node !== "object") return void 0;
+    node = node[key];
+  }
+  return node;
+}
+function buildMcpParamHeaders(declarations, args) {
+  const out = {};
+  for (const decl of declarations) {
+    const raw = valueAtPath(args, decl.path);
+    if (raw === void 0 || raw === null) continue;
+    const stringValue = mcpParamPrimitiveToString(raw);
+    if (stringValue === void 0) continue;
+    out[`${MCP_PARAM_HEADER_PREFIX}${decl.headerName}`] = encodeMcpParamValue(stringValue);
+  }
+  return out;
+}
+function mcpParamHeadersForTool(tool, args) {
+  const scan = scanXMcpHeaderDeclarations(tool.inputSchema);
+  if (!scan.valid || scan.declarations.length === 0) return {};
+  return buildMcpParamHeaders(scan.declarations, args);
+}
 
 // ../../core/mcp/messageTrackingTransport.ts
 var MessageTrackingTransport = class {
@@ -3285,7 +3412,9 @@ function getAuthorizationServerUrl(serverUrl, resourceMetadata) {
     return new URL("/", serverUrl);
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid MCP server URL: "${serverUrl}" (${detail})`);
+    throw new Error(`Invalid MCP server URL: "${serverUrl}" (${detail})`, {
+      cause: err
+    });
   }
 }
 
@@ -4560,6 +4689,7 @@ async function* parseSSE(reader) {
 }
 var RemoteClientTransport = class {
   _sessionId = void 0;
+  _protocolVersion = void 0;
   eventStreamReader = null;
   eventStreamAbort = null;
   eventStreamConsumeTask = null;
@@ -4582,6 +4712,21 @@ var RemoteClientTransport = class {
   getRemoteBackendSessionId() {
     return this._sessionId;
   }
+  /**
+   * The SDK Client calls this with the negotiated protocol version as soon as
+   * `initialize` resolves — before it sends `notifications/initialized` — so an
+   * HTTP transport can stamp `Mcp-Protocol-Version` on every later request.
+   *
+   * Here the real upstream transport lives on the backend, so we can only
+   * record the version and forward it on the next `/api/mcp/send`, which
+   * applies it to the upstream transport *before* sending. Because
+   * `notifications/initialized` is that next send, it and everything after it
+   * (including the standalone SSE GET and the session DELETE, both issued by
+   * the upstream transport itself) carry the header (#1935).
+   */
+  setProtocolVersion(version) {
+    this._protocolVersion = version;
+  }
   /**
    * Reattach to an existing remote backend session after a full-page OAuth
    * redirect. Opens the SSE event stream without POST /connect.
@@ -4948,6 +5093,14 @@ var RemoteClientTransport = class {
       message,
       ...options?.relatedRequestId != null && {
         relatedRequestId: options.relatedRequestId
+      },
+      // Forward per-send `Mcp-Param-*` headers (SEP-2243) for the backend to
+      // apply to the upstream send; the browser can't set them cross-origin.
+      ...options?.headers != null && { headers: options.headers },
+      // Forward the negotiated protocol version so the backend's transport can
+      // stamp `Mcp-Protocol-Version` on this and every later request (#1935).
+      ...this._protocolVersion !== void 0 && {
+        protocolVersion: this._protocolVersion
       }
     };
     const res = await this.fetchFn(`${this.baseUrl}/api/mcp/send`, {
@@ -5029,6 +5182,13 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
   outputValidator = null;
   transport = null;
   baseTransport = null;
+  // Correlation for `markResponseRejected` (#1953): the method of each
+  // outbound request still awaiting a response, and — once one is answered —
+  // the id of the most recently answered request per method. Entries are
+  // dropped as responses arrive, so this holds at most one id per method
+  // rather than growing with the session.
+  outboundRequestMethods = /* @__PURE__ */ new Map();
+  lastAnsweredRequestByMethod = /* @__PURE__ */ new Map();
   /** True when the cached transport was built with an OAuth authProvider attached. */
   transportHasAuthProvider = false;
   /** Dedupes concurrent ambient auth challenges (reason + scopes). */
@@ -5139,7 +5299,10 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
   // `McpSubscription` whose filter's `resourceSubscriptions` mirrors
   // `subscribedResources`; mutating the set re-lists (close old, open new), and
   // an unexpected `"remote"` close re-lists (reconnect-by-re-listen — the stream
-  // is not resumable). `null` when no URI is subscribed or on the legacy era.
+  // is not resumable). `null` on the legacy era, and on the modern era whenever
+  // the filter is empty — which is *not* the same as "no URI subscribed": the
+  // stream also carries the list-change opt-ins, so a tools-only server opens it
+  // with no subscriptions at all (#1920).
   modernSubscription = null;
   // Monotonic guard so a stale re-list/reconnect (whose `listen()` or `closed`
   // resolves after a newer refresh already started) can detect it lost the race
@@ -5362,6 +5525,9 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
   createMessageTrackingCallbacks() {
     return {
       trackRequest: (message, origin) => {
+        if (origin === "client") {
+          this.outboundRequestMethods.set(message.id, message.method);
+        }
         const entry = {
           id: crypto.randomUUID(),
           timestamp: /* @__PURE__ */ new Date(),
@@ -5372,6 +5538,14 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
         this.dispatchTypedEvent("message", entry);
       },
       trackResponse: (message, origin) => {
+        const responseId = message.id;
+        if (origin === "server" && responseId !== void 0) {
+          const method = this.outboundRequestMethods.get(responseId);
+          this.outboundRequestMethods.delete(responseId);
+          if (method !== void 0) {
+            this.lastAnsweredRequestByMethod.set(method, responseId);
+          }
+        }
         const entry = {
           id: crypto.randomUUID(),
           timestamp: /* @__PURE__ */ new Date(),
@@ -5929,6 +6103,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     this.clearReceiverTasks();
     this.resetSubscriptionStream();
     this.cancelledTaskIds.clear();
+    this.outboundRequestMethods.clear();
+    this.lastAnsweredRequestByMethod.clear();
     for (const [, controller] of this.taskInputAbortControllers) {
       controller.abort(new Error("Connection ended"));
     }
@@ -6152,7 +6328,6 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       this.status = "connected";
       this.dispatchTypedEvent("statusChange", this.status);
       await this.fetchServerInfo();
-      this.dispatchTypedEvent("connect");
       if (this.initialLoggingLevel && this.capabilities?.logging) {
         await this.client.setLoggingLevel(
           this.initialLoggingLevel,
@@ -6231,6 +6406,10 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
           );
         }
       }
+      await this.openModernListenStreamOnConnect();
+      if (this.status === "connected" && !this.disconnecting) {
+        this.dispatchTypedEvent("connect");
+      }
     } catch (error) {
       if (!isConnectAuthRecoveryError(error)) {
         this.status = "error";
@@ -7042,7 +7221,11 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
         this.getCacheableRequestOptions(options?.cacheMode)
       )
     );
-    await this.refreshExcludedTools(options?.metadata).catch(() => {
+    await this.refreshExcludedTools(options?.metadata).catch((err) => {
+      this.logger.warn(
+        { err },
+        "Excluded-tools walk failed; the SEP-2243 excluded list may be incomplete"
+      );
     });
     return { tools: [...response.tools] };
   }
@@ -7055,6 +7238,26 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
   excludesInvalidXMcpHeaderTools() {
     return this.isModernEra() && this.getServerType() !== "stdio";
   }
+  /**
+   * Mark the response that most recently answered `method` as rejected by the
+   * client, so its Protocol entry shows why instead of rendering as a clean
+   * success (#1953).
+   *
+   * The SDK gives no request id with a decode failure — `SdkError` carries the
+   * method and nothing else — so the id is recovered by correlation: the last
+   * response received for that method. That is exact rather than approximate,
+   * because the SDK rejects synchronously while decoding the response (inside
+   * the transport's `onmessage`) and the caller's `catch` runs in the very next
+   * microtask. Delivering another response for the same method in that window
+   * would take a macrotask (a socket read), which cannot interleave there.
+   *
+   * A no-op when nothing has answered `method` this session.
+   */
+  markResponseRejected(method, reason) {
+    const id = this.lastAnsweredRequestByMethod.get(method);
+    if (id === void 0) return;
+    this.dispatchTypedEvent("responseRejected", { id, reason });
+  }
   /** The current SEP-2243 excluded-tools set (empty on legacy/stdio). */
   getExcludedTools() {
     return this.excludedTools;
@@ -7198,6 +7401,43 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       }
     }
   }
+  /**
+   * Coerce the string-valued entries of a tool's arguments to the types its
+   * `inputSchema` declares (the Tools form hands everything over as text).
+   * Shared by the two `tools/call` entry points — {@link attemptToolCall} and
+   * {@link callToolStream} — so both put the SAME arguments on the wire.
+   */
+  convertStringToolArgs(tool, args) {
+    const stringArgs = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (typeof value === "string") {
+        stringArgs[key] = value;
+      }
+    }
+    if (Object.keys(stringArgs).length === 0) return args;
+    return { ...args, ...convertToolParameters(tool, stringArgs) };
+  }
+  /**
+   * SEP-2243: mirror `x-mcp-header`-annotated arguments into `Mcp-Param-*`
+   * headers on a modern connection. The SDK only does this inside
+   * `client.callTool()` (and skips it in the browser), but we route
+   * `tools/call` through `client.request()` for manual MRTR driving (#1704), so
+   * we mirror ourselves. `Protocol.request` forwards `headers` (preserved
+   * across MRTR retry legs) to the transport, and the remote transport relays
+   * them to the backend's upstream send — issued server-side, where the browser
+   * skip doesn't apply. No-op on legacy/stdio (no annotations).
+   *
+   * Applied by BOTH `tools/call` entry points: a plain call
+   * ({@link attemptToolCall}) and a task-augmented one
+   * ({@link callToolStream}) — a strict modern server rejects either with
+   * `-32020` when the mirrored header is missing.
+   */
+  applyMirroredParamHeaders(tool, convertedArgs, requestOptions) {
+    if (this.protocolEra !== "modern") return;
+    const paramHeaders = mcpParamHeadersForTool(tool, convertedArgs);
+    if (Object.keys(paramHeaders).length === 0) return;
+    requestOptions.headers = { ...requestOptions.headers, ...paramHeaders };
+  }
   /**
    * Run a single tools/call attempt: convert args, issue the request, validate,
    * and return a successful {@link ToolCallInvocation}. Throws on any error
@@ -7217,17 +7457,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     if (!client) {
       throw new Error("Client is not connected");
     }
-    let convertedArgs = args;
-    const stringArgs = {};
-    for (const [key, value] of Object.entries(args)) {
-      if (typeof value === "string") {
-        stringArgs[key] = value;
-      }
-    }
-    if (Object.keys(stringArgs).length > 0) {
-      const convertedStringArgs = convertToolParameters(tool, stringArgs);
-      convertedArgs = { ...args, ...convertedStringArgs };
-    }
+    const convertedArgs = this.convertStringToolArgs(tool, args);
     const callMetadata = generalMetadata || toolSpecificMetadata ? { ...generalMetadata || {}, ...toolSpecificMetadata || {} } : void 0;
     const timestamp = /* @__PURE__ */ new Date();
     const metadata = this.mergeMeta(callMetadata);
@@ -7243,6 +7473,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       metadata?.progressToken,
       signal
     );
+    this.applyMirroredParamHeaders(tool, convertedArgs, requestOptions);
     const rawResult = await this.invokeMcpClient(
       () => this.requestWithInputRequired(
         "tools/call",
@@ -7646,17 +7877,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       throw new Error("Client is not connected");
     }
     try {
-      let convertedArgs = args;
-      const stringArgs = {};
-      for (const [key, value] of Object.entries(args)) {
-        if (typeof value === "string") {
-          stringArgs[key] = value;
-        }
-      }
-      if (Object.keys(stringArgs).length > 0) {
-        const convertedStringArgs = convertToolParameters(tool, stringArgs);
-        convertedArgs = { ...args, ...convertedStringArgs };
-      }
+      const convertedArgs = this.convertStringToolArgs(tool, args);
       const callMetadata = generalMetadata || toolSpecificMetadata ? { ...generalMetadata || {}, ...toolSpecificMetadata || {} } : void 0;
       const timestamp = /* @__PURE__ */ new Date();
       const metadata = this.mergeMeta(callMetadata);
@@ -7674,6 +7895,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       let taskId;
       let error;
       const requestOptions = this.getRequestOptions(metadata?.progressToken);
+      this.applyMirroredParamHeaders(tool, convertedArgs, requestOptions);
       if (this.progress) {
         const innerOnProgress = requestOptions.onprogress;
         requestOptions.onprogress = (progress) => {
@@ -7779,7 +8001,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
           );
         } catch (resultError) {
           throw new Error(
-            `Tool call did not return a result: ${resultError instanceof Error ? resultError.message : String(resultError)}`
+            `Tool call did not return a result: ${resultError instanceof Error ? resultError.message : String(resultError)}`,
+            { cause: resultError }
           );
         }
       }
@@ -7922,7 +8145,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       expandedUri = uriTemplate2.expand(params);
     } catch (error) {
       throw new Error(
-        `Failed to expand URI template "${uriTemplate}": ${error instanceof Error ? error.message : String(error)}`
+        `Failed to expand URI template "${uriTemplate}": ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
       );
     }
     const readInvocation = await this.readResource(expandedUri, metadata);
@@ -8120,7 +8344,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
         return { values: [] };
       }
       throw new Error(
-        `Failed to get completions: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to get completions: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
       );
     }
   }
@@ -8300,9 +8525,10 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
    * opted-in notification type (SEP §7.4).
    */
   buildSubscriptionFilter() {
-    const filter = {
-      resourceSubscriptions: Array.from(this.subscribedResources)
-    };
+    const filter = {};
+    if (this.subscribedResources.size > 0) {
+      filter.resourceSubscriptions = Array.from(this.subscribedResources);
+    }
     if (this.listChangedNotifications.tools && this.capabilities?.tools?.listChanged) {
       filter.toolsListChanged = true;
     }
@@ -8314,6 +8540,74 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     }
     return filter;
   }
+  /**
+   * Whether the modern listen stream should be open: the built filter carries
+   * something to listen for (#1920). Before #1920 this was "at least one URI is
+   * subscribed", which made the stream unreachable on a server with no resources
+   * — a tools-only server advertising `tools.listChanged` had no way to open it,
+   * so `notifications/tools/list_changed` could never arrive. The filter already
+   * modelled the list-change opt-ins; only the trigger was narrower than the
+   * filter it built. This matches the SDK's own `ClientOptions.listChanged`
+   * auto-open, which opens whenever the effective (config ∩ capability)
+   * intersection is non-empty.
+   *
+   * Note this is deliberately *not* the same predicate as the stream state's
+   * `active` — see `modernStreamActive()`.
+   */
+  wantsModernStream() {
+    const filter = this.buildSubscriptionFilter();
+    return (filter.resourceSubscriptions?.length ?? 0) > 0 || filter.toolsListChanged === true || filter.resourcesListChanged === true || filter.promptsListChanged === true;
+  }
+  /**
+   * Whether the stream state reports `active` — i.e. whether the *Subscriptions*
+   * UI has a stream to describe. That is a narrower question than
+   * `wantsModernStream()`: `ResourceSubscriptionStreamState` drives the
+   * Subscriptions section's badge, so a stream open purely for list-change
+   * notifications (no subscribed URI) has nothing to report there and stays
+   * `active: false` (#1920). Keeping the two apart also preserves the invariant
+   * the rest of this file is written against — an empty subscribed set is never
+   * announced alongside an `active` stream.
+   */
+  modernStreamActive() {
+    return this.subscribedResources.size > 0;
+  }
+  /**
+   * Open the modern listen stream at the end of a successful connect, when the
+   * filter is non-empty (#1920). Only the list-change opt-ins can make it
+   * non-empty here — the subscribed set is emptied by `resetSessionState()` on
+   * the way in — so this is exactly the "server advertises a listChanged the
+   * Inspector wants" case that had no trigger before.
+   *
+   * A failure is not allowed to fail the connect: the handshake succeeded and
+   * every request-scoped feature works without this stream. It is reported the
+   * way a lost stream is — hand it to the reconnect machinery, which retries
+   * with backoff and settles on `"ended"` past the cap.
+   *
+   * Gated on the same generation test as `subscribeToResource` — see the long
+   * comment there. The `connect` event has deliberately *not* been dispatched
+   * yet (that is the point of running here), so a list-state consumer is not the
+   * risk; what is, is anything else that bumps the generation while this
+   * `listen()` is in flight. `statusChange` has already fired, and any
+   * concurrent call on this instance qualifies: a `subscribeToResource` from a
+   * caller restoring subscriptions, or a `disconnect()` — whose
+   * `resetSubscriptionStream` bumps the generation too, making a reconcile here
+   * arm a reconnect for a session that is already gone.
+   */
+  async openModernListenStreamOnConnect() {
+    if (!this.isModernEra() || !this.wantsModernStream()) return;
+    const generationBefore = this.modernListenGeneration;
+    try {
+      await this.refreshModernSubscription();
+    } catch (error) {
+      this.logger.error(
+        { error },
+        "Failed to open the modern subscriptions/listen stream on connect"
+      );
+      if (this.modernListenGeneration === generationBefore + 1) {
+        this.reconcileModernStreamStateAfterFailedRefresh();
+      }
+    }
+  }
   /** Cancel a pending reconnect re-listen, if any (#1630). */
   clearModernReconnectTimer() {
     if (this.modernReconnectTimer !== void 0) {
@@ -8323,9 +8617,10 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
   }
   /**
    * (Re-)establish the modern `subscriptions/listen` stream to match the current
-   * `subscribedResources` set (#1630). Because the stream is not resumable,
-   * every filter change re-lists: the existing stream is closed and a fresh
-   * `listen()` opened. With no subscribed URIs the stream is left closed.
+   * filter (#1630). Because the stream is not resumable, every filter change
+   * re-lists: the existing stream is closed and a fresh `listen()` opened. With
+   * an empty filter — no subscribed URIs *and* no enabled list-change opt-in the
+   * server advertises — the stream is left closed (#1920).
    *
    * `modernListenGeneration` guards against races — if a newer refresh starts
    * while this one awaits its acknowledgement, the just-opened stream is
@@ -8343,7 +8638,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     if (previous) {
       await closeSubscriptionBestEffort(previous);
     }
-    if (this.subscribedResources.size === 0) {
+    if (!this.wantsModernStream()) {
       this.setModernStreamState(INACTIVE_SUBSCRIPTION_STREAM_STATE);
       return;
     }
@@ -8358,7 +8653,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     this.modernSubscription = subscription;
     this.modernReconnectAttempts = 0;
     this.setModernStreamState({
-      active: true,
+      active: this.modernStreamActive(),
       status: "acknowledged",
       honoredUris: subscription.honoredFilter.resourceSubscriptions ?? []
     });
@@ -8389,10 +8684,10 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       return;
     }
     this.modernSubscription = null;
-    const shouldReconnect = reason === "remote" && !isTerminalStatus(this.status) && this.subscribedResources.size > 0;
+    const shouldReconnect = reason === "remote" && !isTerminalStatus(this.status) && this.wantsModernStream();
     if (!shouldReconnect) {
       this.setModernStreamState({
-        active: this.subscribedResources.size > 0,
+        active: this.modernStreamActive(),
         status: "ended",
         honoredUris: []
       });
@@ -8406,10 +8701,11 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
    * refresh owns the state as well as the filter — so both call sites gate on
    * the generation first.
    *
-   * The empty case is the ordinary one: nothing subscribed, no stream, inactive.
-   * The non-empty one exists because a failed re-listen leaves
-   * `modernSubscription` null with URIs still subscribed, and nothing else will
-   * notice: the reconnect machinery is reachable only from a stream that closed
+   * The two branches are the empty and non-empty *filter* (#1920) — which is
+   * "nothing subscribed" only when no list-change opt-in is live. The empty case
+   * is the ordinary one: nothing to listen for, no stream, inactive. The
+   * non-empty one exists because a failed re-listen leaves `modernSubscription`
+   * null with the filter still wanting a stream, and nothing else will notice: the reconnect machinery is reachable only from a stream that closed
    * or a reconnect that failed, and neither happened here. Left alone, the state
    * keeps whatever the last success (or the optimistic `"connecting"`) wrote — a
    * badge that will never change over subscriptions the server may never have
@@ -8417,17 +8713,17 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
    * Subscribe early-returns on the URI already being in the set).
    *
    * So it reconnects rather than settling for an honest-but-dead `"ended"`:
-   * every other route to "stream gone, URIs live" either expects the close or
+   * every other route to "stream gone, filter live" either expects the close or
    * has exhausted the retry cap, and this is the one that has made no attempt
    * at all. `scheduleModernReconnect` fits as-is — a user-initiated refresh
    * already reset `modernReconnectAttempts`, so it starts at the base delay; the
-   * timer bails on a terminal status or an emptied set; and past the cap
+   * timer bails on a terminal status or an emptied filter; and past the cap
    * `onModernReconnectFailed` lands on the same `"ended"` badge. The state
    * therefore becomes true or ends after a real attempt. The caller still sees
    * its error either way — the retry is about the subscriptions, not the call.
    */
   reconcileModernStreamStateAfterFailedRefresh() {
-    if (this.subscribedResources.size === 0) {
+    if (!this.wantsModernStream()) {
       this.setModernStreamState(INACTIVE_SUBSCRIPTION_STREAM_STATE);
       return;
     }
@@ -8441,7 +8737,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
    */
   scheduleModernReconnect() {
     this.setModernStreamState({
-      active: true,
+      active: this.modernStreamActive(),
       status: "reconnecting",
       honoredUris: []
     });
@@ -8452,7 +8748,7 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
     this.clearModernReconnectTimer();
     this.modernReconnectTimer = setTimeout(() => {
       this.modernReconnectTimer = void 0;
-      if (isTerminalStatus(this.status) || this.subscribedResources.size === 0) {
+      if (isTerminalStatus(this.status) || !this.wantsModernStream()) {
         return;
       }
       this.refreshModernSubscription(true).catch(
@@ -8467,9 +8763,9 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
    */
   onModernReconnectFailed() {
     this.modernReconnectAttempts += 1;
-    if (this.modernReconnectAttempts > MODERN_RECONNECT_MAX_ATTEMPTS || isTerminalStatus(this.status) || this.subscribedResources.size === 0) {
+    if (this.modernReconnectAttempts > MODERN_RECONNECT_MAX_ATTEMPTS || isTerminalStatus(this.status) || !this.wantsModernStream()) {
       this.setModernStreamState({
-        active: this.subscribedResources.size > 0,
+        active: this.modernStreamActive(),
         status: "ended",
         honoredUris: []
       });
@@ -8522,7 +8818,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       this.dispatchSubscriptionsChange();
     } catch (error) {
       throw new Error(
-        `Failed to subscribe to resource: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to subscribe to resource: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
       );
     }
   }
@@ -8566,7 +8863,8 @@ var InspectorClient = class _InspectorClient extends InspectorClientEventTarget
       }
     } catch (error) {
       throw new Error(
-        `Failed to unsubscribe from resource: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to unsubscribe from resource: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
       );
     }
   }
@@ -9113,13 +9411,22 @@ async function consumeMethodOutcome(outcome, args) {
 }
 
 // ../../core/mcp/state/managedListState.ts
+import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
 var DEFAULT_LIST_CHANGED_DEBOUNCE_MS = 250;
+function isClientDecodeRejection(err) {
+  return SdkError.isInstance(err) && (err.code === SdkErrorCode.InvalidResult || err.code === SdkErrorCode.UnsupportedResultType);
+}
 var ManagedListState = class extends TypedEventTarget {
   items = [];
   client = null;
   unsubscribe = null;
   _metadata = void 0;
   listChanged = false;
+  // The last fetch's failure, kept as observable state so a load that fails
+  // (a transport error, or a result the SDK codec rejects as invalid) is
+  // rendered by the list panel instead of vanishing into an unhandled
+  // rejection — which read as "this server has no tools" (#1953).
+  error = null;
   config;
   // Debounce a burst of `list_changed` notifications into a single
   // refresh (or one indicator light) once it settles.
@@ -9138,7 +9445,8 @@ var ManagedListState = class extends TypedEventTarget {
       if (this.config.deferWhenPaginated && this.client?.getServerSettings()?.paginatedLists) {
         return;
       }
-      void this.refresh();
+      void this.refresh().catch(() => {
+      });
     };
     const onListChanged = () => {
       if (this.listChangedTimer !== null) clearTimeout(this.listChangedTimer);
@@ -9156,6 +9464,7 @@ var ManagedListState = class extends TypedEventTarget {
         this.items = [];
         this.dispatchChange();
         this.setListChanged(false);
+        this.setError(null);
       }
     };
     this.client.addEventListener("connect", onConnect);
@@ -9197,7 +9506,8 @@ var ManagedListState = class extends TypedEventTarget {
         const settings = this.client?.getServerSettings();
         const skipAggregate = this.config.deferWhenPaginated && settings?.paginatedLists;
         if (!skipAggregate && settings?.autoRefreshOnListChanged) {
-          await this.refresh(void 0, "refresh");
+          await this.refresh(void 0, "refresh").catch(() => {
+          });
         } else if (this.config.supportsIndicator) {
           this.setListChanged(true);
         }
@@ -9239,6 +9549,18 @@ var ManagedListState = class extends TypedEventTarget {
     this.listChanged = value;
     this.emit("listChangedChange", value);
   }
+  /** The last fetch's failure, or `null` when the last fetch succeeded. */
+  getError() {
+    return this.error;
+  }
+  // Compared by identity rather than message: two distinct failures with the
+  // same text are still two events, and a re-render on a repeat failure is
+  // cheap next to silently coalescing them.
+  setError(value) {
+    if (this.error === value) return;
+    this.error = value;
+    this.emit("errorChange", value);
+  }
   setMetadata(metadata) {
     this._metadata = metadata;
   }
@@ -9247,9 +9569,29 @@ var ManagedListState = class extends TypedEventTarget {
    * this fetch: `undefined` (the connect-time load) uses the default `'use'`;
    * a user-initiated or auto refresh passes `'refresh'` to force a
    * cache-bypassing round trip and re-store the fresh aggregate.
+   *
+   * A failure is recorded as observable state (`getError`) AND re-thrown: the
+   * state drives the panel's error rendering, while the rejection is what the
+   * caller's auth-recovery wrapper keys off to detect a 401 and start a
+   * re-authorization. Callers with nobody to await them (the connect-time load,
+   * the `list_changed` auto-refresh) catch it explicitly (#1953).
    */
   async refresh(metadata, cacheMode) {
-    const next = await this.fetchItems(metadata, cacheMode);
+    let next;
+    try {
+      next = await this.fetchItems(metadata, cacheMode);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.setError(error);
+      if (isClientDecodeRejection(err)) {
+        this.client?.markResponseRejected?.(
+          this.config.listMethod,
+          error.message
+        );
+      }
+      throw err;
+    }
+    this.setError(null);
     if (next === null) return this.getItems();
     this.applyItems(next);
     return this.getItems();
@@ -9288,6 +9630,7 @@ var ManagedListState = class extends TypedEventTarget {
 var ManagedToolsState = class extends ManagedListState {
   constructor(client, debounceMs = DEFAULT_LIST_CHANGED_DEBOUNCE_MS) {
     super(client, {
+      listMethod: "tools/list",
       changeEvent: "toolsChange",
       listChangedEvent: "toolsListChanged",
       capabilityKey: "tools",
@@ -9349,6 +9692,20 @@ var MessageLogState = class extends TypedEventTarget {
       }
       pushEntry(entry);
     };
+    const onResponseRejected = (event) => {
+      const { id, reason } = event.detail;
+      for (let i2 = this.messages.length - 1; i2 >= 0; i2--) {
+        const entry = this.messages[i2];
+        const entryId = entry.message.id;
+        if (entryId !== id) continue;
+        if (entry.direction === "notification") continue;
+        if (entry.direction === "request" && !entry.response) continue;
+        entry.clientError = reason;
+        this.dispatchTypedEvent("message", entry);
+        this.dispatchTypedEvent("messagesChange", this.getMessages());
+        return;
+      }
+    };
     const onStatusChange = () => {
       if (isTerminalStatus(this.client?.getStatus())) {
         this.messages = [];
@@ -9357,10 +9714,12 @@ var MessageLogState = class extends TypedEventTarget {
       }
     };
     this.client.addEventListener("message", onMessage);
+    this.client.addEventListener("responseRejected", onResponseRejected);
     this.client.addEventListener("statusChange", onStatusChange);
     this.unsubscribe = () => {
       if (this.client) {
         this.client.removeEventListener("message", onMessage);
+        this.client.removeEventListener("responseRejected", onResponseRejected);
         this.client.removeEventListener("statusChange", onStatusChange);
       }
       this.client = null;
@@ -9406,6 +9765,7 @@ var MessageLogState = class extends TypedEventTarget {
 var ManagedResourcesState = class extends ManagedListState {
   constructor(client, debounceMs = DEFAULT_LIST_CHANGED_DEBOUNCE_MS) {
     super(client, {
+      listMethod: "resources/list",
       changeEvent: "resourcesChange",
       listChangedEvent: "resourcesListChanged",
       capabilityKey: "resources",
@@ -9427,6 +9787,7 @@ var ManagedResourcesState = class extends ManagedListState {
 var ManagedResourceTemplatesState = class extends ManagedListState {
   constructor(client, debounceMs = DEFAULT_LIST_CHANGED_DEBOUNCE_MS) {
     super(client, {
+      listMethod: "resources/templates/list",
       changeEvent: "resourceTemplatesChange",
       listChangedEvent: "resourceTemplatesListChanged",
       // Templates are gated on the broader `resources` capability.
@@ -9454,6 +9815,7 @@ var ManagedResourceTemplatesState = class extends ManagedListState {
 var ManagedPromptsState = class extends ManagedListState {
   constructor(client, debounceMs = DEFAULT_LIST_CHANGED_DEBOUNCE_MS) {
     super(client, {
+      listMethod: "prompts/list",
       changeEvent: "promptsChange",
       listChangedEvent: "promptsListChanged",
       capabilityKey: "prompts",
@@ -11212,8 +11574,8 @@ var C = Q.object({ method: Q.literal("ui/resource-teardown"), params: Q.object({
 var S = Q.record(Q.string(), Q.unknown());
 var F = Q.object({ text: Q.object({}).optional().describe("Host supports text content blocks."), image: Q.object({}).optional().describe("Host supports image content blocks."), audio: Q.object({}).optional().describe("Host supports audio content blocks."), resource: Q.object({}).optional().describe("Host supports resource content blocks."), resourceLink: Q.object({}).optional().describe("Host supports resource link content blocks."), structuredContent: Q.object({}).optional().describe("Host supports structured content.") });
 var q = Q.object({ method: Q.literal("ui/notifications/request-teardown"), params: Q.object({}).optional() });
-var t = Q.object({ experimental: Q.object({}).optional().describe("Experimental features (structure TBD)."), openLinks: Q.object({}).optional().describe("Host supports opening external URLs."), downloadFile: Q.object({}).optional().describe("Host supports file downloads via ui/download-file."), serverTools: Q.object({ listChanged: Q.boolean().optional().describe("Host supports tools/list_changed notifications.") }).optional().describe("Host can proxy tool calls to the MCP server."), serverResources: Q.object({ listChanged: Q.boolean().optional().describe("Host supports resources/list_changed notifications.") }).optional().describe("Host can proxy resource reads to the MCP server."), logging: Q.object({}).optional().describe("Host accepts log messages."), sandbox: Q.object({ permissions: z4.optional().describe("Permissions granted by the host (camera, microphone, geolocation)."), csp: O.optional().describe("CSP domains approved by the host.") }).optional().describe("Sandbox configuration applied by the host."), updateModelContext: F.optional().describe("Host accepts context updates (ui/update-model-context) to be included in the model's context for future turns."), message: F.optional().describe("Host supports receiving content messages (ui/message) from the view."), sampling: Q.object({ tools: Q.object({}).optional().describe("Host supports tool use via `tools` and `toolChoice` parameters.") }).optional().describe("Host supports LLM sampling (sampling/createMessage) from the view.\nMirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through.") });
-var a = Q.object({ experimental: Q.object({}).optional().describe("Experimental features (structure TBD)."), tools: Q.object({ listChanged: Q.boolean().optional().describe("App supports tools/list_changed notifications.") }).optional().describe("App exposes MCP-style tools that the host can call."), availableDisplayModes: Q.array(B).optional().describe("Display modes the app supports.") });
+var t = Q.object({ experimental: Q.record(Q.string(), Q.record(Q.string(), Q.any()).describe("Experimental features keyed by identifier.")).optional().describe("Experimental features keyed by identifier."), openLinks: Q.object({}).optional().describe("Host supports opening external URLs."), downloadFile: Q.object({}).optional().describe("Host supports file downloads via ui/download-file."), serverTools: Q.object({ listChanged: Q.boolean().optional().describe("Host supports tools/list_changed notifications.") }).optional().describe("Host can proxy tool calls to the MCP server."), serverResources: Q.object({ listChanged: Q.boolean().optional().describe("Host supports resources/list_changed notifications.") }).optional().describe("Host can proxy resource reads to the MCP server."), logging: Q.object({}).optional().describe("Host accepts log messages."), sandbox: Q.object({ permissions: z4.optional().describe("Permissions granted by the host (camera, microphone, geolocation)."), csp: O.optional().describe("CSP domains approved by the host.") }).optional().describe("Sandbox configuration applied by the host."), updateModelContext: F.optional().describe("Host accepts context updates (ui/update-model-context) to be included in the model's context for future turns."), message: F.optional().describe("Host supports receiving content messages (ui/message) from the view."), sampling: Q.object({ tools: Q.object({}).optional().describe("Host supports tool use via `tools` and `toolChoice` parameters.") }).optional().describe("Host supports LLM sampling (sampling/createMessage) from the view.\nMirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through.") });
+var a = Q.object({ experimental: Q.record(Q.string(), Q.record(Q.string(), Q.any()).describe("Experimental features keyed by identifier.")).optional().describe("Experimental features keyed by identifier."), tools: Q.object({ listChanged: Q.boolean().optional().describe("App supports tools/list_changed notifications.") }).optional().describe("App exposes MCP-style tools that the host can call."), availableDisplayModes: Q.array(B).optional().describe("Display modes the app supports.") });
 var y = Q.object({ method: Q.literal("ui/notifications/initialized"), params: Q.object({}).optional() });
 var TQ = Q.object({ csp: O.optional().describe("Content Security Policy configuration for UI resources."), permissions: z4.optional().describe("Sandbox permissions requested by the UI resource."), domain: Q.string().optional().describe(`Dedicated origin for view sandbox.
 
@@ -11567,7 +11929,8 @@ async function runMethod(inspectorClient, args) {
         roots = parsed;
       } catch (e2) {
         throw new Error(
-          `--roots-json is invalid: ${e2 instanceof Error ? e2.message : String(e2)}`
+          `--roots-json is invalid: ${e2 instanceof Error ? e2.message : String(e2)}`,
+          { cause: e2 }
         );
       }
       await inspectorClient.setRoots(roots);
@@ -11846,7 +12209,7 @@ function parseRunnerOAuthCallbackUrl(cliCallbackUrl) {
     url = new URL(raw);
   } catch (err) {
     const reason = err?.message ?? String(err);
-    throw new Error(`Invalid OAuth callback URL: ${reason}`);
+    throw new Error(`Invalid OAuth callback URL: ${reason}`, { cause: err });
   }
   if (url.protocol !== "http:") {
     throw new Error("OAuth callback URL must use http scheme");
@@ -12810,7 +13173,7 @@ async function parseArgs(argv) {
   const scriptArgs = rawArgs.slice(2);
   const dashDashIndex = scriptArgs.indexOf("--");
   let targetArgs = [];
-  let optionArgs = [];
+  let optionArgs;
   if (dashDashIndex >= 0) {
     targetArgs = scriptArgs.slice(0, dashDashIndex);
     optionArgs = scriptArgs.slice(dashDashIndex + 1);
@@ -13120,7 +13483,8 @@ async function parseArgs(argv) {
       parsed = JSON.parse(options.toolArgsJson);
     } catch (e2) {
       throw new Error(
-        `--tool-args-json is not valid JSON: ${e2.message}`
+        `--tool-args-json is not valid JSON: ${e2 instanceof Error ? e2.message : String(e2)}`,
+        { cause: e2 }
       );
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {