@mastra/mcp 1.14.0 → 1.15.0-alpha.0

package/dist/index.js

@@ -10,8 +10,11 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { LoggingMessageNotificationSchema, ListRootsRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, EmptyResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ToolListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, ProgressNotificationSchema, ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ErrorCode, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, CallToolResultSchema, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { asyncExitHook, gracefulExit } from 'exit-hook';
-import { createHash, randomUUID } from 'crypto';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+export { UnauthorizedError, auth, buildDiscoveryUrls, discoverAuthorizationServerMetadata, discoverOAuthMetadata, discoverOAuthProtectedResourceMetadata, exchangeAuthorization, extractResourceMetadataUrl, parseErrorResponse, refreshAuthorization, registerClient, selectResourceURL, startAuthorization } from '@modelcontextprotocol/sdk/client/auth.js';
+import { createHash, randomUUID, timingSafeEqual } from 'crypto';
 import equal from 'fast-deep-equal';
+import { createServer } from 'http';
 import { MCPServerBase } from '@mastra/core/mcp';
 import { isStandardSchemaWithJSON as isStandardSchemaWithJSON$1, standardSchemaToJSONSchema } from '@mastra/core/schema';
 import { readFileSync } from 'fs';
@@ -22,7 +25,6 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-export { UnauthorizedError, auth, buildDiscoveryUrls, discoverAuthorizationServerMetadata, discoverOAuthMetadata, discoverOAuthProtectedResourceMetadata, exchangeAuthorization, extractResourceMetadataUrl, parseErrorResponse, refreshAuthorization, registerClient, selectResourceURL, startAuthorization } from '@modelcontextprotocol/sdk/client/auth.js';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -31076,6 +31078,44 @@ function getMastraToolStrictMeta(meta3) {
   const strict = mastraMeta[STRICT_META_KEY];
   return typeof strict === "boolean" ? strict : void 0;
 }
+function escapeHeaderValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function generateWWWAuthenticateHeader(options = {}) {
+  const params = [];
+  if (options.resourceMetadataUrl) {
+    params.push(`resource_metadata="${escapeHeaderValue(options.resourceMetadataUrl)}"`);
+  }
+  if (options.additionalParams) {
+    for (const [key, value] of Object.entries(options.additionalParams)) {
+      params.push(`${key}="${escapeHeaderValue(value)}"`);
+    }
+  }
+  if (params.length === 0) {
+    return "Bearer";
+  }
+  return `Bearer ${params.join(", ")}`;
+}
+function generateProtectedResourceMetadata(config2) {
+  return {
+    resource: config2.resource,
+    authorization_servers: config2.authorizationServers,
+    scopes_supported: config2.scopesSupported ?? ["mcp:read", "mcp:write"],
+    bearer_methods_supported: ["header"],
+    ...config2.resourceName && { resource_name: config2.resourceName },
+    ...config2.resourceDocumentation && {
+      resource_documentation: config2.resourceDocumentation
+    }
+  };
+}
+function extractBearerToken(authHeader) {
+  if (!authHeader) return void 0;
+  const prefix = "bearer ";
+  if (authHeader.length <= prefix.length) return void 0;
+  if (authHeader.slice(0, prefix.length).toLowerCase() !== prefix) return void 0;
+  const token = authHeader.slice(prefix.length).trim();
+  return token || void 0;
+}
 
 // src/client/actions/elicitation.ts
 var ElicitationClientActions = class {
@@ -31532,6 +31572,8 @@ var InternalMastraMCPClient = class extends MastraBase {
   enableProgressTracking;
   serverConfig;
   transport;
+  pendingAuthTransport;
+  _authState;
   operationContextStore = new AsyncLocalStorage();
   exitHookUnsubscribe;
   sigTermHandler;
@@ -31716,14 +31758,14 @@ var InternalMastraMCPClient = class extends MastraBase {
     this.log("debug", `Attempting to connect to URL: ${url2}`);
     let shouldTrySSE = url2.pathname.endsWith(`/sse`);
     if (!shouldTrySSE) {
+      const streamableTransport = new StreamableHTTPClientTransport(url2, {
+        requestInit,
+        reconnectionOptions: this.serverConfig.reconnectionOptions,
+        authProvider,
+        fetch: fetch2
+      });
       try {
         this.log("debug", "Trying Streamable HTTP transport...");
-        const streamableTransport = new StreamableHTTPClientTransport(url2, {
-          requestInit,
-          reconnectionOptions: this.serverConfig.reconnectionOptions,
-          authProvider,
-          fetch: fetch2
-        });
         await this.client.connect(streamableTransport, {
           timeout: connectTimeout ?? DEFAULT_SERVER_CONNECT_TIMEOUT_MSEC
         });
@@ -31731,6 +31773,10 @@ var InternalMastraMCPClient = class extends MastraBase {
         this.log("debug", "Successfully connected using Streamable HTTP transport.");
       } catch (error51) {
         this.log("debug", `Streamable HTTP transport failed: ${error51}`);
+        if (authProvider && error51 instanceof UnauthorizedError) {
+          this.markNeedsAuth(streamableTransport);
+          throw error51;
+        }
         const status = error51?.code;
         if (status !== void 0 && !SSE_FALLBACK_STATUS_CODES.includes(status)) {
           throw error51;
@@ -31740,18 +31786,22 @@ var InternalMastraMCPClient = class extends MastraBase {
     }
     if (shouldTrySSE) {
       this.log("debug", "Falling back to deprecated HTTP+SSE transport...");
+      const sseEventSourceInit = { ...eventSourceInit, fetch: eventSourceInit?.fetch ?? fetch2 };
+      const sseTransport = new SSEClientTransport(url2, {
+        requestInit,
+        eventSourceInit: sseEventSourceInit,
+        authProvider,
+        fetch: fetch2
+      });
       try {
-        const sseEventSourceInit = { ...eventSourceInit, fetch: fetch2 };
-        const sseTransport = new SSEClientTransport(url2, {
-          requestInit,
-          eventSourceInit: sseEventSourceInit,
-          authProvider,
-          fetch: fetch2
-        });
         await this.client.connect(sseTransport, { timeout: this.serverConfig.timeout ?? this.timeout });
         this.transport = sseTransport;
         this.log("debug", "Successfully connected using deprecated HTTP+SSE transport.");
       } catch (sseError) {
+        if (authProvider && sseError instanceof UnauthorizedError) {
+          this.markNeedsAuth(sseTransport);
+          throw sseError;
+        }
         this.log(
           "error",
           `Failed to connect with SSE transport after failing to connect to Streamable HTTP transport first. SSE error: ${sseError}`
@@ -31759,6 +31809,64 @@ var InternalMastraMCPClient = class extends MastraBase {
         throw new Error("Could not connect to server with any available HTTP transport");
       }
     }
+    this.closePendingAuthTransport();
+    if (authProvider) {
+      this._authState = "authorized";
+    }
+  }
+  /**
+   * Closes and clears any transport retained from an unfinished authorization
+   * flow. Safe to call when nothing is pending. Centralizes the cleanup so
+   * success, disconnect, and forceReconnect all release the same resource.
+   */
+  closePendingAuthTransport(replacement) {
+    const pending = this.pendingAuthTransport;
+    this.pendingAuthTransport = replacement;
+    if (pending && pending !== replacement) {
+      void pending.close().catch(() => {
+      });
+    }
+  }
+  /**
+   * Records that the server rejected the connection with a 401 and keeps the
+   * transport that started the authorization flow so finishAuth can complete it.
+   */
+  markNeedsAuth(transport) {
+    this.closePendingAuthTransport(transport);
+    this._authState = "needs-auth";
+    this.log("debug", "Server requires OAuth authorization before connecting.");
+  }
+  /**
+   * OAuth authorization state of this server connection, when it has an authProvider.
+   *
+   * @internal
+   */
+  get authState() {
+    return this._authState;
+  }
+  /**
+   * Completes a pending OAuth authorization-code flow.
+   *
+   * Exchanges the authorization code captured at the redirect URI on the same
+   * transport that started the flow, then leaves the client ready to connect().
+   *
+   * @param authorizationCode - The authorization code captured at the redirect URI
+   * @throws {Error} If no authorization flow is pending for this server
+   *
+   * @internal
+   */
+  async finishAuth(authorizationCode) {
+    const pending = this.pendingAuthTransport;
+    if (!pending) {
+      throw new Error("No OAuth authorization is pending for this server. Call connect() first.");
+    }
+    this.pendingAuthTransport = void 0;
+    try {
+      await pending.finishAuth(authorizationCode);
+    } finally {
+      void pending.close().catch(() => {
+      });
+    }
   }
   isConnected = null;
   /**
@@ -31869,6 +31977,7 @@ var InternalMastraMCPClient = class extends MastraBase {
     this.serverInstructions = this.client.getInstructions();
   }
   async disconnect() {
+    this.closePendingAuthTransport();
     if (!this.transport) {
       this.log("debug", "Disconnect called but no transport was connected.");
       return;
@@ -31913,6 +32022,7 @@ var InternalMastraMCPClient = class extends MastraBase {
    */
   async forceReconnect() {
     this.log("debug", "Forcing reconnection to MCP server...");
+    this.closePendingAuthTransport();
     try {
       if (this.transport) {
         await this.transport.close();
@@ -32191,6 +32301,399 @@ var InternalMastraMCPClient = class extends MastraBase {
     };
   }
 };
+var CALLBACK_PORT_FALLBACK_RANGE = 10;
+var DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60 * 1e3;
+var SUCCESS_HTML = `<!DOCTYPE html>
+<html>
+  <head><meta charset="utf-8"><title>Authentication complete</title></head>
+  <body style="font-family: system-ui, sans-serif; text-align: center; padding-top: 4rem;">
+    <h1>Authentication complete</h1>
+    <p>You can close this tab and return to your application.</p>
+  </body>
+</html>`;
+var ERROR_HTML = `<!DOCTYPE html>
+<html>
+  <head><meta charset="utf-8"><title>Authentication failed</title></head>
+  <body style="font-family: system-ui, sans-serif; text-align: center; padding-top: 4rem;">
+    <h1>Authentication failed</h1>
+    <p>You can close this tab and retry from your application.</p>
+  </body>
+</html>`;
+function getCallbackUrlCandidates(redirectUrl) {
+  const base = new URL(redirectUrl.toString());
+  const preferredPort = base.port ? Number(base.port) : base.protocol === "https:" ? 443 : 80;
+  const candidates = [];
+  for (let offset = 0; offset <= CALLBACK_PORT_FALLBACK_RANGE; offset++) {
+    const port = preferredPort + offset;
+    if (port > 65535) break;
+    const candidate = new URL(base.toString());
+    candidate.port = String(port);
+    candidates.push(candidate);
+  }
+  return candidates;
+}
+function stateMatches(receivedState, expectedState) {
+  const received = Buffer.from(receivedState);
+  const expected = Buffer.from(expectedState);
+  return received.length === expected.length && timingSafeEqual(received, expected);
+}
+function listen(server, port, hostname3) {
+  return new Promise((resolve, reject) => {
+    const onError = (error51) => {
+      server.off("listening", onListening);
+      if (error51.code === "EADDRINUSE") {
+        resolve(error51);
+      } else {
+        reject(error51);
+      }
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve(null);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, hostname3);
+  });
+}
+async function createOAuthCallbackServer(options) {
+  const candidates = getCallbackUrlCandidates(options.redirectUrl);
+  const callbackPath = candidates[0].pathname;
+  let settled = false;
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+  codePromise.catch(() => {
+  });
+  const settle = (outcome) => {
+    if (settled) return;
+    settled = true;
+    if ("result" in outcome) {
+      resolveCode(outcome.result);
+    } else {
+      rejectCode(outcome.error);
+    }
+  };
+  const server = createServer((req, res) => {
+    const url2 = new URL(req.url ?? "", "http://localhost");
+    if (url2.pathname !== callbackPath) {
+      res.statusCode = 404;
+      res.end("Not found");
+      return;
+    }
+    if (settled) {
+      res.statusCode = 410;
+      res.end("Callback already handled");
+      return;
+    }
+    const respond = (statusCode, html) => {
+      res.statusCode = statusCode;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(html);
+    };
+    const state = url2.searchParams.get("state");
+    if (state === null || !stateMatches(state, options.state)) {
+      respond(400, ERROR_HTML);
+      return;
+    }
+    const error51 = url2.searchParams.get("error");
+    if (error51) {
+      const description = url2.searchParams.get("error_description");
+      respond(400, ERROR_HTML);
+      settle({ error: new Error(`Authorization failed: ${error51}${description ? ` (${description})` : ""}`) });
+      return;
+    }
+    const code = url2.searchParams.get("code");
+    if (!code) {
+      respond(400, ERROR_HTML);
+      settle({ error: new Error("Authorization failed: missing authorization code") });
+      return;
+    }
+    respond(200, SUCCESS_HTML);
+    settle({ result: { code, state } });
+  });
+  const hostname3 = candidates[0].hostname.replace(/^\[|\]$/g, "");
+  let boundUrl;
+  let boundPort;
+  for (const candidate of candidates) {
+    const candidatePort = Number(candidate.port);
+    const error51 = await listen(server, candidatePort, hostname3);
+    if (!error51) {
+      boundUrl = candidate;
+      boundPort = candidatePort;
+      break;
+    }
+  }
+  if (!boundUrl || boundPort === void 0) {
+    const firstPort = Number(candidates[0].port);
+    const lastPort = Number(candidates[candidates.length - 1].port);
+    throw new Error(`Failed to start OAuth callback server: ports ${firstPort}-${lastPort} are all in use`);
+  }
+  server.on("error", (error51) => {
+    settle({ error: error51 instanceof Error ? error51 : new Error(String(error51)) });
+  });
+  return {
+    url: boundUrl,
+    port: boundPort,
+    waitForCode({ timeoutMs = DEFAULT_CALLBACK_TIMEOUT_MS } = {}) {
+      let timer;
+      const timeout = new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Timed out waiting for OAuth callback after ${timeoutMs}ms`)),
+          timeoutMs
+        );
+        timer.unref?.();
+      });
+      return Promise.race([codePromise, timeout]).finally(() => clearTimeout(timer));
+    },
+    close() {
+      settle({ error: new Error("OAuth callback server closed before receiving an authorization code") });
+      server.closeIdleConnections();
+      return new Promise((resolve, reject) => {
+        server.close((error51) => {
+          if (error51 && error51.code !== "ERR_SERVER_NOT_RUNNING") {
+            reject(error51);
+          } else {
+            resolve();
+          }
+        });
+      });
+    }
+  };
+}
+
+// src/client/oauth-provider.ts
+var InMemoryOAuthStorage = class {
+  data = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.data.set(key, value);
+  }
+  get(key) {
+    return this.data.get(key);
+  }
+  delete(key) {
+    this.data.delete(key);
+  }
+  clear() {
+    this.data.clear();
+  }
+};
+var MCPOAuthClientProvider = class {
+  _redirectUrl;
+  _clientMetadata;
+  storage;
+  onRedirect;
+  generateState;
+  _clientInfo;
+  _sessionState;
+  _sessionRedirectUrl;
+  constructor(options) {
+    this._redirectUrl = options.redirectUrl;
+    this._clientMetadata = options.clientMetadata;
+    this._clientInfo = options.clientInformation;
+    this.storage = options.storage ?? new InMemoryOAuthStorage();
+    this.onRedirect = options.onRedirectToAuthorization;
+    this.generateState = options.stateGenerator ?? (() => crypto.randomUUID());
+  }
+  /**
+   * The URL to redirect the user agent to after authorization.
+   */
+  get redirectUrl() {
+    return this._redirectUrl;
+  }
+  /**
+   * Metadata about this OAuth client.
+   */
+  get clientMetadata() {
+    return this._clientMetadata;
+  }
+  /**
+   * Returns a OAuth2 state parameter.
+   *
+   * While an authorization session is active (see beginAuthorizationSession),
+   * the pinned session state is returned so a callback server can validate
+   * the redirect against a known value.
+   */
+  async state() {
+    return this._sessionState ?? this.generateState();
+  }
+  /**
+   * Pins the OAuth state parameter for the next authorization request.
+   *
+   * Hosts driving an interactive authorization flow (e.g. MCPClient.authenticate)
+   * call this before triggering the flow so the loopback callback server knows
+   * which state value to expect. Call endAuthorizationSession once the flow settles.
+   *
+   * @returns The pinned state value, generated with the configured stateGenerator
+   */
+  async beginAuthorizationSession() {
+    this._sessionState = await this.generateState();
+    this._sessionRedirectUrl = this._redirectUrl;
+    return this._sessionState;
+  }
+  /**
+   * Clears the pinned authorization state (see beginAuthorizationSession) and
+   * restores the configured redirect URL if applyResolvedRedirectUrl rebased
+   * it to a fallback port during the session, so the next flow starts from
+   * the preferred port again.
+   */
+  endAuthorizationSession() {
+    this._sessionState = void 0;
+    if (this._sessionRedirectUrl !== void 0) {
+      this._redirectUrl = this._sessionRedirectUrl;
+      this._sessionRedirectUrl = void 0;
+    }
+  }
+  /**
+   * Points the provider at the callback URL that is actually bound.
+   *
+   * Loopback callback servers may bind a fallback port when the preferred one
+   * is in use. Call this before triggering authorization so the authorization
+   * request's redirect_uri matches the listening server, and so dynamic client
+   * registration registers every candidate callback URL (see
+   * getCallbackUrlCandidates) rather than only the preferred one.
+   *
+   * @param redirectUrl - The callback URL that is actually bound
+   * @param registeredRedirectUris - The redirect URIs to register during dynamic client registration
+   */
+  applyResolvedRedirectUrl(redirectUrl, registeredRedirectUris) {
+    this._redirectUrl = redirectUrl;
+    this._clientMetadata = {
+      ...this._clientMetadata,
+      redirect_uris: registeredRedirectUris.map((uri) => uri.toString())
+    };
+  }
+  /**
+   * Loads information about this OAuth client.
+   */
+  async clientInformation() {
+    if (this._clientInfo) {
+      return this._clientInfo;
+    }
+    const stored = await this.storage.get("client_info");
+    if (stored) {
+      try {
+        return JSON.parse(stored);
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Saves dynamically registered client information.
+   */
+  async saveClientInformation(clientInformation) {
+    this._clientInfo = clientInformation;
+    await this.storage.set("client_info", JSON.stringify(clientInformation));
+  }
+  /**
+   * Loads existing OAuth tokens.
+   */
+  async tokens() {
+    const stored = await this.storage.get("tokens");
+    if (stored) {
+      try {
+        return JSON.parse(stored);
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Stores new OAuth tokens after successful authorization.
+   */
+  async saveTokens(tokens) {
+    await this.storage.set("tokens", JSON.stringify(tokens));
+  }
+  /**
+   * Invoked to redirect the user agent to the authorization URL.
+   */
+  async redirectToAuthorization(authorizationUrl) {
+    if (this.onRedirect) {
+      await this.onRedirect(authorizationUrl);
+    } else {
+      console.info(`Authorization required. Please visit: ${authorizationUrl.toString()}`);
+    }
+  }
+  /**
+   * Saves a PKCE code verifier before redirecting to authorization.
+   */
+  async saveCodeVerifier(codeVerifier) {
+    await this.storage.set("code_verifier", codeVerifier);
+  }
+  /**
+   * Loads the PKCE code verifier for validating authorization result.
+   */
+  async codeVerifier() {
+    const verifier = await this.storage.get("code_verifier");
+    if (!verifier) {
+      throw new Error("No code verifier found. Authorization flow may not have started properly.");
+    }
+    return verifier;
+  }
+  /**
+   * Invalidate credentials when server indicates they're no longer valid.
+   */
+  async invalidateCredentials(scope) {
+    switch (scope) {
+      case "all":
+        await this.storage.delete("tokens");
+        await this.storage.delete("client_info");
+        await this.storage.delete("code_verifier");
+        this._clientInfo = void 0;
+        break;
+      case "client":
+        await this.storage.delete("client_info");
+        this._clientInfo = void 0;
+        break;
+      case "tokens":
+        await this.storage.delete("tokens");
+        break;
+      case "verifier":
+        await this.storage.delete("code_verifier");
+        break;
+    }
+  }
+  /**
+   * Clear all stored OAuth data.
+   * Useful for logging out or resetting state.
+   */
+  async clear() {
+    await this.invalidateCredentials("all");
+  }
+  /**
+   * Check if the provider has valid (non-expired) tokens.
+   */
+  async hasValidTokens() {
+    const currentTokens = await this.tokens();
+    if (!currentTokens) return false;
+    if (!currentTokens.access_token) return false;
+    return true;
+  }
+};
+function createSimpleTokenProvider(accessToken, options) {
+  const tokens = {
+    access_token: accessToken,
+    token_type: options.tokenType ?? "Bearer",
+    refresh_token: options.refreshToken,
+    expires_in: options.expiresIn,
+    scope: options.scope
+  };
+  const storage = new InMemoryOAuthStorage();
+  storage.set("tokens", JSON.stringify(tokens));
+  if (options.clientInformation) {
+    storage.set("client_info", JSON.stringify(options.clientInformation));
+  }
+  return new MCPOAuthClientProvider({
+    redirectUrl: options.redirectUrl,
+    clientMetadata: options.clientMetadata,
+    clientInformation: options.clientInformation,
+    storage
+  });
+}
 var MCPClientServerProxy = class extends MCPServerBase {
   clientGetter;
   cachedClient = null;
@@ -32330,12 +32833,25 @@ var MCPClientServerProxy = class extends MCPServerBase {
 // src/client/configuration.ts
 var mcpClientInstances = /* @__PURE__ */ new Map();
 var TOOL_DISCOVERY_MAX_ATTEMPTS = 2;
+var LOOPBACK_IPV4 = /^127\.(?:\d{1,3})\.(?:\d{1,3})\.(?:\d{1,3})$/;
+function isLoopbackHostname(hostname3) {
+  return hostname3 === "localhost" || hostname3 === "[::1]" || hostname3 === "::1" || LOOPBACK_IPV4.test(hostname3);
+}
 var MCPClient = class extends MastraBase {
   serverConfigs = {};
   id;
   defaultTimeout;
   mcpClientsById = /* @__PURE__ */ new Map();
   disconnectPromise = null;
+  authFlowsByServer = /* @__PURE__ */ new Map();
+  authCallbackServersByServer = /* @__PURE__ */ new Map();
+  /**
+   * Per-server abort controllers for in-flight authorization flows. Created
+   * synchronously at the start of {@link runAuthorizationFlow} — before the
+   * callback server exists — so cancel/disconnect can interrupt the setup phase
+   * (discovery, registration, port binding) and not just the waitForCode wait.
+   */
+  authAbortControllersByServer = /* @__PURE__ */ new Map();
   /**
    * Creates a new MCPClient instance for managing MCP server connections.
    *
@@ -32995,6 +33511,17 @@ To fix this you have three different options:
     this.disconnectPromise = (async () => {
       try {
         mcpClientInstances.delete(this.id);
+        const pendingFlows = Array.from(this.authFlowsByServer.values());
+        for (const controller of this.authAbortControllersByServer.values()) {
+          controller.abort();
+        }
+        await Promise.allSettled(
+          Array.from(this.authCallbackServersByServer.values()).map((server) => server.close())
+        );
+        await Promise.allSettled(pendingFlows);
+        this.authAbortControllersByServer.clear();
+        this.authCallbackServersByServer.clear();
+        this.authFlowsByServer.clear();
         await Promise.allSettled(Array.from(this.mcpClientsById.values()).map((client) => client.disconnect()));
         this.mcpClientsById.clear();
       } finally {
@@ -33026,6 +33553,151 @@ To fix this you have three different options:
       await this.getConnectedClientForServer(serverName);
     }
   }
+  /**
+   * Runs the interactive OAuth authorization-code flow for a server.
+   *
+   * Requires the server to be configured with an MCPOAuthClientProvider whose
+   * redirect URL points at a loopback address. The flow:
+   *
+   * 1. Starts a loopback callback server on the redirect URL's port (falling
+   *    back to the next sequential ports when it is in use)
+   * 2. Attempts a connection so the SDK runs discovery and dynamic client
+   *    registration, delivering the authorization URL through the provider's
+   *    `onRedirectToAuthorization` callback — the host directs the user there
+   * 3. Waits for the browser to deliver the authorization code, validates the
+   *    OAuth state, exchanges the code for tokens, and reconnects
+   *
+   * Concurrent calls for the same server join the pending flow (the joiner's
+   * options are ignored — the pending flow keeps its own timeout); different
+   * servers authenticate independently. Each server needs its own provider
+   * instance: the flow pins session state on the provider, so sharing one
+   * MCPOAuthClientProvider across servers is not supported. Hosts with custom
+   * redirect handling (e.g. a web app with an HTTPS redirect URL) should
+   * drive MCPOAuthClientProvider directly instead.
+   *
+   * @param serverName - The name of the server to authenticate (must match a key in `servers`)
+   * @param options.timeoutMs - How long to wait for the browser callback (default 5 minutes)
+   * @throws {Error} If the server has no MCPOAuthClientProvider or its redirect URL is not loopback
+   *
+   * @example
+   * ```typescript
+   * if (mcp.getServerAuthState('weatherServer') === 'needs-auth') {
+   *   await mcp.authenticate('weatherServer');
+   * }
+   * ```
+   */
+  async authenticate(serverName, options) {
+    if (this.disconnectPromise) {
+      await this.disconnectPromise.catch(() => {
+      });
+    }
+    const pendingFlow = this.authFlowsByServer.get(serverName);
+    if (pendingFlow) {
+      return pendingFlow;
+    }
+    const flow = this.runAuthorizationFlow(serverName, options).finally(() => {
+      this.authFlowsByServer.delete(serverName);
+    });
+    this.authFlowsByServer.set(serverName, flow);
+    return flow;
+  }
+  /**
+   * OAuth authorization state of a configured server.
+   *
+   * Returns `undefined` for servers without an authProvider and for servers
+   * that have not attempted a connection yet.
+   */
+  getServerAuthState(serverName) {
+    return this.mcpClientsById.get(serverName)?.authState;
+  }
+  async runAuthorizationFlow(serverName, options) {
+    const abortController = new AbortController();
+    this.authAbortControllersByServer.set(serverName, abortController);
+    const throwIfAborted = () => {
+      if (abortController.signal.aborted) {
+        throw new Error(`Authentication for MCP server ${serverName} was cancelled.`);
+      }
+    };
+    let provider;
+    let sessionStarted = false;
+    let callbackServer;
+    try {
+      const config2 = this.getServerConfig(serverName);
+      const candidateProvider = config2.authProvider;
+      if (!(candidateProvider instanceof MCPOAuthClientProvider)) {
+        throw new Error(
+          `Cannot authenticate MCP server ${serverName}: it is not configured with an MCPOAuthClientProvider.`
+        );
+      }
+      provider = candidateProvider;
+      const redirectUrl = new URL(provider.redirectUrl.toString());
+      if (redirectUrl.protocol !== "http:" || !isLoopbackHostname(redirectUrl.hostname)) {
+        throw new Error(
+          `Cannot authenticate MCP server ${serverName}: the provider's redirect URL must be a loopback address, got ${redirectUrl.origin}.`
+        );
+      }
+      const state = await provider.beginAuthorizationSession();
+      sessionStarted = true;
+      throwIfAborted();
+      callbackServer = await createOAuthCallbackServer({ redirectUrl, state });
+      throwIfAborted();
+      this.authCallbackServersByServer.set(serverName, callbackServer);
+      provider.applyResolvedRedirectUrl(callbackServer.url, getCallbackUrlCandidates(redirectUrl));
+      const clientInfo = await provider.clientInformation();
+      if (clientInfo?.redirect_uris && !clientInfo.redirect_uris.includes(callbackServer.url.toString())) {
+        await provider.invalidateCredentials("client");
+      }
+      const client = await this.getClientForServer(serverName);
+      try {
+        await client.connect();
+        return;
+      } catch (error51) {
+        if (!(error51 instanceof UnauthorizedError)) {
+          throw this.handleConnectError(serverName, error51);
+        }
+      }
+      const { code } = await callbackServer.waitForCode(options);
+      await client.finishAuth(code);
+      try {
+        await client.connect();
+      } catch (error51) {
+        throw error51 instanceof UnauthorizedError ? error51 : this.handleConnectError(serverName, error51);
+      }
+    } finally {
+      this.authCallbackServersByServer.delete(serverName);
+      this.authAbortControllersByServer.delete(serverName);
+      if (sessionStarted) {
+        provider?.endAuthorizationSession();
+      }
+      await callbackServer?.close();
+    }
+  }
+  /**
+   * Cancels a pending {@link authenticate} flow for a server.
+   *
+   * Tears down the loopback callback server immediately — the pending
+   * authenticate() call rejects. Useful when the user closed the browser
+   * without completing consent, which the host cannot observe.
+   *
+   * The resulting auth state depends on how far the flow had progressed: a flow
+   * cancelled after the server rejected the connection with a 401 stays in the
+   * `needs-auth` state so it can be retried right away, while a flow cancelled
+   * during the setup phase (before any connection was attempted) leaves the
+   * state unchanged — typically `undefined`.
+   *
+   * @param serverName - The name of the server whose flow to cancel
+   * @returns `true` if a pending flow was cancelled, `false` when no flow was pending
+   */
+  async cancelAuthentication(serverName) {
+    const pendingFlow = this.authFlowsByServer.get(serverName);
+    if (!pendingFlow) {
+      return false;
+    }
+    this.authAbortControllersByServer.get(serverName)?.abort();
+    await this.authCallbackServersByServer.get(serverName)?.close();
+    await pendingFlow.catch(() => void 0);
+    return true;
+  }
   /**
    * Returns instructions advertised by connected MCP servers during initialize.
    *
@@ -33311,7 +33983,9 @@ To fix this you have three different options:
     );
     this.logger.trackException(mastraError);
     this.logger.error("MCPClient errored connecting to MCP server:", { error: mastraError.toString() });
-    this.mcpClientsById.delete(name);
+    if (!(error51 instanceof UnauthorizedError)) {
+      this.mcpClientsById.delete(name);
+    }
     return mastraError;
   }
   async getConnectedClientForServer(serverName) {
@@ -33342,184 +34016,6 @@ To fix this you have three different options:
   }
 };
 
-// src/client/oauth-provider.ts
-var InMemoryOAuthStorage = class {
-  data = /* @__PURE__ */ new Map();
-  set(key, value) {
-    this.data.set(key, value);
-  }
-  get(key) {
-    return this.data.get(key);
-  }
-  delete(key) {
-    this.data.delete(key);
-  }
-  clear() {
-    this.data.clear();
-  }
-};
-var MCPOAuthClientProvider = class {
-  _redirectUrl;
-  _clientMetadata;
-  storage;
-  onRedirect;
-  generateState;
-  _clientInfo;
-  constructor(options) {
-    this._redirectUrl = options.redirectUrl;
-    this._clientMetadata = options.clientMetadata;
-    this._clientInfo = options.clientInformation;
-    this.storage = options.storage ?? new InMemoryOAuthStorage();
-    this.onRedirect = options.onRedirectToAuthorization;
-    this.generateState = options.stateGenerator ?? (() => crypto.randomUUID());
-  }
-  /**
-   * The URL to redirect the user agent to after authorization.
-   */
-  get redirectUrl() {
-    return this._redirectUrl;
-  }
-  /**
-   * Metadata about this OAuth client.
-   */
-  get clientMetadata() {
-    return this._clientMetadata;
-  }
-  /**
-   * Returns a OAuth2 state parameter.
-   */
-  async state() {
-    return this.generateState();
-  }
-  /**
-   * Loads information about this OAuth client.
-   */
-  async clientInformation() {
-    if (this._clientInfo) {
-      return this._clientInfo;
-    }
-    const stored = await this.storage.get("client_info");
-    if (stored) {
-      try {
-        return JSON.parse(stored);
-      } catch {
-      }
-    }
-    return void 0;
-  }
-  /**
-   * Saves dynamically registered client information.
-   */
-  async saveClientInformation(clientInformation) {
-    this._clientInfo = clientInformation;
-    await this.storage.set("client_info", JSON.stringify(clientInformation));
-  }
-  /**
-   * Loads existing OAuth tokens.
-   */
-  async tokens() {
-    const stored = await this.storage.get("tokens");
-    if (stored) {
-      try {
-        return JSON.parse(stored);
-      } catch {
-      }
-    }
-    return void 0;
-  }
-  /**
-   * Stores new OAuth tokens after successful authorization.
-   */
-  async saveTokens(tokens) {
-    await this.storage.set("tokens", JSON.stringify(tokens));
-  }
-  /**
-   * Invoked to redirect the user agent to the authorization URL.
-   */
-  async redirectToAuthorization(authorizationUrl) {
-    if (this.onRedirect) {
-      await this.onRedirect(authorizationUrl);
-    } else {
-      console.info(`Authorization required. Please visit: ${authorizationUrl.toString()}`);
-    }
-  }
-  /**
-   * Saves a PKCE code verifier before redirecting to authorization.
-   */
-  async saveCodeVerifier(codeVerifier) {
-    await this.storage.set("code_verifier", codeVerifier);
-  }
-  /**
-   * Loads the PKCE code verifier for validating authorization result.
-   */
-  async codeVerifier() {
-    const verifier = await this.storage.get("code_verifier");
-    if (!verifier) {
-      throw new Error("No code verifier found. Authorization flow may not have started properly.");
-    }
-    return verifier;
-  }
-  /**
-   * Invalidate credentials when server indicates they're no longer valid.
-   */
-  async invalidateCredentials(scope) {
-    switch (scope) {
-      case "all":
-        await this.storage.delete("tokens");
-        await this.storage.delete("client_info");
-        await this.storage.delete("code_verifier");
-        this._clientInfo = void 0;
-        break;
-      case "client":
-        await this.storage.delete("client_info");
-        this._clientInfo = void 0;
-        break;
-      case "tokens":
-        await this.storage.delete("tokens");
-        break;
-      case "verifier":
-        await this.storage.delete("code_verifier");
-        break;
-    }
-  }
-  /**
-   * Clear all stored OAuth data.
-   * Useful for logging out or resetting state.
-   */
-  async clear() {
-    await this.invalidateCredentials("all");
-  }
-  /**
-   * Check if the provider has valid (non-expired) tokens.
-   */
-  async hasValidTokens() {
-    const currentTokens = await this.tokens();
-    if (!currentTokens) return false;
-    if (!currentTokens.access_token) return false;
-    return true;
-  }
-};
-function createSimpleTokenProvider(accessToken, options) {
-  const tokens = {
-    access_token: accessToken,
-    token_type: options.tokenType ?? "Bearer",
-    refresh_token: options.refreshToken,
-    expires_in: options.expiresIn,
-    scope: options.scope
-  };
-  const storage = new InMemoryOAuthStorage();
-  storage.set("tokens", JSON.stringify(tokens));
-  if (options.clientInformation) {
-    storage.set("client_info", JSON.stringify(options.clientInformation));
-  }
-  return new MCPOAuthClientProvider({
-    redirectUrl: options.redirectUrl,
-    clientMetadata: options.clientMetadata,
-    clientInformation: options.clientInformation,
-    storage
-  });
-}
-
 // ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/hono/4.12.30/1b2e4fcdfb5fc9f7f51bffc1540f859608c39e01fb7d73d8ab30d60a680eaffc/node_modules/hono/dist/utils/stream.js
 var StreamingApi = class {
   writer;
@@ -36208,44 +36704,6 @@ Provided arguments: ${JSON.stringify(args, null, 2)}`,
     return { resources };
   }
 };
-function escapeHeaderValue(value) {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-function generateWWWAuthenticateHeader(options = {}) {
-  const params = [];
-  if (options.resourceMetadataUrl) {
-    params.push(`resource_metadata="${escapeHeaderValue(options.resourceMetadataUrl)}"`);
-  }
-  if (options.additionalParams) {
-    for (const [key, value] of Object.entries(options.additionalParams)) {
-      params.push(`${key}="${escapeHeaderValue(value)}"`);
-    }
-  }
-  if (params.length === 0) {
-    return "Bearer";
-  }
-  return `Bearer ${params.join(", ")}`;
-}
-function generateProtectedResourceMetadata(config2) {
-  return {
-    resource: config2.resource,
-    authorization_servers: config2.authorizationServers,
-    scopes_supported: config2.scopesSupported ?? ["mcp:read", "mcp:write"],
-    bearer_methods_supported: ["header"],
-    ...config2.resourceName && { resource_name: config2.resourceName },
-    ...config2.resourceDocumentation && {
-      resource_documentation: config2.resourceDocumentation
-    }
-  };
-}
-function extractBearerToken(authHeader) {
-  if (!authHeader) return void 0;
-  const prefix = "bearer ";
-  if (authHeader.length <= prefix.length) return void 0;
-  if (authHeader.slice(0, prefix.length).toLowerCase() !== prefix) return void 0;
-  const token = authHeader.slice(prefix.length).trim();
-  return token || void 0;
-}
 
 // src/server/oauth-middleware.ts
 function createOAuthMiddleware(options) {
@@ -36412,6 +36870,6 @@ function createIntrospectionValidator(introspectionEndpoint, clientCredentials)
   };
 }
 
-export { InMemoryOAuthStorage, InternalMastraMCPClient, MCPClient, MCPClientServerProxy, MCPOAuthClientProvider, MCPServer, createIntrospectionValidator, createOAuthMiddleware, createSimpleTokenProvider, createStaticTokenValidator, extractBearerToken, generateProtectedResourceMetadata, generateWWWAuthenticateHeader };
+export { InMemoryOAuthStorage, InternalMastraMCPClient, MCPClient, MCPClientServerProxy, MCPOAuthClientProvider, MCPServer, createIntrospectionValidator, createOAuthCallbackServer, createOAuthMiddleware, createSimpleTokenProvider, createStaticTokenValidator, extractBearerToken, generateProtectedResourceMetadata, generateWWWAuthenticateHeader, getCallbackUrlCandidates };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map