@mcp-use/client 2.0.0-beta.8 → 2.0.0

package/dist/react/index.js

@@ -251,6 +251,67 @@ var init_rpc_logger = __esm({
   }
 });
 
+// src/react/types.ts
+var PERSISTED_SERVER_CONFIG_KEYS = [
+  "url",
+  "displayName",
+  "enabled",
+  "oauthProxyUrl",
+  "connectionMode",
+  "autoProxyFallback",
+  "callbackUrl",
+  "storageKeyPrefix",
+  "logLevel",
+  "autoRetry",
+  "autoReconnect",
+  "reconnectionOptions",
+  "popupFeatures",
+  "preventAutoAuth",
+  "useRedirectFlow",
+  "protocolNegotiation",
+  "timeout",
+  "clientInfo"
+];
+function pickPersistedServerConfig(source) {
+  const out = {};
+  for (const key of PERSISTED_SERVER_CONFIG_KEYS) {
+    const value = source[key];
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  if (source.proxyConfig?.proxyAddress !== void 0) {
+    out.proxyConfig = { proxyAddress: source.proxyConfig.proxyAddress };
+  }
+  if (source.oauth) {
+    const oauth = {};
+    if (source.oauth.clientId !== void 0) {
+      oauth.clientId = source.oauth.clientId;
+    }
+    if (source.oauth.clientMetadataUrl !== void 0) {
+      oauth.clientMetadataUrl = source.oauth.clientMetadataUrl;
+    }
+    if (source.oauth.scope !== void 0) {
+      oauth.scope = source.oauth.scope;
+    }
+    if (Object.keys(oauth).length > 0) {
+      out.oauth = oauth;
+    }
+  }
+  return out;
+}
+function pickLiveServerConfig(source) {
+  return {
+    ...pickPersistedServerConfig(source),
+    ...source.headers !== void 0 ? { headers: source.headers } : {},
+    ...source.proxyConfig !== void 0 ? { proxyConfig: source.proxyConfig } : {},
+    ...source.clientOptions !== void 0 ? { clientOptions: source.clientOptions } : {}
+  };
+}
+function toPersistedServerConfig(config) {
+  return pickPersistedServerConfig(config);
+}
+
 // src/react/useMcp.ts
 import { auth as auth2 } from "@modelcontextprotocol/client";
 
@@ -456,6 +517,11 @@ var BaseConnector = class {
   notificationHandlers = [];
   rootsCache = [];
   activeProgressHandlers = /* @__PURE__ */ new Set();
+  /**
+   * Creates a connector with shared SDK and callback options.
+   *
+   * @param opts - Connector initialization options.
+   */
   constructor(opts = {}) {
     this.opts = opts;
     if (opts.roots) {
@@ -638,7 +704,9 @@ var BaseConnector = class {
     }
   }
   /**
-   * Get the current roots.
+   * Returns the roots currently advertised to the server.
+   *
+   * @returns A copy of the configured roots.
    */
   getRoots() {
     return [...this.rootsCache];
@@ -707,7 +775,11 @@ var BaseConnector = class {
       "setupElicitationHandler: Elicitation handler registered successfully"
     );
   }
-  /** Disconnect and release resources. */
+  /**
+   * Disconnects the SDK client and releases transport resources.
+   *
+   * @returns A promise that resolves after cleanup completes.
+   */
   async disconnect() {
     if (!this.connected) {
       logger.debug("Not connected to MCP implementation");
@@ -718,7 +790,7 @@ var BaseConnector = class {
     this.connected = false;
     logger.debug("Disconnected from MCP implementation");
   }
-  /** Check if the client is connected */
+  /** Whether an SDK client currently exists for this connector. */
   get isClientConnected() {
     return this.client != null;
   }
@@ -728,6 +800,10 @@ var BaseConnector = class {
    * In the SDK, `Client.connect(transport)` automatically performs the
    * protocol‑level `initialize` handshake, so we only need to cache the list of
    * tools and expose some server info.
+   *
+   * @param defaultRequestOptions - Options used while fetching the initial tool list.
+   * @returns The capabilities advertised by the server.
+   * @throws When {@link BaseConnector.connect} has not completed.
    */
   async initialize(defaultRequestOptions = this.opts.defaultRequestOptions ?? {}) {
     if (!this.client) {
@@ -765,18 +841,22 @@ var BaseConnector = class {
     logger.debug("Server info:", serverInfo);
     return capabilities;
   }
-  /** Lazily expose the cached tools list. */
+  /**
+   * Returns the tool list cached during initialization.
+   *
+   * @throws When {@link BaseConnector.initialize} has not completed.
+   */
   get tools() {
     if (!this.toolsCache) {
       throw new Error("MCP client is not initialized; call initialize() first");
     }
     return this.toolsCache;
   }
-  /** Expose cached server capabilities. */
+  /** Capabilities cached during initialization, or an empty object. */
   get serverCapabilities() {
     return this.capabilitiesCache || {};
   }
-  /** Expose cached server info. */
+  /** Server identity cached during initialization, or `null`. */
   get serverInfo() {
     return this.serverInfoCache;
   }
@@ -797,7 +877,15 @@ var BaseConnector = class {
   get negotiatedProtocolVersion() {
     return this.client?.getNegotiatedProtocolVersion?.();
   }
-  /** Call a tool on the server. */
+  /**
+   * Calls a tool on the connected server.
+   *
+   * @param name - Tool name.
+   * @param args - Tool arguments.
+   * @param options - Per-request timeout, cancellation, and progress options.
+   * @returns The tool result returned by the server.
+   * @throws When the connector is not connected or the tool call fails.
+   */
   async callTool(name, args, options) {
     if (!this.client) {
       throw new Error("MCP client is not connected");
@@ -922,7 +1010,13 @@ var BaseConnector = class {
     );
     return result;
   }
-  /** Read a resource by URI. */
+  /**
+   * Reads a resource by URI.
+   *
+   * @param uri - Resource URI to read.
+   * @param options - Per-request options.
+   * @returns The resource contents returned by the server.
+   */
   async readResource(uri, options) {
     if (!this.client) {
       throw new Error("MCP client is not connected");
@@ -957,6 +1051,11 @@ var BaseConnector = class {
     logger.debug(`Unsubscribing from resource: ${uri}`);
     return await this.client.unsubscribeResource({ uri }, options);
   }
+  /**
+   * Lists prompts exposed by the server.
+   *
+   * @returns The prompt list, or an empty list when prompts are unsupported.
+   */
   async listPrompts() {
     if (!this.client) {
       throw new Error("MCP client is not connected");
@@ -977,6 +1076,13 @@ var BaseConnector = class {
       throw err;
     }
   }
+  /**
+   * Gets a prompt with the supplied arguments.
+   *
+   * @param name - Prompt name.
+   * @param args - Prompt arguments.
+   * @returns The rendered prompt returned by the server.
+   */
   async getPrompt(name, args) {
     if (!this.client) {
       throw new Error("MCP client is not connected");
@@ -984,7 +1090,14 @@ var BaseConnector = class {
     logger.debug(`Getting prompt ${name}`);
     return await this.client.getPrompt({ name, arguments: args });
   }
-  /** Send a raw request through the client. */
+  /**
+   * Sends a raw, potentially non-standard request through the SDK client.
+   *
+   * @param method - JSON-RPC method name.
+   * @param params - Request parameters. Defaults to an empty object.
+   * @param options - Per-request options.
+   * @returns The unvalidated result returned by the server.
+   */
   async request(method, params = null, options) {
     if (!this.client) {
       throw new Error("MCP client is not connected");
@@ -1083,6 +1196,12 @@ var HttpConnector = class extends BaseConnector {
   reconnectionOptions;
   transportType = null;
   streamableTransport = null;
+  /**
+   * Creates an HTTP connector.
+   *
+   * @param baseUrl - MCP endpoint URL.
+   * @param opts - Authentication, transport, SDK, and reconnection options.
+   */
   constructor(baseUrl, opts = {}) {
     super(opts);
     const originalUrl = baseUrl.replace(/\/$/, "");
@@ -1200,7 +1319,12 @@ var HttpConnector = class extends BaseConnector {
     }
     return { fallbackReason, is401Error, httpStatusCode };
   }
-  /** Establish connection to the MCP implementation via streamable HTTP. */
+  /**
+   * Establishes a streamable HTTP connection to the MCP server.
+   *
+   * @returns A promise that resolves after protocol negotiation completes.
+   * @throws An error with `code: 401` when authentication is required.
+   */
   async connect() {
     if (this.connected) {
       logger.debug("Already connected to MCP implementation");
@@ -1428,6 +1552,11 @@ var HttpConnector = class extends BaseConnector {
       throw err;
     }
   }
+  /**
+   * Returns fields that identify the endpoint and negotiated transport.
+   *
+   * @returns HTTP connector identity metadata.
+   */
   get publicIdentifier() {
     return {
       type: "http",
@@ -1436,7 +1565,11 @@ var HttpConnector = class extends BaseConnector {
       protocolEra: this.protocolEra ?? "unknown"
     };
   }
-  /** Get the active transport type (`streamable-http` once connected). */
+  /**
+   * Returns the active transport type.
+   *
+   * @returns `"streamable-http"` after connection, otherwise `null`.
+   */
   getTransportType() {
     return this.transportType;
   }
@@ -1473,7 +1606,7 @@ var HttpConnector = class extends BaseConnector {
 };
 
 // src/utils/version.ts
-var VERSION = "2.0.0-beta.7";
+var VERSION = "2.0.0";
 function getPackageVersion() {
   return VERSION;
 }
@@ -1544,6 +1677,186 @@ function resolveClientOptions(clientOptions) {
   };
 }
 
+// src/auth/storage.ts
+var AUTH_CRYPTO_DATABASE = "mcp-use-oauth-crypto";
+var AUTH_CRYPTO_STORE = "keys";
+var AUTH_CRYPTO_KEY = "aes-gcm-v1";
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+var LocalStorageKVStore = class {
+  fallback = /* @__PURE__ */ new Map();
+  keyPromise;
+  durable = true;
+  async get(key) {
+    if (!this.durable) return this.fallback.get(key) ?? null;
+    let stored;
+    try {
+      stored = localStorage.getItem(key);
+    } catch {
+      this.durable = false;
+      return this.fallback.get(key) ?? null;
+    }
+    if (stored === null) return null;
+    const envelope = parseEncryptedEnvelope(stored);
+    if (!envelope) {
+      await this.set(key, stored);
+      return stored;
+    }
+    try {
+      const cryptoKey = await this.getCryptoKey();
+      const plaintext = await globalThis.crypto.subtle.decrypt(
+        {
+          name: "AES-GCM",
+          iv: decodeBase64(envelope.iv),
+          additionalData: textEncoder.encode(key)
+        },
+        cryptoKey,
+        decodeBase64(envelope.ciphertext)
+      );
+      return textDecoder.decode(plaintext);
+    } catch {
+      await this.remove(key);
+      return null;
+    }
+  }
+  async set(key, value) {
+    if (!this.durable) {
+      this.fallback.set(key, value);
+      return;
+    }
+    try {
+      const cryptoKey = await this.getCryptoKey();
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+      const ciphertext = await globalThis.crypto.subtle.encrypt(
+        {
+          name: "AES-GCM",
+          iv,
+          additionalData: textEncoder.encode(key)
+        },
+        cryptoKey,
+        textEncoder.encode(value)
+      );
+      const envelope = {
+        v: 1,
+        alg: "A256GCM",
+        iv: encodeBase64(iv),
+        ciphertext: encodeBase64(new Uint8Array(ciphertext))
+      };
+      localStorage.setItem(key, JSON.stringify(envelope));
+      this.fallback.delete(key);
+    } catch {
+      this.durable = false;
+      try {
+        localStorage.removeItem(key);
+      } catch {
+      }
+      this.fallback.set(key, value);
+    }
+  }
+  remove(key) {
+    this.fallback.delete(key);
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      this.durable = false;
+    }
+  }
+  keys() {
+    const out = new Set(this.fallback.keys());
+    if (this.durable) {
+      try {
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key) out.add(key);
+        }
+      } catch {
+        this.durable = false;
+      }
+    }
+    return [...out];
+  }
+  getCryptoKey() {
+    this.keyPromise ??= getOrCreateCryptoKey();
+    return this.keyPromise;
+  }
+};
+function parseEncryptedEnvelope(value) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || !("v" in parsed) || parsed.v !== 1 || !("alg" in parsed) || parsed.alg !== "A256GCM" || !("iv" in parsed) || typeof parsed.iv !== "string" || !("ciphertext" in parsed) || typeof parsed.ciphertext !== "string") {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function getOrCreateCryptoKey() {
+  if (!globalThis.crypto?.subtle || typeof indexedDB === "undefined") {
+    throw new Error("Durable browser cryptography is unavailable");
+  }
+  const candidate = await globalThis.crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+  const database = await openCryptoDatabase();
+  try {
+    return await new Promise((resolve, reject) => {
+      const transaction = database.transaction(AUTH_CRYPTO_STORE, "readwrite");
+      const store = transaction.objectStore(AUTH_CRYPTO_STORE);
+      const request = store.get(AUTH_CRYPTO_KEY);
+      let selected;
+      request.onsuccess = () => {
+        selected = request.result;
+        if (!selected) {
+          selected = candidate;
+          store.put(candidate, AUTH_CRYPTO_KEY);
+        }
+      };
+      request.onerror = () => reject(request.error);
+      transaction.oncomplete = () => {
+        if (selected) resolve(selected);
+        else reject(new Error("OAuth encryption key was not initialized"));
+      };
+      transaction.onerror = () => reject(transaction.error);
+      transaction.onabort = () => reject(transaction.error);
+    });
+  } finally {
+    database.close();
+  }
+}
+function openCryptoDatabase() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(AUTH_CRYPTO_DATABASE, 1);
+    request.onupgradeneeded = () => {
+      const database = request.result;
+      if (!database.objectStoreNames.contains(AUTH_CRYPTO_STORE)) {
+        database.createObjectStore(AUTH_CRYPTO_STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => reject(new Error("OAuth encryption database is blocked"));
+  });
+}
+function encodeBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function decodeBase64(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+// src/auth/session-store.ts
+import { validateClientMetadataUrl } from "@modelcontextprotocol/client";
+
 // src/auth/url.ts
 function sanitizeUrl(raw) {
   const abort = () => {
@@ -1568,29 +1881,7 @@ function sanitizeParam([k, v]) {
   return `${encodeURIComponent(k)}${v.length > 0 ? `=${encodeURIComponent(v)}` : ""}`;
 }
 
-// src/auth/storage.ts
-var LocalStorageKVStore = class {
-  get(key) {
-    return localStorage.getItem(key);
-  }
-  set(key, value) {
-    localStorage.setItem(key, value);
-  }
-  remove(key) {
-    localStorage.removeItem(key);
-  }
-  keys() {
-    const out = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const k = localStorage.key(i);
-      if (k) out.push(k);
-    }
-    return out;
-  }
-};
-
 // src/auth/session-store.ts
-import { validateClientMetadataUrl } from "@modelcontextprotocol/client";
 var OAuthSessionStore = class _OAuthSessionStore {
   serverUrl;
   storageKeyPrefix;
@@ -1696,29 +1987,39 @@ var OAuthSessionStore = class _OAuthSessionStore {
     if (ctx) await this.store.set(this.credentialKey("tokens"), serialized);
     await this.store.remove(this.getKey("code_verifier"));
     await this.store.remove(this.getKey("last_auth_url"));
+    await this.store.remove(this.getKey("last_auth_callback_url"));
   }
   async clientInformation(ctx) {
+    if (!this.allowClientSecret) {
+      const registeredRedirectUri = await this.store.get(
+        this.getKey("client_info_redirect_uri")
+      );
+      if (registeredRedirectUri !== this.redirectUrl) {
+        await this.invalidateCredentials("registration");
+        console.info(
+          `[${this.storageKeyPrefix}] Re-registering browser OAuth client after its Inspector callback changed or could not be verified.`
+        );
+        return void 0;
+      }
+    }
     const stored = await this.readCredential("client_info", ctx);
     if (!stored) return void 0;
     const { key, value: clientInfo } = stored;
     try {
       if (!this.allowClientSecret && clientInfo.client_secret) {
-        await this.store.remove(key);
-        if (ctx) await this.store.remove(this.credentialKey("client_info"));
+        await this.invalidateCredentials("registration");
         console.warn(
-          `[${this.storageKeyPrefix}] Removed OAuth client information containing a browser client_secret.`
+          `[${this.storageKeyPrefix}] Recovered stale browser OAuth credentials containing a client_secret.`
         );
         return void 0;
       }
       const storedRedirectUris = Array.isArray(clientInfo.redirect_uris) ? clientInfo.redirect_uris : [];
-      const hasMatchingRedirect = storedRedirectUris.length === 0 || storedRedirectUris.includes(this.redirectUrl);
+      const hasMatchingRedirect = storedRedirectUris.length === 0 && this.allowClientSecret || storedRedirectUris.includes(this.redirectUrl);
       if (!hasMatchingRedirect) {
         console.info(
-          `[${this.storageKeyPrefix}] Invalidating cached OAuth client info due to redirect URI mismatch.`
+          `[${this.storageKeyPrefix}] Recovering cached OAuth credentials after a redirect URI change.`
         );
-        await this.store.remove(key);
-        await this.store.remove(this.credentialKey("tokens", ctx));
-        await this.store.remove(this.getKey("last_auth_url"));
+        await this.invalidateCredentials("registration");
         return void 0;
       }
       return clientInfo;
@@ -1736,11 +2037,20 @@ var OAuthSessionStore = class _OAuthSessionStore {
         "Browser OAuth clients must be public clients; client_secret persistence is not allowed."
       );
     }
-    const serialized = JSON.stringify(clientInformation);
+    const persistedClientInformation = !this.allowClientSecret && (!("redirect_uris" in clientInformation) || !Array.isArray(
+      clientInformation.redirect_uris
+    ) || clientInformation.redirect_uris.length === 0) ? { ...clientInformation, redirect_uris: [this.redirectUrl] } : clientInformation;
+    const serialized = JSON.stringify(persistedClientInformation);
     await this.store.set(this.credentialKey("client_info", ctx), serialized);
     if (ctx) {
       await this.store.set(this.credentialKey("client_info"), serialized);
     }
+    if (!this.allowClientSecret) {
+      await this.store.set(
+        this.getKey("client_info_redirect_uri"),
+        this.redirectUrl
+      );
+    }
   }
   async saveCodeVerifier(codeVerifier) {
     await this.store.set(this.getKey("code_verifier"), codeVerifier);
@@ -1765,11 +2075,22 @@ var OAuthSessionStore = class _OAuthSessionStore {
       }
     };
     switch (scope) {
+      case "registration":
+        await removeCredentialKeys("tokens");
+        await removeCredentialKeys("client_info");
+        await this.store.remove(this.getKey("code_verifier"));
+        await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
+        await this.store.remove(this.getKey("token_endpoint"));
+        break;
       case "all":
         await removeCredentialKeys("tokens");
         await removeCredentialKeys("client_info");
         await this.store.remove(this.getKey("code_verifier"));
         await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
         await this.store.remove(this.getKey("discovery_state"));
         await this.store.remove(this.getKey("token_endpoint"));
         break;
@@ -1819,7 +2140,7 @@ var OAuthSessionStore = class _OAuthSessionStore {
    */
   async storeAuthorizationState(authorizationUrl, opts = {}) {
     const state = globalThis.crypto.randomUUID();
-    const stateKey = `${this.storageKeyPrefix}:state_${state}`;
+    const stateKey = `${this.storageKeyPrefix}_${this.serverUrlHash}_state_${state}`;
     const stateData = {
       serverUrlHash: this.serverUrlHash,
       expiry: Date.now() + 1e3 * 60 * 10,
@@ -1839,6 +2160,10 @@ var OAuthSessionStore = class _OAuthSessionStore {
     authorizationUrl.searchParams.set("state", state);
     const sanitizedAuthUrl = sanitizeUrl(authorizationUrl.toString());
     await this.store.set(stateKey, JSON.stringify(stateData));
+    await this.store.set(
+      this.getKey("last_auth_callback_url"),
+      this.redirectUrl
+    );
     await this.store.set(this.getKey("last_auth_url"), sanitizedAuthUrl);
     return sanitizedAuthUrl;
   }
@@ -1868,16 +2193,30 @@ async function serializeBody(body) {
   if (body instanceof Blob) return await body.text();
   return body;
 }
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  return value.slice(0, end);
+}
 var BrowserOAuthClientProvider = class {
+  /** Protected MCP server URL associated with this provider. */
   serverUrl;
+  /** Pre-registered public client information, when configured. */
   staticClientInfo;
   session;
+  storage;
   // Browser-only state
+  /** Whether initial connection waits for explicit authentication. */
   preventAutoAuth;
   useRedirectFlow;
   oauthProxyUrl;
   connectionUrl;
   proxyOAuthRequests;
+  lastAttemptedAuthUrl = null;
+  authorizationPending = false;
+  /** Callback invoked immediately before an authorization popup opens. */
   onPopupWindow;
   constructor(serverUrl, options = {}) {
     if (options.staticClientInfo?.client_secret) {
@@ -1886,10 +2225,11 @@ var BrowserOAuthClientProvider = class {
       );
     }
     this.serverUrl = serverUrl;
+    this.storage = new LocalStorageKVStore();
     this.session = new OAuthSessionStore(
       serverUrl,
       { ...options, allowClientSecret: false },
-      new LocalStorageKVStore()
+      this.storage
     );
     this.preventAutoAuth = options.preventAutoAuth;
     this.useRedirectFlow = options.useRedirectFlow;
@@ -1900,33 +2240,54 @@ var BrowserOAuthClientProvider = class {
     this.onPopupWindow = options.onPopupWindow;
   }
   // --- Identity / key fields exposed for callback handling ---
+  /** Prefix used for persisted OAuth keys. */
   get storageKeyPrefix() {
     return this.session.storageKeyPrefix;
   }
+  /** Stable hash used to namespace storage for this server. */
   get serverUrlHash() {
     return this.session.serverUrlHash;
   }
+  /** Human-readable OAuth client name. */
   get clientName() {
     return this.session.clientName;
   }
+  /** Public website describing the OAuth client. */
   get clientUri() {
     return this.session.clientUri;
   }
+  /** Public OAuth client logo URL. */
   get logoUri() {
     return this.session.logoUri;
   }
+  /** OAuth redirect URI. */
   get callbackUrl() {
     return this.session.callbackUrl;
   }
+  /** Space-delimited OAuth scopes requested by the client. */
   get scope() {
     return this.session.scope;
   }
   get clientMetadataUrl() {
     return this.session.clientMetadataUrl;
   }
+  /**
+   * Returns a provider-scoped storage key.
+   *
+   * @param keySuffix - Suffix identifying the stored value.
+   * @returns Namespaced storage key.
+   */
   getKey(keySuffix) {
     return this.session.getKey(keySuffix);
   }
+  /** Whether an authorization flow is awaiting completion. */
+  get hasPendingFlow() {
+    return this.authorizationPending;
+  }
+  /** Marks the current authorization flow as complete. */
+  markFlowComplete() {
+    this.authorizationPending = false;
+  }
   /**
    * Re-anchor an SDK-derived OAuth discovery URL from the MCP connection
    * (proxy) origin onto the actual MCP server.
@@ -1954,8 +2315,8 @@ var BrowserOAuthClientProvider = class {
       const [doc, ...suffixParts] = rest.split("/");
       if (!doc) return url;
       const suffix = suffixParts.length ? `/${suffixParts.join("/")}` : "";
-      const connectionPath = connection.pathname.replace(/\/+$/, "");
-      const targetPath = target.pathname.replace(/\/+$/, "");
+      const connectionPath = trimTrailingSlashes(connection.pathname);
+      const targetPath = trimTrailingSlashes(target.pathname);
       const newSuffix = suffix && suffix === connectionPath ? targetPath : suffix;
       return `${target.origin}/.well-known/${doc}${newSuffix}${requested.search}`;
     } catch {
@@ -1974,20 +2335,19 @@ var BrowserOAuthClientProvider = class {
    * therefore never alters fetch behavior for other servers, other
    * connections, or the rest of the page.
    *
-   * When this provider is not configured to proxy OAuth requests (no
-   * `oauthProxyUrl`, or `proxyOAuthRequests` disabled), the provided
-   * `baseFetch` is returned as-is (or `undefined` when none is given, letting
-   * the SDK fall back to its default `fetch`).
+   * OAuth metadata is always fetched with `cache: "no-store"`, including in
+   * direct mode. Authorization servers commonly vary CORS headers by Origin;
+   * bypassing the browser HTTP cache prevents a revalidated response cached
+   * for another localhost origin from poisoning discovery. When OAuth proxying
+   * is disabled or no `oauthProxyUrl` is configured, all requests still go
+   * directly to their original URLs.
    *
    * @param baseFetch - The fetch used for non-OAuth requests and for the
    *   underlying proxy calls. Defaults to the global `fetch`.
    */
   getProxyFetch(baseFetch) {
-    if (!this.proxyOAuthRequests || !this.oauthProxyUrl) {
-      return baseFetch;
-    }
     const base = baseFetch ?? globalThis.fetch.bind(globalThis);
-    const oauthProxyUrl = this.oauthProxyUrl;
+    const oauthProxyUrl = this.proxyOAuthRequests && this.oauthProxyUrl ? this.oauthProxyUrl : void 0;
     const discoveredEndpoints = /* @__PURE__ */ new Set();
     let restoredDiscovery = false;
     return async (input, init) => {
@@ -2000,6 +2360,12 @@ var BrowserOAuthClientProvider = class {
         return await base(input, init);
       }
       const isMetadata = pathname.includes("/.well-known/");
+      if (!oauthProxyUrl) {
+        return await base(
+          isMetadata ? url : input,
+          isMetadata ? { ...init, cache: "no-store" } : init
+        );
+      }
       if (!restoredDiscovery) {
         restoredDiscovery = true;
         const metadata = (await this.discoveryState())?.authorizationServerMetadata;
@@ -2034,7 +2400,8 @@ var BrowserOAuthClientProvider = class {
       if (isMetadata) {
         const response2 = await base(proxyEndpoint, {
           ...init,
-          method: "GET"
+          method: "GET",
+          cache: "no-store"
         });
         try {
           const metadata = await response2.clone().json();
@@ -2052,23 +2419,40 @@ var BrowserOAuthClientProvider = class {
         }
         return response2;
       }
-      const body = init?.body ? await serializeBody(init.body) : void 0;
+      const inputRequest = input instanceof Request ? input : void 0;
+      const method = init?.method ?? inputRequest?.method ?? "POST";
+      const requestHeaders = init?.headers ?? inputRequest?.headers;
+      let body;
+      if (init?.body !== void 0 && init.body !== null) {
+        body = await serializeBody(init.body);
+      } else if (inputRequest?.body && method !== "GET" && method !== "HEAD") {
+        body = await inputRequest.clone().text();
+      }
       const response = await base(proxyEndpoint, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           serverUrl: this.serverUrl,
           url,
-          method: init?.method || "POST",
-          headers: init?.headers ? Object.fromEntries(new Headers(init.headers)) : {},
+          method,
+          headers: requestHeaders ? Object.fromEntries(new Headers(requestHeaders)) : {},
           body
         })
       });
       const data = await response.json();
+      if (!response.ok || typeof data.status !== "number") {
+        return new Response(JSON.stringify(data), {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers
+        });
+      }
       return new Response(JSON.stringify(data.body), {
         status: data.status,
-        statusText: data.statusText,
-        headers: new Headers(data.headers)
+        statusText: typeof data.statusText === "string" ? data.statusText : void 0,
+        headers: new Headers(
+          data.headers && typeof data.headers === "object" ? data.headers : void 0
+        )
       });
     };
   }
@@ -2083,15 +2467,41 @@ var BrowserOAuthClientProvider = class {
     return this.session.tokens(ctx);
   }
   saveTokens(tokens, ctx) {
+    this.lastAttemptedAuthUrl = null;
+    this.authorizationPending = false;
     return this.session.saveTokens(tokens, ctx);
   }
+  /**
+   * Returns the configured or dynamically registered OAuth client information.
+   *
+   * @param ctx - Optional registration context.
+   * @returns OAuth client information, or `undefined` when not registered.
+   */
   async clientInformation(ctx) {
     if (this.staticClientInfo) return this.staticClientInfo;
     return this.session.clientInformation(ctx);
   }
+  /**
+   * Persists public OAuth client registration information.
+   *
+   * Static client configuration takes precedence, and browser providers discard
+   * any client secret returned for a public client.
+   *
+   * @param clientInformation - Registration information to save.
+   * @param ctx - Optional registration context.
+   */
   async saveClientInformation(clientInformation, ctx) {
     if (this.staticClientInfo) return;
-    return this.session.saveClientInformation(clientInformation, ctx);
+    const { client_secret: discardedClientSecret, ...publicClientInformation } = clientInformation;
+    if (discardedClientSecret) {
+      console.info(
+        `[${this.storageKeyPrefix}] Discarded client_secret returned for a public browser OAuth client.`
+      );
+    }
+    return this.session.saveClientInformation(
+      publicClientInformation,
+      ctx
+    );
   }
   codeVerifier() {
     return this.session.codeVerifier();
@@ -2140,20 +2550,26 @@ var BrowserOAuthClientProvider = class {
    * use `redirectToAuthorization` for that.
    */
   async prepareAuthorizationUrl(authorizationUrl) {
-    return this.session.storeAuthorizationState(authorizationUrl, {
-      extraProviderOptions: {
-        oauthProxyUrl: this.oauthProxyUrl,
-        ...this.clientMetadataUrl ? { clientMetadataUrl: this.clientMetadataUrl } : {},
-        ...this.staticClientInfo ? { staticClientInfo: this.staticClientInfo } : {},
-        ...this.scope ? { scope: this.scope } : {}
-      },
-      flowType: this.useRedirectFlow ? "redirect" : "popup",
-      returnUrl: typeof window !== "undefined" ? window.location.href : void 0
-    });
+    const prepared = await this.session.storeAuthorizationState(
+      authorizationUrl,
+      {
+        extraProviderOptions: {
+          oauthProxyUrl: this.oauthProxyUrl,
+          ...this.clientMetadataUrl ? { clientMetadataUrl: this.clientMetadataUrl } : {},
+          ...this.staticClientInfo ? { staticClientInfo: this.staticClientInfo } : {},
+          ...this.scope ? { scope: this.scope } : {}
+        },
+        flowType: this.useRedirectFlow ? "redirect" : "popup",
+        returnUrl: typeof window !== "undefined" ? window.location.href : void 0
+      }
+    );
+    this.lastAttemptedAuthUrl = prepared;
+    this.authorizationPending = true;
+    return prepared;
   }
   /**
    * Redirects the user agent to the authorization URL, storing necessary state.
-   * @param authorizationUrl The fully constructed authorization URL from the SDK.
+   * @param authorizationUrl - The fully constructed authorization URL from the SDK.
    */
   async redirectToAuthorization(authorizationUrl) {
     const sanitizedAuthUrl = await this.prepareAuthorizationUrl(authorizationUrl);
@@ -2201,40 +2617,27 @@ var BrowserOAuthClientProvider = class {
    * Retrieves the last URL passed to `redirectToAuthorization`. Useful for manual fallback.
    */
   getLastAttemptedAuthUrl() {
-    const storedUrl = localStorage.getItem(this.getKey("last_auth_url"));
-    if (!storedUrl) return null;
-    return sanitizeUrl(storedUrl);
+    return this.lastAttemptedAuthUrl;
   }
+  /**
+   * Removes OAuth state stored for this server.
+   *
+   * @returns The number of storage entries removed.
+   */
   clearStorage() {
+    this.lastAttemptedAuthUrl = null;
+    this.authorizationPending = false;
     const prefixPattern = `${this.storageKeyPrefix}_${this.serverUrlHash}_`;
-    const statePattern = `${this.storageKeyPrefix}:state_`;
     const keysToRemove = [];
     let count = 0;
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i);
-      if (!key) continue;
+    for (const key of this.storage.keys()) {
       if (key.startsWith(prefixPattern)) {
         keysToRemove.push(key);
-      } else if (key.startsWith(statePattern)) {
-        try {
-          const item = localStorage.getItem(key);
-          if (item) {
-            const state = JSON.parse(item);
-            if (state.serverUrlHash === this.serverUrlHash) {
-              keysToRemove.push(key);
-            }
-          }
-        } catch (e) {
-          console.warn(
-            `[${this.storageKeyPrefix}] Error parsing state key ${key} during clearStorage:`,
-            e
-          );
-        }
       }
     }
     const uniqueKeysToRemove = [...new Set(keysToRemove)];
     uniqueKeysToRemove.forEach((key) => {
-      localStorage.removeItem(key);
+      this.storage.remove(key);
       count++;
     });
     return count;
@@ -2265,16 +2668,13 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
     return {
       // Core execution info
       execution_method: this.data.executionMethod,
-      query: this.data.query,
       query_length: this.data.query.length,
       success: this.data.success,
       // Agent configuration
       model_provider: this.data.modelProvider,
       model_name: this.data.modelName,
       server_count: this.data.serverCount,
-      server_identifiers: this.data.serverIdentifiers,
       total_tools_available: this.data.totalToolsAvailable,
-      tools_available_names: this.data.toolsAvailableNames,
       max_steps_configured: this.data.maxStepsConfigured,
       memory_enabled: this.data.memoryEnabled,
       use_server_manager: this.data.useServerManager,
@@ -2285,8 +2685,6 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
       // Execution results (always include, even if null)
       steps_taken: this.data.stepsTaken ?? null,
       tools_used_count: this.data.toolsUsedCount ?? null,
-      tools_used_names: this.data.toolsUsedNames ?? null,
-      response: this.data.response ?? null,
       response_length: this.data.response ? this.data.response.length : null,
       execution_time_ms: this.data.executionTimeMs ?? null,
       error_type: this.data.errorType ?? null,
@@ -2382,21 +2780,72 @@ async function telFetch(url, init) {
 }
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI";
-function capturePostHog(params) {
-  const host = params.host ?? POSTHOG_HOST;
-  const apiKey = params.apiKey ?? POSTHOG_API_KEY;
-  return telFetch(`${host}/i/v0/e/`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    keepalive: true,
-    body: JSON.stringify({
+var CONTENT_PROPERTY = /(^|_)(arguments?|args|body|command|headers?|location|message|query|response|secret|subject|token|uri|url|user_agent)(_|$)/i;
+var IDENTIFYING_PROPERTY = /(^|_)(server_identifiers?|server_names?|servers|tool_names?|tools_(available|used)_names)(_|$)/i;
+var AGGREGATE_PROPERTY = /(_count|_length|_duration(?:_ms)?|_time_ms|(^|_)num_[a-z0-9_]+)$/i;
+function normalizePropertyKey(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-z0-9_$]+/gi, "_").toLowerCase();
+}
+function sanitizeValue(value, seen) {
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = value.map((item) => sanitizeValue(item, seen));
+    seen.delete(value);
+    return sanitized;
+  }
+  if (value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = sanitizeProperties(
+      value,
+      seen
+    );
+    seen.delete(value);
+    return sanitized;
+  }
+  return value;
+}
+function sanitizeProperties(properties, seen = /* @__PURE__ */ new WeakSet()) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(properties)) {
+    const normalizedKey = normalizePropertyKey(key);
+    if (AGGREGATE_PROPERTY.test(normalizedKey)) {
+      if (value === null || typeof value === "number") {
+        sanitized[key] = value;
+      }
+      continue;
+    }
+    if (IDENTIFYING_PROPERTY.test(normalizedKey) || CONTENT_PROPERTY.test(normalizedKey)) {
+      continue;
+    }
+    sanitized[key] = sanitizeValue(value, seen);
+  }
+  return sanitized;
+}
+async function capturePostHog(params) {
+  try {
+    const host = params.host ?? POSTHOG_HOST;
+    const apiKey = params.apiKey ?? POSTHOG_API_KEY;
+    const body = JSON.stringify({
       api_key: apiKey,
       event: params.event,
       distinct_id: params.distinctId,
-      properties: params.properties,
+      properties: sanitizeProperties(params.properties),
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    })
-  });
+    });
+    await telFetch(`${host}/i/v0/e/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body
+    });
+  } catch {
+  }
 }
 
 // src/telemetry/telemetry.ts
@@ -2728,11 +3177,12 @@ async function completeOAuthFlow(provider, serverUrl, options = {}) {
       throw new Error(`Unexpected OAuth auth() result: ${result}`);
     }
   }
-  if (typeof flowProvider.getAuthorizationCode === "function") {
-    const code = await flowProvider.getAuthorizationCode();
+  if (typeof flowProvider.getAuthorizationResponse === "function" || typeof flowProvider.getAuthorizationCode === "function") {
+    const response = typeof flowProvider.getAuthorizationResponse === "function" ? await flowProvider.getAuthorizationResponse() : { code: await flowProvider.getAuthorizationCode() };
     await auth(provider, {
       serverUrl,
-      authorizationCode: code,
+      authorizationCode: response.code,
+      ...response.iss !== void 0 ? { iss: response.iss } : {},
       fetchFn
     });
     return;
@@ -2746,6 +3196,8 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     );
   }
   if (provider.useRedirectFlow) {
+    await new Promise(() => {
+    });
     return;
   }
   const tokensKey = provider.getKey?.("tokens");
@@ -2762,25 +3214,29 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     } catch {
     }
   }
-  const result = await runAuthPopup({
-    popup: null,
-    state,
-    tokensKey,
-    timeoutMs
-  });
-  switch (result.kind) {
-    case "success":
-      return;
-    case "cancelled":
-      throw new Error("OAuth authentication was cancelled.");
-    case "timeout":
-      throw new Error(
-        `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
-      );
-    case "error":
-      throw new Error(result.error);
-    default:
-      throw new Error("Unexpected OAuth popup result");
+  try {
+    const result = await runAuthPopup({
+      popup: null,
+      state,
+      tokensKey,
+      timeoutMs
+    });
+    switch (result.kind) {
+      case "success":
+        return;
+      case "cancelled":
+        throw new Error("OAuth authentication was cancelled.");
+      case "timeout":
+        throw new Error(
+          `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
+        );
+      case "error":
+        throw new Error(result.error);
+      default:
+        throw new Error("Unexpected OAuth popup result");
+    }
+  } finally {
+    provider.markFlowComplete?.();
   }
 }
 
@@ -3029,7 +3485,7 @@ var MCPConnection = class {
   /**
    * Normalized server metadata for this ready connection.
    *
-   * @throws {Error} When called before protocol negotiation completes.
+   * @throws When called before protocol negotiation completes.
    */
   get info() {
     const protocolEra = this.protocolEra;
@@ -3250,12 +3706,10 @@ function isOAuthClientProvider(provider) {
 var BaseMCPClient = class {
   /**
    * Internal configuration object containing MCP server definitions.
-   * @protected
    */
   config = {};
   /**
    * Map of server names to their active sessions.
-   * @protected
    */
   sessions = {};
   /**
@@ -3299,7 +3753,7 @@ var BaseMCPClient = class {
    *
    * @param _cfg - Configuration dictionary
    * @returns Client instance
-   * @throws {Error} If called on the base class instead of a concrete implementation
+   * @throws If called on the base class instead of a concrete implementation
    *
    * @example
    * ```typescript
@@ -3441,7 +3895,7 @@ var BaseMCPClient = class {
    * @param serverName - The name of the server as defined in the client configuration
    * @param autoInitialize - Whether to automatically initialize the session (default: true)
    * @returns A promise that resolves to the created MCPSession instance
-   * @throws {Error} If the server is not found in the configuration
+   * @throws If the server is not found in the configuration
    *
    * @example
    * ```typescript
@@ -3611,7 +4065,7 @@ var BaseMCPClient = class {
    *
    * @param serverName - Name of the server
    * @returns The session instance
-   * @throws {Error} If the session is not found
+   * @throws If the session is not found
    *
    * @example
    * ```typescript
@@ -3780,16 +4234,28 @@ function trackBrowserClientInit(config) {
 }
 var BrowserMCPClient = class _BrowserMCPClient extends BaseMCPClient {
   /**
-   * Get the mcp-use package version.
-   * Works in all environments (Node.js, browser, Cloudflare Workers, Deno, etc.)
+   * Returns the installed `@mcp-use/client` package version.
+   *
+   * @returns The package version string.
    */
   static getPackageVersion() {
     return getPackageVersion();
   }
+  /**
+   * Creates a browser MCP client.
+   *
+   * @param config - Client configuration containing an optional `mcpServers` map.
+   */
   constructor(config) {
     super(config);
     trackBrowserClientInit(this.config);
   }
+  /**
+   * Creates a browser client from an inline configuration object.
+   *
+   * @param cfg - Client configuration containing an optional `mcpServers` map.
+   * @returns A browser client initialized with `cfg`.
+   */
   static fromDict(cfg) {
     return new _BrowserMCPClient(cfg);
   }
@@ -4047,9 +4513,14 @@ function startConnectionHealthMonitoring(params) {
         return;
       }
       const authHeaders = params.getAuthHeaders ? await params.getAuthHeaders() : {};
+      const healthCheckHeaders = {
+        ...params.allHeaders,
+        ...authHeaders,
+        ...params.gatewayUrl && params.url ? { "X-Target-URL": params.url } : {}
+      };
       const response = await fetch(healthCheckUrl, {
         method: "HEAD",
-        headers: { ...params.allHeaders, ...authHeaders },
+        headers: healthCheckHeaders,
         signal: AbortSignal.timeout(5e3)
       });
       if (response.status === 405 || response.status === 404) {
@@ -4254,6 +4725,16 @@ function useMcpOperations(params) {
   };
 }
 
+// src/react/token-expiry.ts
+function getOAuthTokenExpiry(tokens) {
+  try {
+    const payload = JSON.parse(atob(tokens.access_token?.split(".")[1] ?? ""));
+    if (typeof payload.exp === "number") return payload.exp * 1e3;
+  } catch {
+  }
+  return typeof tokens.expires_in === "number" ? Date.now() + tokens.expires_in * 1e3 : void 0;
+}
+
 // src/react/useMcp.ts
 var DEFAULT_RECONNECT_DELAY = 3e3;
 var DEFAULT_RETRY_DELAY = 5e3;
@@ -4269,6 +4750,7 @@ function useMcp(options) {
     headers: headersOption,
     proxyConfig,
     oauthProxyUrl: oauthProxyUrlOption,
+    connectionMode,
     autoProxyFallback = false,
     logLevel: logLevelOption = "silent",
     autoRetry = false,
@@ -4292,6 +4774,7 @@ function useMcp(options) {
     oauth: oauthOptions
   } = options;
   const transportType = "http";
+  const requestedProxyAddress = proxyConfig?.proxyAddress;
   const oauthClientId = oauthOptions?.clientId?.trim() || void 0;
   const oauthClientMetadataUrl = oauthOptions?.clientMetadataUrl?.trim() || void 0;
   const oauthScope = oauthOptions?.scope?.trim() || void 0;
@@ -4339,6 +4822,9 @@ function useMcp(options) {
   );
   const oauthClientConfig = derivedOAuthClientConfig;
   const autoProxyFallbackConfig = useMemo(() => {
+    if (connectionMode === "direct" || connectionMode === "proxy") {
+      return { enabled: false, proxyAddress: void 0 };
+    }
     if (!autoProxyFallback) {
       return { enabled: false, proxyAddress: void 0 };
     }
@@ -4354,7 +4840,7 @@ function useMcp(options) {
       enabled: autoProxyFallback.enabled !== false && Boolean(proxyAddress),
       proxyAddress
     };
-  }, [autoProxyFallback, proxyConfig]);
+  }, [autoProxyFallback, connectionMode, proxyConfig]);
   const autoReconnectConfig = useMemo(() => {
     if (autoReconnect === false) {
       return {
@@ -4390,20 +4876,33 @@ function useMcp(options) {
   const [effectiveProxyConfig, setEffectiveProxyConfig] = useState(void 0);
   useEffect(() => {
     setEffectiveProxyConfig(void 0);
-  }, [url, proxyConfig]);
+  }, [
+    url,
+    requestedProxyAddress,
+    connectionMode,
+    autoProxyFallbackConfig.proxyAddress
+  ]);
   const activeProxyConfig = useMemo(() => {
-    if (!effectiveProxyConfig?.proxyAddress) {
-      return proxyConfig;
+    const hasCurrentAutoFallback = autoProxyFallbackConfig.enabled && effectiveProxyConfig?.proxyAddress === autoProxyFallbackConfig.proxyAddress;
+    if (hasCurrentAutoFallback && effectiveProxyConfig) {
+      const latestHeaders = proxyConfig?.headers ?? {};
+      return {
+        ...effectiveProxyConfig,
+        headers: {
+          ...latestHeaders,
+          ...effectiveProxyConfig.headers ?? {}
+        }
+      };
     }
-    const latestHeaders = proxyConfig?.headers ?? {};
-    return {
-      ...effectiveProxyConfig,
-      headers: {
-        ...latestHeaders,
-        ...effectiveProxyConfig.headers ?? {}
-      }
-    };
-  }, [effectiveProxyConfig, proxyConfig]);
+    const startsDirect = connectionMode === "auto" || connectionMode === "direct" || connectionMode === void 0 && autoProxyFallbackConfig.enabled;
+    return startsDirect ? void 0 : proxyConfig;
+  }, [
+    effectiveProxyConfig,
+    proxyConfig,
+    connectionMode,
+    autoProxyFallbackConfig.enabled,
+    autoProxyFallbackConfig.proxyAddress
+  ]);
   const gatewayUrl = activeProxyConfig?.proxyAddress;
   const proxyHeaders = activeProxyConfig?.headers ?? {};
   const effectiveOAuthUrl = useMemo(() => {
@@ -4735,8 +5234,9 @@ function useMcp(options) {
           clientInfo: mergedClientInfo,
           // Pass a fetch that scopes OAuth-proxy routing to this server's
           // transport/auth calls. getProxyFetch wraps `customFetch` (e.g. the
-          // OAuth retry fetch for scope step-up) when proxying, or returns it
-          // unchanged otherwise. Never mutates the global fetch.
+          // OAuth retry fetch for scope step-up), bypasses the browser cache
+          // for OAuth metadata, and optionally routes OAuth through the BFF.
+          // It never mutates the global fetch.
           ...(() => {
             const scopedFetch = authProviderRef.current?.getProxyFetch?.(customFetch) ?? customFetch;
             return scopedFetch ? { fetch: scopedFetch } : {};
@@ -4874,9 +5374,22 @@ function useMcp(options) {
         });
         setTools(connection.tools || []);
         const [resourcesResult, promptsResult, templatesResult] = await Promise.all([
-          connection.listAllResources(),
-          connection.listPrompts(),
-          connection.supports("resources") ? connection.listResourceTemplates() : Promise.resolve({ resourceTemplates: [] })
+          connection.listAllResources().catch((error2) => {
+            addLog("warn", "Failed to load initial resources:", error2);
+            return { resources: [] };
+          }),
+          connection.listPrompts().catch((error2) => {
+            addLog("warn", "Failed to load initial prompts:", error2);
+            return { prompts: [] };
+          }),
+          connection.supports("resources") ? connection.listResourceTemplates().catch((error2) => {
+            addLog(
+              "warn",
+              "Failed to load initial resource templates:",
+              error2
+            );
+            return { resourceTemplates: [] };
+          }) : Promise.resolve({ resourceTemplates: [] })
         ]);
         if (!isMountedRef.current) {
           addLog(
@@ -4935,7 +5448,7 @@ function useMcp(options) {
             return "failed";
           }
           if (tokens?.access_token) {
-            const expiresAt = tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0;
+            const expiresAt = getOAuthTokenExpiry(tokens);
             let tokenEndpoint = null;
             let resource = null;
             let clientCreds = null;
@@ -5045,8 +5558,10 @@ function useMcp(options) {
                   fetchFn: authProviderRef.current.getProxyFetch?.()
                 });
                 if (authResult === "REDIRECT") {
-                  const authCode = await authProviderRef.current.getAuthorizationCode?.();
-                  if (!authCode) {
+                  const flowProvider = authProviderRef.current;
+                  const authResponse = await flowProvider.getAuthorizationResponse?.();
+                  const authCode = authResponse?.code ?? await flowProvider.getAuthorizationCode?.();
+                  if (typeof authCode !== "string") {
                     throw new Error(
                       "Authorization code not captured by headless provider"
                     );
@@ -5054,6 +5569,7 @@ function useMcp(options) {
                   await auth2(authProviderRef.current, {
                     serverUrl: url,
                     authorizationCode: authCode,
+                    ...authResponse?.iss !== void 0 ? { iss: authResponse.iss } : {},
                     fetchFn: authProviderRef.current.getProxyFetch?.()
                   });
                 }
@@ -5210,19 +5726,20 @@ function useMcp(options) {
         addLog("info", "Triggering fresh OAuth authorization...");
         const parsedUrl = new URL(url);
         const baseUrl = parsedUrl.origin + parsedUrl.pathname.replace(/\/+$/, "");
-        try {
-          await auth2(freshAuthProvider, {
-            serverUrl: baseUrl,
-            fetchFn: freshAuthProvider.getProxyFetch?.()
-          });
+        const authResult = await auth2(freshAuthProvider, {
+          serverUrl: baseUrl,
+          fetchFn: freshAuthProvider.getProxyFetch?.()
+        });
+        if (authResult === "AUTHORIZED") {
           addLog("info", "OAuth flow completed (tokens obtained)");
-        } catch (err) {
-          addLog(
-            "info",
-            "OAuth flow initiated (popup/redirect):",
-            err instanceof Error ? err.message : "Redirecting..."
-          );
+          connectingRef.current = false;
+          connectRef.current?.();
+          return;
         }
+        if (authResult !== "REDIRECT") {
+          throw new Error(`Unexpected OAuth auth() result: ${authResult}`);
+        }
+        addLog("info", "OAuth authorization redirect initiated");
         const newAuthUrl = freshAuthProvider.getLastAttemptedAuthUrl?.();
         if (newAuthUrl) {
           setAuthUrl(newAuthUrl);
@@ -5288,11 +5805,8 @@ function useMcp(options) {
         }
       } catch (authError) {
         if (!isMountedRef.current) return;
-        setState("pending_auth");
-        addLog(
-          "error",
-          `Manual authentication failed: ${authError instanceof Error ? authError.message : String(authError)}`
-        );
+        const error2 = authError instanceof Error ? authError : new Error(String(authError));
+        failConnection(`Manual authentication failed: ${error2.message}`, error2);
       }
     } else if (currentState === "authenticating") {
       addLog(
@@ -5500,6 +6014,7 @@ function useMcp(options) {
     // Triggers reconnection when proxy fallback changes OAuth URL
     proxyConfig,
     // Triggers reconnection when proxy config (including headers) changes
+    autoProxyFallbackConfig.proxyAddress,
     providedAuthProvider
   ]);
   const retryRef = useRef(retry);
@@ -5649,20 +6164,14 @@ function renderResult(title, message, error, returnUrl) {
   }
   document.body.appendChild(container);
 }
-function findStoredState(state) {
-  const defaultKey = `mcp:auth:state_${state}`;
-  let key = localStorage.getItem(defaultKey) ? defaultKey : null;
-  if (!key) {
-    const suffix = `:state_${state}`;
-    for (let index = 0; index < localStorage.length; index++) {
-      const candidate = localStorage.key(index);
-      if (candidate?.endsWith(suffix)) {
-        key = candidate;
-        break;
-      }
-    }
-  }
-  const serialized = key ? localStorage.getItem(key) : null;
+async function findStoredState(state) {
+  const store = new LocalStorageKVStore();
+  const legacySuffix = `:state_${state}`;
+  const scopedSuffix = `_state_${state}`;
+  const key = (await store.keys()).find(
+    (candidate) => candidate.endsWith(legacySuffix) || candidate.endsWith(scopedSuffix)
+  );
+  const serialized = key ? await store.get(key) : null;
   if (!key || !serialized) {
     throw new Error(`Invalid or expired OAuth state "${state}".`);
   }
@@ -5670,10 +6179,10 @@ function findStoredState(state) {
   try {
     value = JSON.parse(serialized);
   } catch {
-    localStorage.removeItem(key);
+    await store.remove(key);
     throw new Error("Failed to parse stored OAuth state.");
   }
-  return { key, value };
+  return { key, value, store };
 }
 function redirectWithError(returnUrl, message) {
   const url = new URL(returnUrl);
@@ -5732,17 +6241,19 @@ async function completeAuthorization() {
   const callbackParams = new URLSearchParams(window.location.search);
   const state = callbackParams.get("state");
   let stateKey = null;
+  let stateStore = null;
   let storedState = null;
   let provider = null;
   try {
     if (!state) {
       throw new Error("OAuth callback is missing the state parameter.");
     }
-    const stored = findStoredState(state);
+    const stored = await findStoredState(state);
     stateKey = stored.key;
+    stateStore = stored.store;
     storedState = stored.value;
     if (!storedState.expiry || storedState.expiry < Date.now()) {
-      localStorage.removeItem(stateKey);
+      await stateStore.remove(stateKey);
       throw new Error(
         "OAuth state has expired. Please start authentication again."
       );
@@ -5757,7 +6268,7 @@ async function completeAuthorization() {
       fetch: provider.getProxyFetch()
     });
     await transport.finishAuth(callbackParams);
-    localStorage.removeItem(stateKey);
+    await stateStore.remove(stateKey);
     signalResult(true, void 0, storedState, {
       state,
       serverUrlHash: storedState.serverUrlHash
@@ -5765,8 +6276,12 @@ async function completeAuthorization() {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error("[mcp-callback] OAuth callback failed:", error);
-    if (stateKey) localStorage.removeItem(stateKey);
-    if (provider) localStorage.removeItem(provider.getKey("last_auth_url"));
+    if (stateKey && stateStore) await stateStore.remove(stateKey);
+    if (provider) {
+      await (stateStore ?? new LocalStorageKVStore()).remove(
+        provider.getKey("last_auth_url")
+      );
+    }
     signalResult(false, message, storedState, {
       state,
       serverUrlHash: storedState?.serverUrlHash
@@ -5789,45 +6304,6 @@ import React, {
   useState as useState3
 } from "react";
 
-// src/react/types.ts
-var PERSISTED_SERVER_CONFIG_KEYS = [
-  "url",
-  "displayName",
-  "enabled",
-  "proxyConfig",
-  "oauthProxyUrl",
-  "connectionMode",
-  "autoProxyFallback",
-  "callbackUrl",
-  "storageKeyPrefix",
-  "headers",
-  "logLevel",
-  "autoRetry",
-  "autoReconnect",
-  "reconnectionOptions",
-  "popupFeatures",
-  "preventAutoAuth",
-  "useRedirectFlow",
-  "clientOptions",
-  "protocolNegotiation",
-  "timeout",
-  "clientInfo",
-  "oauth"
-];
-function pickPersistedServerConfig(source) {
-  const out = {};
-  for (const key of PERSISTED_SERVER_CONFIG_KEYS) {
-    const value = source[key];
-    if (value !== void 0) {
-      out[key] = value;
-    }
-  }
-  return out;
-}
-function toPersistedServerConfig(config) {
-  return pickPersistedServerConfig(config);
-}
-
 // src/react/useMcpServerQueues.ts
 import { useCallback as useCallback3, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
 var MAX_NOTIFICATIONS = 500;
@@ -6014,8 +6490,8 @@ function sameSerializedValue(left, right) {
 }
 function isSameMcpServer(left, right) {
   return left.id === right.id && sameSerializedValue(
-    pickPersistedServerConfig(left),
-    pickPersistedServerConfig(right)
+    pickLiveServerConfig(left),
+    pickLiveServerConfig(right)
   ) && left.name === right.name && left.state === right.state && left.error === right.error && left.authUrl === right.authUrl && sameSerializedValue(left.authTokens, right.authTokens) && left.protocolEra === right.protocolEra && left.protocolVersion === right.protocolVersion && sameSerializedValue(left.serverInfo, right.serverInfo) && sameSerializedValue(left.capabilities, right.capabilities) && left.instructions === right.instructions && sameSerializedValue(left.extensions, right.extensions) && sameSerializedValue(left.tools, right.tools) && sameSerializedValue(left.resources, right.resources) && sameSerializedValue(left.resourceTemplates, right.resourceTemplates) && sameSerializedValue(left.prompts, right.prompts) && sameSerializedValue(left.notifications, right.notifications) && left.unreadNotificationCount === right.unreadNotificationCount && sameSerializedValue(
     left.pendingSamplingRequests,
     right.pendingSamplingRequests
@@ -6149,7 +6625,7 @@ function McpServerWrapper({
   }, [onUpdate]);
   useEffect3(() => {
     const server = {
-      ...toPersistedServerConfig(options),
+      ...pickLiveServerConfig(options),
       ...mcp,
       id,
       displayName: displayName || options.displayName || id,
@@ -6496,8 +6972,8 @@ function McpClientProvider({
         ...options
       };
       if (sameSerializedValue(
-        pickPersistedServerConfig(currentConfig.options),
-        pickPersistedServerConfig(updatedOptions)
+        pickLiveServerConfig(currentConfig.options),
+        pickLiveServerConfig(updatedOptions)
       )) {
         return;
       }
@@ -6656,70 +7132,115 @@ function useMcpServer(id) {
 
 // src/react/storage.ts
 var LocalStorageProvider = class {
+  /**
+   * Creates a browser storage provider.
+   *
+   * @param storageKey - Key used for configurations. Metadata uses the same key
+   * with a `-metadata` suffix. Defaults to `"mcp-client-servers"`.
+   */
   constructor(storageKey = "mcp-client-servers") {
     this.storageKey = storageKey;
     this.metadataKey = `${storageKey}-metadata`;
   }
   metadataKey;
+  /** Returns sanitized server configurations from `localStorage`. */
   getServers() {
     try {
       const stored = localStorage.getItem(this.storageKey);
-      return stored ? JSON.parse(stored) : {};
-    } catch (error) {
-      console.error("[LocalStorageProvider] Failed to load servers:", error);
+      if (!stored) return {};
+      const parsed = JSON.parse(stored);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+      }
+      const sanitized = Object.fromEntries(
+        Object.entries(parsed).flatMap(
+          ([id, config]) => config && typeof config === "object" && !Array.isArray(config) ? [
+            [
+              id,
+              toPersistedServerConfig(config)
+            ]
+          ] : []
+        )
+      );
+      const serialized = JSON.stringify(sanitized);
+      if (serialized !== stored) {
+        try {
+          localStorage.setItem(this.storageKey, serialized);
+        } catch {
+          console.error(
+            "[LocalStorageProvider] Failed to persist sanitized servers."
+          );
+        }
+      }
+      return sanitized;
+    } catch {
+      console.error("[LocalStorageProvider] Failed to load servers.");
       return {};
     }
   }
+  /** Replaces all saved server configurations. */
   setServers(servers) {
     try {
-      localStorage.setItem(this.storageKey, JSON.stringify(servers));
-    } catch (error) {
-      console.error("[LocalStorageProvider] Failed to save servers:", error);
+      const sanitized = Object.fromEntries(
+        Object.entries(servers).map(([id, config]) => [
+          id,
+          toPersistedServerConfig(config)
+        ])
+      );
+      localStorage.setItem(this.storageKey, JSON.stringify(sanitized));
+    } catch {
+      console.error("[LocalStorageProvider] Failed to save servers.");
     }
   }
+  /** Saves one server configuration. */
   setServer(id, config) {
     const servers = this.getServers();
     servers[id] = config;
     this.setServers(servers);
   }
+  /** Removes one server and its cached metadata. */
   removeServer(id) {
     const servers = this.getServers();
     delete servers[id];
     this.setServers(servers);
     this.removeServerMetadata(id);
   }
+  /** Removes all saved configurations and metadata. */
   clear() {
     try {
       localStorage.removeItem(this.storageKey);
       localStorage.removeItem(this.metadataKey);
-    } catch (error) {
-      console.error("[LocalStorageProvider] Failed to clear:", error);
+    } catch {
+      console.error("[LocalStorageProvider] Failed to clear.");
     }
   }
   getAllMetadata() {
     try {
       const stored = localStorage.getItem(this.metadataKey);
       return stored ? JSON.parse(stored) : {};
-    } catch (error) {
-      console.error("[LocalStorageProvider] Failed to load metadata:", error);
+    } catch {
+      console.error("[LocalStorageProvider] Failed to load metadata.");
       return {};
     }
   }
   setAllMetadata(metadata) {
     try {
       localStorage.setItem(this.metadataKey, JSON.stringify(metadata));
-    } catch (error) {
-      console.error("[LocalStorageProvider] Failed to save metadata:", error);
+    } catch {
+      console.error("[LocalStorageProvider] Failed to save metadata.");
     }
   }
+  /** Returns cached presentation metadata for a server. */
   getServerMetadata(id) {
     return this.getAllMetadata()[id];
   }
+  /** Saves presentation metadata and stamps the current cache time. */
   setServerMetadata(id, metadata) {
     const allMetadata = this.getAllMetadata();
     allMetadata[id] = { ...metadata, cachedAt: Date.now() };
     this.setAllMetadata(allMetadata);
   }
+  /** Removes cached presentation metadata for a server. */
   removeServerMetadata(id) {
     const allMetadata = this.getAllMetadata();
     delete allMetadata[id];
@@ -6729,29 +7250,42 @@ var LocalStorageProvider = class {
 var MemoryStorageProvider = class {
   storage = {};
   metadata = {};
+  /** Returns a shallow copy of all stored server configurations. */
   getServers() {
     return { ...this.storage };
   }
+  /** Replaces all stored server configurations. */
   setServers(servers) {
-    this.storage = { ...servers };
+    this.storage = Object.fromEntries(
+      Object.entries(servers).map(([id, config]) => [
+        id,
+        toPersistedServerConfig(config)
+      ])
+    );
   }
+  /** Stores one server configuration. */
   setServer(id, config) {
-    this.storage[id] = config;
+    this.storage[id] = toPersistedServerConfig(config);
   }
+  /** Removes one server and its cached metadata. */
   removeServer(id) {
     delete this.storage[id];
     this.removeServerMetadata(id);
   }
+  /** Removes all configurations and metadata. */
   clear() {
     this.storage = {};
     this.metadata = {};
   }
+  /** Returns cached presentation metadata for a server. */
   getServerMetadata(id) {
     return this.metadata[id];
   }
+  /** Saves presentation metadata and stamps the current cache time. */
   setServerMetadata(id, metadata) {
     this.metadata[id] = { ...metadata, cachedAt: Date.now() };
   }
+  /** Removes cached presentation metadata for a server. */
   removeServerMetadata(id) {
     delete this.metadata[id];
   }
@@ -6816,32 +7350,58 @@ var OPENAI_FILE_APIS_SCRIPT = `<script>
 })();
 </script>`;
 function injectOpenAiFileApis(html) {
-  if (html.includes("<head>")) {
-    return html.replace("<head>", "<head>" + OPENAI_FILE_APIS_SCRIPT);
-  }
-  if (html.includes("<HEAD>")) {
-    return html.replace("<HEAD>", "<HEAD>" + OPENAI_FILE_APIS_SCRIPT);
-  }
-  if (html.includes("<html>")) {
-    return html.replace(
-      "<html>",
-      "<html><head>" + OPENAI_FILE_APIS_SCRIPT + "</head>"
+  const headEnd = findOpeningConstructEnd(html, "<head");
+  if (headEnd !== void 0) {
+    return insertAt(html, headEnd, OPENAI_FILE_APIS_SCRIPT);
+  }
+  const htmlEnd = findOpeningConstructEnd(html, "<html");
+  if (htmlEnd !== void 0) {
+    return insertAt(
+      html,
+      htmlEnd,
+      "<head>" + OPENAI_FILE_APIS_SCRIPT + "</head>"
     );
   }
-  if (html.includes("<HTML>")) {
-    return html.replace(
-      "<HTML>",
-      "<HTML><head>" + OPENAI_FILE_APIS_SCRIPT + "</head>"
-    );
-  }
-  if (html.includes("<!DOCTYPE") || html.includes("<!doctype")) {
-    return html.replace(
-      /(<!DOCTYPE[^>]*>|<!doctype[^>]*>)/i,
-      "$1<head>" + OPENAI_FILE_APIS_SCRIPT + "</head>"
+  const doctypeEnd = findOpeningConstructEnd(html, "<!doctype");
+  if (doctypeEnd !== void 0) {
+    return insertAt(
+      html,
+      doctypeEnd,
+      "<head>" + OPENAI_FILE_APIS_SCRIPT + "</head>"
     );
   }
   return OPENAI_FILE_APIS_SCRIPT + html;
 }
+function findOpeningConstructEnd(html, lowercasePrefix) {
+  const lowercaseHtml = html.toLowerCase();
+  let searchFrom = 0;
+  while (searchFrom < lowercaseHtml.length) {
+    const start = lowercaseHtml.indexOf(lowercasePrefix, searchFrom);
+    if (start === -1) return void 0;
+    const boundary = lowercaseHtml[start + lowercasePrefix.length];
+    if (boundary === ">" || boundary === " " || boundary === "	" || boundary === "\n" || boundary === "\r" || boundary === "\f") {
+      let quote;
+      for (let index = start + lowercasePrefix.length; index < html.length; index++) {
+        const character = html[index];
+        if (quote) {
+          if (character === quote) quote = void 0;
+          continue;
+        }
+        if (character === '"' || character === "'") {
+          quote = character;
+          continue;
+        }
+        if (character === ">") return index + 1;
+      }
+      return void 0;
+    }
+    searchFrom = start + lowercasePrefix.length;
+  }
+  return void 0;
+}
+function insertAt(value, index, addition) {
+  return value.slice(0, index) + addition + value.slice(index);
+}
 
 // src/react/view/resolve-view-resource.ts
 function resolveViewResource(options) {
@@ -6890,6 +7450,11 @@ function resolveViewResource(options) {
 }
 
 // src/react/view/sandbox-blob-url.ts
+function buildViewSandboxUrl(sandboxDocumentUrl, options) {
+  const url = new URL(sandboxDocumentUrl.href);
+  applySandboxSearchParams(url, options);
+  return url;
+}
 function applySandboxSearchParams(url, options) {
   const { cspMode, permissions, widgetCsp } = options;
   url.searchParams.set(
@@ -7256,6 +7821,67 @@ var VIEW_DIMENSIONS = {
   FULLSCREEN_HEADER_HEIGHT: 50
 };
 
+// src/react/view/view-host-policy.ts
+function buildDefaultHostCapabilities({
+  hasConnection,
+  hasMessageHandler,
+  hasModelContextHandler,
+  hasLogHandler,
+  hasSamplingHandler,
+  hasDownloadHandler,
+  messageCapabilities,
+  modelContextCapabilities
+}) {
+  return {
+    openLinks: {},
+    ...hasConnection ? {
+      serverTools: {},
+      serverResources: {}
+    } : {},
+    ...hasLogHandler ? { logging: {} } : {},
+    ...hasSamplingHandler ? { sampling: {} } : {},
+    ...hasDownloadHandler ? { downloadFile: {} } : {},
+    ...hasModelContextHandler ? { updateModelContext: modelContextCapabilities ?? { text: {} } } : {},
+    ...hasMessageHandler ? { message: messageCapabilities ?? { text: {} } } : {}
+  };
+}
+function isToolVisibleToModel(tool) {
+  if (!tool._meta || typeof tool._meta !== "object") return true;
+  const ui = tool._meta.ui;
+  if (!ui || typeof ui !== "object") return true;
+  const visibility = ui.visibility;
+  return !Array.isArray(visibility) || visibility.some((value) => value === "model");
+}
+async function dispatchUiMessage(handler, content) {
+  if (!handler) {
+    throw new Error("This host surface does not support ui/message");
+  }
+  if (content.length === 0) {
+    throw new Error("ui/message requires at least one content block");
+  }
+  await handler(content);
+}
+function resolveRequestedDisplayMode({
+  requested,
+  current,
+  hostAvailable,
+  appAvailable
+}) {
+  const hostModes = hostAvailable ?? ["inline"];
+  const appModes = appAvailable ?? ["inline"];
+  return hostModes.includes(requested) && appModes.includes(requested) ? requested : current;
+}
+function assertAppCanCallTool(tools, name) {
+  const tool = tools?.find((candidate) => candidate.name === name);
+  if (!tool) {
+    throw new Error(`Tool "${name}" is not available to this app`);
+  }
+  const visibility = tool._meta?.ui?.visibility;
+  if (visibility && !visibility.includes("app")) {
+    throw new Error(`Tool "${name}" is not available to this app`);
+  }
+}
+
 // src/react/view/view-detection.ts
 function getViewResourceUri(toolMeta) {
   const uri = toolMeta?.ui;
@@ -7275,15 +7901,6 @@ function isViewResource(mimeType) {
 var DEFAULT_HOST_INFO = { name: "mcp-use-client", version: "2.0.0" };
 var DEFAULT_TOOL_CALL_TIMEOUT = 6e5;
 var SANDBOX_PROXY_READY = "ui/notifications/sandbox-proxy-ready";
-var DEFAULT_HOST_CAPABILITIES = {
-  openLinks: {},
-  serverTools: {},
-  serverResources: {},
-  logging: {},
-  updateModelContext: { text: {} },
-  // ponytail: always advertised; bridge.onmessage no-ops when onMessage unset
-  message: { text: {} }
-};
 function CloseIcon() {
   return /* @__PURE__ */ React2.createElement(
     "svg",
@@ -7347,12 +7964,17 @@ function ViewRendererBase({
   hostInfo = DEFAULT_HOST_INFO,
   hostContext,
   hostCapabilities,
+  messageCapabilities,
+  modelContextCapabilities,
   cspMode = "widget-declared",
   displayMode: displayModeProp,
   onDisplayModeChange,
   inlineMaxWidth = 768,
   chromeless,
   onMessage,
+  onSamplingRequest,
+  onDownloadFile,
+  onAppToolsChanged,
   onModelContextUpdate,
   onLog,
   onReady,
@@ -7384,12 +8006,42 @@ function ViewRendererBase({
   const [activeSandboxUrl, setActiveSandboxUrl] = useState4(null);
   const [loadError, setLoadError] = useState4(null);
   const [initCount, setInitCount] = useState4(0);
-  const [showSpinner, setShowSpinner] = useState4(true);
   const [inlineHeight, setInlineHeight] = useState4(
     VIEW_DIMENSIONS.DEFAULT_HEIGHT
   );
   const [internalDisplayMode, setInternalDisplayMode] = useState4("inline");
   const displayMode = displayModeProp ?? internalDisplayMode;
+  const hasMessageHandler = onMessage !== void 0;
+  const hasModelContextHandler = onModelContextUpdate !== void 0;
+  const hasLogHandler = onLog !== void 0;
+  const hasSamplingHandler = onSamplingRequest !== void 0;
+  const hasDownloadHandler = onDownloadFile !== void 0;
+  const effectiveHostCapabilities = useMemo3(
+    () => ({
+      ...buildDefaultHostCapabilities({
+        hasConnection: source.kind === "live",
+        hasMessageHandler,
+        hasModelContextHandler,
+        hasLogHandler,
+        hasSamplingHandler,
+        hasDownloadHandler,
+        messageCapabilities,
+        modelContextCapabilities
+      }),
+      ...hostCapabilities
+    }),
+    [
+      hostCapabilities,
+      hasLogHandler,
+      hasSamplingHandler,
+      hasDownloadHandler,
+      hasMessageHandler,
+      hasModelContextHandler,
+      messageCapabilities,
+      modelContextCapabilities,
+      source.kind
+    ]
+  );
   const effectiveHostContext = useMemo3(() => {
     if (!hostContext) return hostContext;
     if (hostContext.displayMode === displayMode) return hostContext;
@@ -7399,6 +8051,12 @@ function ViewRendererBase({
   hostContextRef.current = effectiveHostContext;
   const onMessageRef = useRef4(onMessage);
   onMessageRef.current = onMessage;
+  const onSamplingRequestRef = useRef4(onSamplingRequest);
+  onSamplingRequestRef.current = onSamplingRequest;
+  const onDownloadFileRef = useRef4(onDownloadFile);
+  onDownloadFileRef.current = onDownloadFile;
+  const onAppToolsChangedRef = useRef4(onAppToolsChanged);
+  onAppToolsChangedRef.current = onAppToolsChanged;
   const toolInputRef = useRef4(toolInput);
   toolInputRef.current = toolInput;
   const partialToolInputRef = useRef4(partialToolInput);
@@ -7615,7 +8273,7 @@ function ViewRendererBase({
         await readyPromise;
         if (disposed) return;
         const capabilities = {
-          ...hostCapabilities ?? DEFAULT_HOST_CAPABILITIES,
+          ...effectiveHostCapabilities,
           sandbox: {
             csp: cspMode === "permissive" ? void 0 : resolved.csp,
             permissions: resolved.permissions
@@ -7624,75 +8282,110 @@ function ViewRendererBase({
         bridge = new AppBridge(null, hostInfo, capabilities, {
           hostContext: hostContextRef.current
         });
-        bridge.onmessage = async ({
-          content
-        }) => {
-          if (content.length > 0 && onMessageRef.current) {
-            onMessageRef.current(content);
-          }
-          return {};
-        };
+        if (capabilities.message) {
+          bridge.onmessage = async ({
+            content
+          }) => {
+            await dispatchUiMessage(onMessageRef.current, content);
+            return {};
+          };
+        }
+        if (capabilities.sampling) {
+          bridge.oncreatesamplingmessage = async (params) => {
+            const handler = onSamplingRequestRef.current;
+            if (!handler) {
+              throw new Error("This host surface does not support sampling");
+            }
+            return handler(params);
+          };
+        }
+        if (capabilities.downloadFile) {
+          bridge.ondownloadfile = async (params) => {
+            const handler = onDownloadFileRef.current;
+            if (!handler) {
+              throw new Error("This host surface does not support downloads");
+            }
+            return handler(params);
+          };
+        }
         bridge.onopenlink = async ({ url }) => {
           if (url) window.open(url, "_blank", "noopener,noreferrer");
           return {};
         };
-        bridge.oncalltool = (async ({
-          name,
-          arguments: args
-        }) => {
-          const conn = connectionRef.current;
-          if (!conn) throw new Error("Server connection not available");
-          try {
-            return await conn.callTool(name, args || {}, {
-              timeout: toolCallTimeout,
-              resetTimeoutOnProgress: true
-            });
-          } catch (error) {
-            bridge?.sendToolCancelled({
-              reason: error instanceof Error ? error.message : String(error)
-            });
-            throw error;
-          }
-        });
-        bridge.onreadresource = (async ({
-          uri
-        }) => {
-          const conn = connectionRef.current;
-          if (!conn) throw new Error("Server connection not available");
-          return await conn.readResource(uri);
-        });
-        bridge.onlistresources = (async () => {
-          const conn = connectionRef.current;
-          if (!conn) throw new Error("Server connection not available");
-          return { resources: [...conn.resources ?? []] };
-        });
+        if (capabilities.serverTools) {
+          bridge.oncalltool = (async ({
+            name,
+            arguments: args
+          }) => {
+            const conn = connectionRef.current;
+            if (!conn) throw new Error("Server connection not available");
+            assertAppCanCallTool(conn.tools, name);
+            try {
+              return await conn.callTool(name, args || {}, {
+                timeout: toolCallTimeout,
+                resetTimeoutOnProgress: true
+              });
+            } catch (error) {
+              bridge?.sendToolCancelled({
+                reason: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
+            }
+          });
+        }
+        if (capabilities.serverResources) {
+          bridge.onreadresource = (async ({
+            uri
+          }) => {
+            const conn = connectionRef.current;
+            if (!conn) throw new Error("Server connection not available");
+            return await conn.readResource(uri);
+          });
+          bridge.onlistresources = (async () => {
+            const conn = connectionRef.current;
+            if (!conn) throw new Error("Server connection not available");
+            return { resources: [...conn.resources ?? []] };
+          });
+        }
         bridge.onrequestdisplaymode = async ({
           mode
         }) => {
           const requested = mode ?? "inline";
-          const available = hostContextRef.current?.availableDisplayModes ?? [
-            "inline",
-            "pip",
-            "fullscreen"
-          ];
-          const effective = available.includes(requested) ? requested : displayModeRef.current;
+          const effective = resolveRequestedDisplayMode({
+            requested,
+            current: displayModeRef.current,
+            hostAvailable: hostContextRef.current?.availableDisplayModes,
+            appAvailable: bridge?.getAppCapabilities()?.availableDisplayModes
+          });
           await handleDisplayModeChangeRef.current(effective);
           return { mode: effective };
         };
-        bridge.onupdatemodelcontext = async ({
-          content,
-          structuredContent
-        }) => {
-          onModelContextUpdateRef.current?.({ content, structuredContent });
-          return {};
-        };
-        bridge.onloggingmessage = async ({
-          level,
-          data
-        }) => {
-          onLogRef.current?.({ level, data });
-          return {};
-        };
+        if (capabilities.updateModelContext) {
+          bridge.onupdatemodelcontext = async ({
+            content,
+            structuredContent
+          }) => {
+            if (!onModelContextUpdateRef.current) {
+              throw new Error(
+                "This host surface does not support model context updates"
+              );
+            }
+            await onModelContextUpdateRef.current({
+              content,
+              structuredContent
+            });
+            return {};
+          };
+        }
+        if (capabilities.logging) {
+          bridge.onloggingmessage = async ({
+            level,
+            data
+          }) => {
+            onLogRef.current?.({ level, data });
+            return {};
+          };
+        }
         bridge.onsizechange = async ({
           height
         }) => {
@@ -7702,6 +8395,35 @@ function ViewRendererBase({
             onInlineHeightChangeRef.current?.(height);
           }
         };
+        let publishedAppToolsSignature = null;
+        const publishAppTools = async () => {
+          const handler = onAppToolsChangedRef.current;
+          if (!bridge || !handler) return;
+          const appCapabilities = bridge.getAppCapabilities();
+          if (!appCapabilities?.tools) {
+            handler(null);
+            return;
+          }
+          const result = await bridge.listTools({});
+          if (disposed || !bridge) return;
+          const signature = JSON.stringify(result.tools);
+          if (signature === publishedAppToolsSignature) return;
+          publishedAppToolsSignature = signature;
+          const currentBridge = bridge;
+          handler({
+            tools: result.tools,
+            callTool: (name, args) => currentBridge.callTool({
+              name,
+              arguments: args ?? {}
+            })
+          });
+        };
+        bridge.setNotificationHandler(
+          "notifications/tools/list_changed",
+          async () => {
+            await publishAppTools();
+          }
+        );
         const initPromise = hookInitialized(bridge);
         let transport = new PostMessageTransport(
           iframe.contentWindow,
@@ -7722,9 +8444,11 @@ function ViewRendererBase({
         bridgeRef.current = bridge;
         setInitCount((c) => c + 1);
         onLifecycleChangeRef.current?.({ status: "initialized" });
+        await publishAppTools();
         const currentPartialToolInput = partialToolInputRef.current;
-        if (currentPartialToolInput) {
-          bridge.sendToolInputPartial({
+        const hasCompletedToolResult = toolOutputRef.current !== void 0 && toolOutputRef.current !== null;
+        if (currentPartialToolInput && !hasCompletedToolResult) {
+          await bridge.sendToolInputPartial({
             arguments: currentPartialToolInput
           });
         } else {
@@ -7732,14 +8456,14 @@ function ViewRendererBase({
             ...toolInputRef.current,
             ...parseCustomProps(customPropsRef.current)
           };
-          bridge.sendToolInput({ arguments: mergedArgs });
+          await bridge.sendToolInput({ arguments: mergedArgs });
         }
         const toolResultPayload = buildToolResultPayload(
           toolOutputRef.current,
           customPropsRef.current
         );
         if (toolResultPayload) {
-          bridge.sendToolResult(toolResultPayload);
+          await bridge.sendToolResult(toolResultPayload);
         }
         onLifecycleChangeRef.current?.({ status: "ready" });
       } catch (err) {
@@ -7756,6 +8480,7 @@ function ViewRendererBase({
       disposed = true;
       const toClose = bridge;
       bridgeRef.current = null;
+      onAppToolsChangedRef.current?.(null);
       if (!toClose) return;
       onLifecycleChangeRef.current?.({ status: "tearing-down" });
       void (async () => {
@@ -7778,7 +8503,7 @@ function ViewRendererBase({
     resolved,
     activeSandboxUrl,
     hostInfo,
-    hostCapabilities,
+    effectiveHostCapabilities,
     cspMode,
     viewId,
     wrapTransport,
@@ -7788,33 +8513,37 @@ function ViewRendererBase({
   useEffect5(() => {
     const bridge = bridgeRef.current;
     if (!bridge || initCount === 0 || !effectiveHostContext) return;
-    bridge.setHostContext(effectiveHostContext);
+    void bridge.setHostContext(effectiveHostContext);
   }, [effectiveHostContext, initCount]);
   useEffect5(() => {
     const bridge = bridgeRef.current;
-    if (!bridge || initCount === 0 || !partialToolInput) return;
-    bridge.sendToolInputPartial({ arguments: partialToolInput });
-  }, [initCount, partialToolInput]);
+    if (!bridge || initCount === 0 || !partialToolInput || toolOutput !== void 0 && toolOutput !== null) {
+      return;
+    }
+    void bridge.sendToolInputPartial({ arguments: partialToolInput });
+  }, [initCount, partialToolInput, toolOutput]);
   useEffect5(() => {
     const bridge = bridgeRef.current;
-    if (!bridge || initCount === 0 || partialToolInput) return;
+    if (!bridge || initCount === 0 || partialToolInput && (toolOutput === void 0 || toolOutput === null)) {
+      return;
+    }
     const mergedArgs = {
       ...toolInput,
       ...parseCustomProps(customProps)
     };
-    bridge.sendToolInput({ arguments: mergedArgs });
-  }, [initCount, toolInput, partialToolInput, customProps]);
+    void bridge.sendToolInput({ arguments: mergedArgs });
+  }, [initCount, toolInput, partialToolInput, customProps, toolOutput]);
   useEffect5(() => {
     const bridge = bridgeRef.current;
     if (!bridge || initCount === 0) return;
     const toolResultPayload = buildToolResultPayload(toolOutput, customProps);
     if (!toolResultPayload) return;
-    bridge.sendToolResult(toolResultPayload);
+    void bridge.sendToolResult(toolResultPayload);
   }, [initCount, toolOutput, customProps]);
   useEffect5(() => {
     const bridge = bridgeRef.current;
     if (!bridge || initCount === 0 || !cancelled) return;
-    bridge.sendToolCancelled({ reason: "Cancelled by user" });
+    void bridge.sendToolCancelled({ reason: "Cancelled by user" });
   }, [cancelled, initCount]);
   const readyFiredRef = useRef4(false);
   useEffect5(() => {
@@ -7822,11 +8551,6 @@ function ViewRendererBase({
     readyFiredRef.current = true;
     onReadyRef.current?.();
   }, [initCount]);
-  useEffect5(() => {
-    if (initCount === 0 || !showSpinner) return;
-    const timer = setTimeout(() => setShowSpinner(false), 300);
-    return () => clearTimeout(timer);
-  }, [initCount, showSpinner]);
   const showHostBorder = resolved !== null && resolved.prefersBorder && displayMode !== "fullscreen";
   if (loadError) {
     return /* @__PURE__ */ React2.createElement("div", { className }, /* @__PURE__ */ React2.createElement("div", { className: "border border-red-200/50 dark:border-red-800/50 bg-red-50/30 dark:bg-red-950/20 rounded-lg p-4" }, /* @__PURE__ */ React2.createElement("p", { className: "text-sm text-red-600 dark:text-red-400" }, "Failed to load view: ", loadError)));
@@ -7909,7 +8633,6 @@ function ViewRendererBase({
       {
         className: isFullscreen ? "relative flex min-h-0 w-full flex-1 flex-col" : isPip ? "relative w-full h-full min-h-0 flex flex-1 flex-col" : "relative w-full flex flex-1 justify-center items-center"
       },
-      showSpinner && /* @__PURE__ */ React2.createElement("div", { className: "flex absolute inset-0 items-center justify-center z-10" }, /* @__PURE__ */ React2.createElement("span", { className: "text-sm text-muted-foreground" }, "Loading\u2026")),
       !isPip && !isFullscreen && (invoking || invoked) && /* @__PURE__ */ React2.createElement("div", { className: "absolute -top-8 left-2 z-10 whitespace-nowrap pointer-events-none text-xs text-muted-foreground" }, invoking && !toolOutput ? invoking : invoked),
       /* @__PURE__ */ React2.createElement(
         "div",
@@ -7944,6 +8667,14 @@ function viewRendererAreEqual(prev, next) {
   if (prev.customProps !== next.customProps) return false;
   if (prev.hostContext !== next.hostContext) return false;
   if (prev.hostCapabilities !== next.hostCapabilities) return false;
+  if (prev.messageCapabilities !== next.messageCapabilities) return false;
+  if (prev.modelContextCapabilities !== next.modelContextCapabilities)
+    return false;
+  if (prev.onMessage !== next.onMessage) return false;
+  if (prev.onSamplingRequest !== next.onSamplingRequest) return false;
+  if (prev.onDownloadFile !== next.onDownloadFile) return false;
+  if (prev.onAppToolsChanged !== next.onAppToolsChanged) return false;
+  if (prev.onModelContextUpdate !== next.onModelContextUpdate) return false;
   if (prev.cspMode !== next.cspMode) return false;
   if (prev.mockOpenAiFileApis !== next.mockOpenAiFileApis) return false;
   if (prev.onInlineHeightChange !== next.onInlineHeightChange) return false;
@@ -7962,20 +8693,25 @@ export {
   Tel,
   Telemetry,
   ViewRenderer,
+  buildSandboxProxyBlobHtml,
   buildViewSandboxBlobUrl,
+  buildViewSandboxUrl,
   clearRpcLogs,
   detectFavicon,
   getAllRpcLogs,
   getRpcLogs,
   getViewResourceUri,
+  isToolVisibleToModel,
   isViewResource,
   isViewTool,
   onMcpAuthorization,
   parseCustomProps,
+  pickPersistedServerConfig,
   resolveViewResource,
   setTelemetrySource,
   specTypeSchemas,
   subscribeToRpcLogs,
+  toPersistedServerConfig,
   useMcp,
   useMcpClient,
   useMcpServer