Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

119 KB
Raw Blame
import { isIP } from 'node:net';
import { EventEmitter } from 'events';
import { logger } from '@librechat/data-schemas';
import { MCP_UI_EXTENSION_ID } from 'librechat-data-provider';
import { fetch as undiciFetch, Agent, ProxyAgent } from 'undici';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import {
  StdioClientTransport,
  getDefaultEnvironment,
} from '@modelcontextprotocol/sdk/client/stdio.js';
import {
  ResourceListChangedNotificationSchema,
  ToolListChangedNotificationSchema,
} from '@modelcontextprotocol/sdk/types.js';
import type {
  RequestInit as UndiciRequestInit,
  RequestInfo as UndiciRequestInfo,
  Response as UndiciResponse,
  Dispatcher,
} from 'undici';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
import type { TMCPAppOperationLimits } from 'librechat-data-provider';
import type { MCPClientCapabilityProfile } from './capabilities';
import type { MCPRequestScopeRunner } from './signal';
import type { MCPOAuthTokens } from './oauth/types';
import type * as t from './types';
import {
  extractSSEErrorMessage,
  isOAuthAuthenticationError,
  isMCPTransportAuthenticationError,
  MCPTransportAuthenticationError,
  isStandaloneSseConflict,
  isMCPInitializationError,
} from './errors';
import {
  withMCPRequestSignal,
  getMCPDispatchSignal,
  holdMCPRequestFailure,
  outsideMCPRequestScope,
  captureMCPRequestScope,
} from './signal';
import {
  createMCPAppSSEEventGuard,
  getMCPAppOperationLimits,
  guardMCPAppSSEEvents,
} from './apps/budget';
import { MCP_APPS_CAPABILITY_PROFILE, STANDARD_MCP_CAPABILITY_PROFILE } from './capabilities';
import { createSSRFSafeUndiciConnect, isSSRFTarget, resolveHostnameSSRF } from '~/auth';
import { projectMCPAppRuntimeTarget, type MCPAppRuntimeTarget } from './apps/binding';
import { assertToolApprovalTransportEpoch } from '~/tools/approval';
import { reserveMCPToolsChangedRevision } from './toolsChanged';
import { runOutsideTracing } from '~/utils/tracing';
import { MCPRequestQuiescedError } from './request';
import { isOwnedAbortError } from '~/utils/errors';
import { mediaTypeEssence } from '~/utils/headers';
import { isAddressAllowed } from '~/auth/domain';
import { awaitOboOperation } from './oauth/obo';
import { withTimeout } from '~/utils/promise';
import { RESOURCE_MIME_TYPE } from './apps';
import { isOAuthServer } from './utils';
import { mcpConfig } from './mcpConfig';

type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;
type ManagedDispatcher = Agent | ProxyAgent;
type ParsedIP = { version: 4 | 6; bits: 32 | 128; value: bigint };
type MCPTool = MCPListToolsResult['tools'][number];

const BIGINT_ZERO = BigInt(0);
const BIGINT_ONE = BigInt(1);
const BIGINT_EIGHT = BigInt(8);
const BIGINT_SIXTEEN = BigInt(16);
const UINT16_MASK = BigInt(0xffff);

function getApproximateToolBytes(tool: MCPTool): number {
  try {
    return Buffer.byteLength(JSON.stringify(tool), 'utf8');
  } catch {
    return Number.POSITIVE_INFINITY;
  }
}

function getToolsListBudgetExceededReason(
  toolCount: number,
  totalBytes: number,
  maxTools: number,
  maxBytes: number,
): string | null {
  if (toolCount >= maxTools) {
    return 'tool count';
  }
  if (totalBytes >= maxBytes) {
    return 'size';
  }
  return null;
}

type MCPProxyConfig =
  | {
      type: 'explicit';
      proxyUrl: string;
    }
  | {
      type: 'env';
      httpProxy?: string;
      httpsProxy?: string;
      noProxy?: string;
    };

function isStdioOptions(options: t.MCPOptions): options is t.StdioOptions {
  return 'command' in options;
}

function isWebSocketOptions(options: t.MCPOptions): options is t.WebSocketOptions {
  if ('url' in options) {
    const protocol = new URL(options.url).protocol;
    return protocol === 'ws:' || protocol === 'wss:';
  }
  return false;
}

function isSSEOptions(options: t.MCPOptions): options is t.SSEOptions {
  if ('url' in options) {
    const protocol = new URL(options.url).protocol;
    return protocol !== 'ws:' && protocol !== 'wss:';
  }
  return false;
}

/**
 * Checks if the provided options are for a Streamable HTTP transport.
 *
 * Streamable HTTP is an MCP transport that uses HTTP POST for sending messages
 * and supports streaming responses. It provides better performance than
 * SSE transport while maintaining compatibility with most network environments.
 *
 * @param options MCP connection options to check
 * @returns True if options are for a streamable HTTP transport
 */
function isStreamableHTTPOptions(options: t.MCPOptions): options is t.StreamableHTTPOptions {
  if ('url' in options && 'type' in options) {
    const optionType = options.type as string;
    if (optionType === 'streamable-http' || optionType === 'http') {
      const protocol = new URL(options.url).protocol;
      return protocol !== 'ws:' && protocol !== 'wss:';
    }
  }
  return false;
}

const FIVE_MINUTES = 5 * 60 * 1000;
const DEFAULT_TIMEOUT = 60000;
/** SSE connections through proxies may need longer initial handshake time */
const SSE_CONNECT_TIMEOUT = 120000;
const DEFAULT_INIT_TIMEOUT = 30000;
/** Upper bound on the spec-mandated Streamable HTTP session DELETE so teardown never blocks on a hung server */
const SESSION_TERMINATION_TIMEOUT = 5000;
const TOOL_LIST_REFRESH_RETRY_BASE_MS = 250;
const TOOL_LIST_REFRESH_RETRY_MAX_MS = 30_000;
/** Max 307/308 redirects to follow per request (prevents redirect loops) */
const MAX_REDIRECTS = 5;
/**
 * `createFetchFunction` is the only redirect authority (SSRF checks, the hop cap, cross-origin
 * credential stripping, no tool-call replay). `'follow'` leaves redirects to that fetch, so the
 * SDK's own same-origin follower cannot re-issue a request it declined.
 */
const SDK_REDIRECT_POLICY = 'follow' as const;
const DEFAULT_MCP_STREAMABLE_HTTP_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
const DEFAULT_MCP_STREAMABLE_HTTP_MAX_LINE_BYTES = 5 * 1024 * 1024;

function getNonNegativeIntegerEnv(name: string, defaultValue: number): number {
  const raw = process.env[name];
  if (raw == null || raw.trim() === '') {
    return defaultValue;
  }

  const trimmed = raw.trim();
  if (!/^\d+$/.test(trimmed)) {
    return defaultValue;
  }

  const parsed = Number(trimmed);
  return Number.isSafeInteger(parsed) ? parsed : defaultValue;
}

function bytesToMiB(bytes: number): string {
  return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
}

function getMemoryDebugSnapshot(): Record<string, string> {
  const mem = process.memoryUsage();
  return {
    rss: bytesToMiB(mem.rss),
    heapUsed: bytesToMiB(mem.heapUsed),
    heapTotal: bytesToMiB(mem.heapTotal),
    external: bytesToMiB(mem.external),
    arrayBuffers: bytesToMiB(mem.arrayBuffers ?? 0),
  };
}

const textEncoder = new TextEncoder();
const textDecoder = new TextDecoder();
type JSONRPCRequestId = string | number;

function getChunkBytes(chunk: unknown): Uint8Array {
  if (typeof chunk === 'string') {
    return textEncoder.encode(chunk);
  }
  if (chunk instanceof ArrayBuffer) {
    return new Uint8Array(chunk);
  }
  if (ArrayBuffer.isView(chunk)) {
    const view = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
    return new Uint8Array(view);
  }
  return new Uint8Array();
}

function copyBytes(bytes: Uint8Array): Uint8Array {
  const copy = new Uint8Array(bytes.byteLength);
  copy.set(bytes);
  return copy;
}

function concatBytes(chunks: Uint8Array[]): Uint8Array {
  if (chunks.length === 0) {
    return new Uint8Array();
  }
  if (chunks.length === 1) {
    return chunks[0];
  }
  const totalLength = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
  const combined = new Uint8Array(totalLength);
  let offset = 0;
  for (const chunk of chunks) {
    combined.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return combined;
}

function getBodyText(body: unknown): string | null {
  if (typeof body === 'string') {
    return body;
  }
  if (body instanceof ArrayBuffer) {
    return textDecoder.decode(new Uint8Array(body));
  }
  if (ArrayBuffer.isView(body)) {
    return textDecoder.decode(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
  }
  return null;
}

function containsToolInvocation(body: unknown): boolean {
  const text = getBodyText(body);
  if (!text) return false;
  try {
    const value: unknown = JSON.parse(text);
    const messages: unknown[] = Array.isArray(value) ? value : [value];
    return messages.some(
      (message) =>
        message != null &&
        typeof message === 'object' &&
        'method' in message &&
        message.method === 'tools/call',
    );
  } catch {
    return false;
  }
}

function getJSONRPCRequestIds(body: unknown): JSONRPCRequestId[] {
  const bodyText = getBodyText(body);
  if (!bodyText) {
    return [];
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(bodyText);
  } catch {
    return [];
  }

  const messages = Array.isArray(parsed) ? parsed : [parsed];
  return messages.flatMap((message) => {
    if (!message || typeof message !== 'object') {
      return [];
    }
    const jsonrpcMessage = message as { id?: unknown; method?: unknown };
    const { id } = jsonrpcMessage;
    if (typeof jsonrpcMessage.method !== 'string') {
      return [];
    }
    if (typeof id !== 'string' && typeof id !== 'number') {
      return [];
    }
    return [id];
  });
}

function buildBlockedMCPResponseMessage(
  reason: string,
  details: {
    maxResponseBytes: number;
    maxLineBytes: number;
    totalBytes: number;
    currentLineBytes: number;
    chunkCount: number;
  },
): string {
  const limitDetails =
    reason === 'MCP response exceeded byte limit'
      ? `limit=${details.maxResponseBytes} bytes, observed=${details.totalBytes} bytes`
      : `lineLimit=${details.maxLineBytes} bytes, observedLine=${details.currentLineBytes} bytes, observedTotal=${details.totalBytes} bytes`;

  return `[MCP] ${reason} (${limitDetails}, chunks=${details.chunkCount}). The MCP server returned an unsafe streamable HTTP response; narrow the tool result or retry after the server response is fixed.`;
}

function buildBlockedMCPResponseSSE(requestIds: JSONRPCRequestId[], message: string): Uint8Array {
  const events = requestIds
    .map((id) => {
      const payload = {
        jsonrpc: '2.0',
        id,
        error: {
          code: -32000,
          message,
        },
      };
      return `data: ${JSON.stringify(payload)}\n\n`;
    })
    .join('');
  return textEncoder.encode(events);
}

function getMCPStreamableHTTPResponseLimits(
  appProfile = false,
  operationLimits?: TMCPAppOperationLimits,
): {
  maxResponseBytes: number;
  maxLineBytes: number;
} {
  if (appProfile) {
    // Validated App-profile policy owns both bounds. Generic transport env defaults are for
    // standard sessions and must not silently reject an operator-approved larger App event.
    const maxBytes = getMCPAppOperationLimits(operationLimits).maxBytes;
    return { maxResponseBytes: maxBytes, maxLineBytes: maxBytes };
  }
  return {
    maxResponseBytes: getNonNegativeIntegerEnv(
      'MCP_STREAMABLE_HTTP_MAX_RESPONSE_BYTES',
      DEFAULT_MCP_STREAMABLE_HTTP_MAX_RESPONSE_BYTES,
    ),
    maxLineBytes: getNonNegativeIntegerEnv(
      'MCP_STREAMABLE_HTTP_MAX_LINE_BYTES',
      DEFAULT_MCP_STREAMABLE_HTTP_MAX_LINE_BYTES,
    ),
  };
}

async function guardMCPStreamableHTTPResponse(
  response: UndiciResponse,
  context: {
    logPrefix: string;
    method: string;
    url: string;
    requestIds?: JSONRPCRequestId[];
    appProfile?: boolean;
    operationLimits?: TMCPAppOperationLimits;
    onAppSSEOverflow?: () => void;
  },
): Promise<UndiciResponse> {
  const contentType = response.headers.get('content-type') ?? '';
  const isEventStream = mediaTypeEssence(contentType) === 'text/event-stream';
  if (context.method === 'GET') {
    if (!context.appProfile) return response;
    if (isEventStream && response.ok) {
      return guardMCPAppSSEEvents(
        response as unknown as Response,
        getMCPAppOperationLimits(context.operationLimits).maxBytes,
        context.onAppSSEOverflow,
      ) as unknown as UndiciResponse;
    }
    // SDK GET error paths may call response.text(); bound those as ordinary HTTP bodies,
    // including non-2xx responses mislabelled as an event stream.
  }
  if (!response.body) {
    return response;
  }

  const { maxResponseBytes, maxLineBytes } = getMCPStreamableHTTPResponseLimits(
    context.appProfile,
    context.operationLimits,
  );
  const canEmitFallbackSSEError = isEventStream && maxLineBytes > 0;
  // SSE streams can emit many bounded events; cumulative bytes must not end a healthy App session.
  const fitsAppEvent =
    isEventStream && response.ok && context.appProfile
      ? createMCPAppSSEEventGuard(maxResponseBytes)
      : undefined;
  if (!isEventStream && maxResponseBytes === 0) {
    return response;
  }
  if (maxResponseBytes === 0 && maxLineBytes === 0) {
    return response;
  }

  let totalBytes = 0;
  let currentLineBytes = 0;
  let chunkCount = 0;
  let pendingSSELineChunks: Uint8Array[] = [];
  const sseEventDataLines: string[] = [];
  const unresolvedRequestIds = new Set(context.requestIds ?? []);

  const buildAndLogBlockedError = (reason: string, details: Record<string, unknown>): Error => {
    const message = buildBlockedMCPResponseMessage(reason, {
      maxResponseBytes,
      maxLineBytes,
      totalBytes,
      currentLineBytes,
      chunkCount,
    });
    logger.warn(`${context.logPrefix} MCP streamable HTTP response blocked: ${reason}`, {
      method: context.method,
      status: response.status,
      maxResponseBytes,
      maxLineBytes,
      totalBytes,
      currentLineBytes,
      chunkCount,
      ...details,
      memory: getMemoryDebugSnapshot(),
    });
    return new Error(message);
  };

  const trackSSELineForResolvedIds = (lineBytes: Uint8Array): void => {
    if (unresolvedRequestIds.size === 0) {
      return;
    }

    const rawLine = textDecoder.decode(lineBytes).replace(/[\r\n]+$/, '');
    if (rawLine === '') {
      if (sseEventDataLines.length === 0) {
        return;
      }
      const data = sseEventDataLines.join('\n');
      sseEventDataLines.length = 0;
      try {
        const parsed = JSON.parse(data) as { id?: unknown };
        if (typeof parsed.id === 'string' || typeof parsed.id === 'number') {
          unresolvedRequestIds.delete(parsed.id);
        }
      } catch {
        /** Ignore malformed SSE data here; the SDK parser will report it. */
      }
      return;
    }

    const separatorIndex = rawLine.indexOf(':');
    const field = separatorIndex === -1 ? rawLine : rawLine.slice(0, separatorIndex);
    if (field !== 'data') {
      return;
    }
    let value = separatorIndex === -1 ? '' : rawLine.slice(separatorIndex + 1);
    if (value.startsWith(' ')) {
      value = value.slice(1);
    }
    sseEventDataLines.push(value);
  };

  const enqueuePendingSSELine = (controller: TransformStreamDefaultController<Uint8Array>) => {
    if (pendingSSELineChunks.length === 0) {
      return;
    }
    const lineBytes = concatBytes(pendingSSELineChunks);
    pendingSSELineChunks = [];
    trackSSELineForResolvedIds(lineBytes);
    controller.enqueue(lineBytes);
  };

  const blockResponse = (
    controller: TransformStreamDefaultController<Uint8Array>,
    reason: string,
    details: Record<string, unknown>,
  ) => {
    const error = buildAndLogBlockedError(reason, details);
    const fallbackRequestIds = [...unresolvedRequestIds];
    if (canEmitFallbackSSEError && fallbackRequestIds.length > 0) {
      controller.enqueue(buildBlockedMCPResponseSSE(fallbackRequestIds, error.message));
      controller.terminate();
      return;
    }
    throw error;
  };

  const guardedBody = (response.body as unknown as ReadableStream<unknown>).pipeThrough(
    new TransformStream<unknown, Uint8Array>({
      transform(chunk, controller) {
        const bytes = getChunkBytes(chunk);
        if (bytes.byteLength === 0) {
          return;
        }

        chunkCount += 1;
        totalBytes += bytes.byteLength;

        if (
          maxResponseBytes > 0 &&
          (fitsAppEvent ? !fitsAppEvent(bytes) : totalBytes > maxResponseBytes)
        ) {
          blockResponse(controller, 'MCP response exceeded byte limit', {
            chunkBytes: bytes.byteLength,
          });
          return;
        }

        if (isEventStream && maxLineBytes > 0) {
          let segmentStart = 0;
          for (let i = 0; i < bytes.byteLength; i++) {
            const byte = bytes[i];
            if (byte === 10 || byte === 13) {
              if (i + 1 > segmentStart) {
                pendingSSELineChunks.push(copyBytes(bytes.subarray(segmentStart, i + 1)));
              }
              enqueuePendingSSELine(controller);
              segmentStart = i + 1;
              currentLineBytes = 0;
              continue;
            }
            currentLineBytes += 1;
            if (currentLineBytes > maxLineBytes) {
              blockResponse(controller, 'MCP response contained an oversized SSE line', {
                chunkBytes: bytes.byteLength,
              });
              return;
            }
          }
          if (segmentStart < bytes.byteLength) {
            pendingSSELineChunks.push(copyBytes(bytes.subarray(segmentStart)));
          }
          return;
        }

        controller.enqueue(bytes);
      },
      flush(controller) {
        enqueuePendingSSELine(controller);
      },
    }),
  );

  return new Response(guardedBody as unknown as BodyInit, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers as unknown as HeadersInit,
  }) as unknown as UndiciResponse;
}

/**
 * Headers stripped before forwarding a request across an origin boundary on
 * 307/308 redirects, mirroring browser/Fetch-spec behavior. These headers can
 * carry credentials (OAuth bearer, MCP session, cookies) that an attacker
 * controlling a redirecting MCP endpoint could otherwise exfiltrate by sending
 * a `Location` to a host they own.
 */
const CROSS_ORIGIN_FORBIDDEN_HEADERS = new Set([
  'authorization',
  'proxy-authorization',
  'cookie',
  'mcp-session-id',
]);

/**
 * Normalizes a fetch input + init pair so the redirect loop only ever has
 * to deal with `(string, init)`. When `input` is a `Request`, its method,
 * headers, and body are baked into the returned init — explicit init values
 * win (matching Fetch-spec semantics) and the body is buffered with
 * `arrayBuffer()` so 307/308 retries can replay it on the new URL. Without
 * this, switching `url` to a `Location` string on redirect would silently
 * drop the original POST method and request payload.
 */
async function resolveFetchInput(
  input: UndiciRequestInfo,
  init: UndiciRequestInit | undefined,
): Promise<{ urlString: string; resolvedInit: UndiciRequestInit | undefined }> {
  if (typeof input === 'string') {
    return { urlString: input, resolvedInit: init };
  }
  if (input instanceof URL) {
    return { urlString: input.href, resolvedInit: init };
  }
  /**
   * Treat anything else as a `Request`. Duck-typed instead of
   * `instanceof undici.Request` because requests handed to a generic fetch
   * wrapper can come from a different undici realm and fail the prototype
   * check while still implementing the same shape. The `as unknown as` cast
   * is needed because undici's `Headers` and DOM's `Headers` have
   * incompatible declared shapes even though they are interchangeable at
   * runtime for the methods we use.
   */
  const req = input as unknown as {
    url: string;
    method: string;
    headers: { entries: () => Iterable<[string, string]> };
    body: unknown;
    signal: AbortSignal | null;
    arrayBuffer: () => Promise<ArrayBuffer>;
  };
  const reqHeaders = Object.fromEntries(req.headers.entries());
  const initHeaders = normalizeInitHeaders(init);
  const mergedHeaders = { ...reqHeaders, ...initHeaders };
  /** Body must be buffered before we hand it off — the original stream is
   * single-shot, so a redirect retry with the same stream would crash with
   * `body has been read`. Empty/no-body Requests skip the read entirely. */
  const reqBody = req.body ? await req.arrayBuffer() : undefined;
  /** Forward the `Request`'s abort signal so callers that wired up an
   * `AbortController` (for timeout / user-cancellation) keep working after
   * we re-shape the input into `(string, init)`. Explicit `init.signal`
   * still wins per Fetch-spec semantics. */
  const signal = init?.signal ?? req.signal ?? undefined;
  return {
    urlString: req.url,
    resolvedInit: {
      ...init,
      method: init?.method ?? req.method,
      body: init?.body ?? (reqBody as unknown as UndiciRequestInit['body']),
      headers: mergedHeaders,
      signal,
    },
  };
}

function normalizeInitHeaders(init: UndiciRequestInit | undefined): Record<string, string> {
  if (!init?.headers) {
    return {};
  }
  if (init.headers instanceof Headers) {
    return Object.fromEntries(init.headers.entries());
  }
  if (Array.isArray(init.headers)) {
    return Object.fromEntries(init.headers);
  }
  return init.headers as Record<string, string>;
}

function buildFetchInit(
  init: UndiciRequestInit | undefined,
  dispatcher: Dispatcher,
  requestHeaders: Record<string, string> | null | undefined,
): UndiciRequestInit {
  const hasInitHeaders = init?.headers != null;
  const hasRuntimeHeaders = requestHeaders != null && Object.keys(requestHeaders).length > 0;
  /**
   * If neither `init.headers` nor runtime headers contribute anything, leave
   * `headers` off the returned init entirely. Setting `headers: {}` would
   * blow away the headers carried on a `Request` input — auth/session tokens
   * and protocol negotiation headers — even when no redirect is involved.
   */
  if (!hasInitHeaders && !hasRuntimeHeaders) {
    return { ...init, redirect: 'manual', dispatcher };
  }
  const initHeaders = normalizeInitHeaders(init);
  const headers = hasRuntimeHeaders ? { ...initHeaders, ...requestHeaders } : initHeaders;
  return {
    ...init,
    redirect: 'manual',
    headers,
    dispatcher,
  };
}

function getUrlPort(url: URL | string): string {
  const parsed = typeof url === 'string' ? new URL(url) : url;
  if (parsed.port) return parsed.port;
  if (parsed.protocol === 'http:' || parsed.protocol === 'ws:') return '80';
  if (parsed.protocol === 'https:' || parsed.protocol === 'wss:') return '443';
  return '';
}

function getTrimmedEnv(...keys: string[]): string | undefined {
  for (const key of keys) {
    const rawValue = process.env[key];
    if (rawValue != null) {
      return rawValue.trim() || undefined;
    }
  }
  return undefined;
}

function getMCPProxyConfig(options: t.MCPOptions): MCPProxyConfig | undefined {
  const configuredProxy =
    'proxy' in options && typeof options.proxy === 'string' ? options.proxy.trim() : '';
  if (configuredProxy) {
    return { type: 'explicit', proxyUrl: configuredProxy };
  }

  const libreChatProxy = process.env.PROXY?.trim() ?? '';
  if (libreChatProxy) {
    return { type: 'explicit', proxyUrl: libreChatProxy };
  }

  const httpProxy = getTrimmedEnv('http_proxy', 'HTTP_PROXY');
  const httpsProxy = getTrimmedEnv('https_proxy', 'HTTPS_PROXY');
  if (!httpProxy && !httpsProxy) {
    return undefined;
  }

  return {
    type: 'env',
    httpProxy,
    httpsProxy,
    noProxy: getTrimmedEnv('no_proxy', 'NO_PROXY'),
  };
}

function parseIPv4ToBigInt(ip: string): bigint | null {
  const octets = ip.split('.');
  if (octets.length !== 4) {
    return null;
  }

  let value = BIGINT_ZERO;
  for (const octet of octets) {
    if (!/^\d{1,3}$/.test(octet)) {
      return null;
    }
    const parsed = Number.parseInt(octet, 10);
    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 255) {
      return null;
    }
    value = (value << BIGINT_EIGHT) + BigInt(parsed);
  }
  return value;
}

function parseIPv6ToBigInt(ip: string): bigint | null {
  let normalized = ip.toLowerCase().replace(/^\[|\]$/g, '');
  const zoneIndex = normalized.indexOf('%');
  if (zoneIndex !== -1) {
    normalized = normalized.slice(0, zoneIndex);
  }

  if (normalized.includes('.')) {
    const lastColon = normalized.lastIndexOf(':');
    if (lastColon === -1) {
      return null;
    }
    const ipv4Value = parseIPv4ToBigInt(normalized.slice(lastColon + 1));
    if (ipv4Value == null) {
      return null;
    }
    const hi = Number((ipv4Value >> BIGINT_SIXTEEN) & UINT16_MASK).toString(16);
    const lo = Number(ipv4Value & UINT16_MASK).toString(16);
    normalized = `${normalized.slice(0, lastColon)}:${hi}:${lo}`;
  }

  const halves = normalized.split('::');
  if (halves.length > 2) {
    return null;
  }

  const left = halves[0] ? halves[0].split(':') : [];
  const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
  const missing = halves.length === 2 ? 8 - left.length - right.length : 0;
  if (missing < 0 || (halves.length === 1 && left.length !== 8)) {
    return null;
  }

  const parts = [...left, ...Array<string>(missing).fill('0'), ...right];
  if (parts.length !== 8 || parts.some((part) => !/^[0-9a-f]{1,4}$/.test(part))) {
    return null;
  }

  return parts.reduce(
    (value, part) => (value << BIGINT_SIXTEEN) + BigInt(Number.parseInt(part, 16)),
    BIGINT_ZERO,
  );
}

function parseIPLiteral(value: string): ParsedIP | null {
  const normalized = value
    .toLowerCase()
    .trim()
    .replace(/^\[|\]$/g, '');
  const version = isIP(normalized);
  if (version === 4) {
    const parsed = parseIPv4ToBigInt(normalized);
    return parsed == null ? null : { version: 4, bits: 32, value: parsed };
  }
  if (version === 6) {
    const parsed = parseIPv6ToBigInt(normalized);
    return parsed == null ? null : { version: 6, bits: 128, value: parsed };
  }
  return null;
}

function ipMatchesCIDR(hostname: string, cidr: string): boolean {
  const [rangeAddress, prefixLength, extra] = cidr.split('/');
  if (!rangeAddress || prefixLength == null || extra != null || !/^\d+$/.test(prefixLength)) {
    return false;
  }

  const hostIP = parseIPLiteral(hostname);
  const rangeIP = parseIPLiteral(rangeAddress);
  if (!hostIP || !rangeIP || hostIP.version !== rangeIP.version) {
    return false;
  }

  const prefix = Number.parseInt(prefixLength, 10);
  if (!Number.isInteger(prefix) || prefix < 0 || prefix > rangeIP.bits) {
    return false;
  }

  const bits = BigInt(rangeIP.bits);
  const mask =
    prefix === 0
      ? BIGINT_ZERO
      : (((BIGINT_ONE << bits) - BIGINT_ONE) << BigInt(rangeIP.bits - prefix)) &
        ((BIGINT_ONE << bits) - BIGINT_ONE);
  return (hostIP.value & mask) === (rangeIP.value & mask);
}

function ipMatchesRange(hostname: string, range: string): boolean {
  const [startAddress, endAddress, extra] = range.split('-');
  if (!startAddress || !endAddress || extra != null) {
    return false;
  }

  const hostIP = parseIPLiteral(hostname);
  const startIP = parseIPLiteral(startAddress);
  const endIP = parseIPLiteral(endAddress);
  if (
    !hostIP ||
    !startIP ||
    !endIP ||
    hostIP.version !== startIP.version ||
    hostIP.version !== endIP.version
  ) {
    return false;
  }

  const min = startIP.value <= endIP.value ? startIP.value : endIP.value;
  const max = startIP.value <= endIP.value ? endIP.value : startIP.value;
  return hostIP.value >= min && hostIP.value <= max;
}

function matchesNoProxyIPPattern(hostname: string, entryHostname: string): boolean {
  if (entryHostname.includes('/')) {
    return ipMatchesCIDR(hostname, entryHostname);
  }
  if (entryHostname.includes('-')) {
    return ipMatchesRange(hostname, entryHostname);
  }
  return false;
}

function getProxyEntryPort(entry: string): {
  hostname: string;
  port: number;
} {
  const trimmed = entry.trim();
  const bracketed = trimmed.match(/^\[([^\]]+)\](?::(\d+))?$/);
  if (bracketed) {
    return {
      hostname: bracketed[1].toLowerCase(),
      port: bracketed[2] ? Number.parseInt(bracketed[2], 10) : 0,
    };
  }

  const separatorCount = (trimmed.match(/:/g) ?? []).length;
  const parsed = separatorCount === 1 ? trimmed.match(/^(.+):(\d+)$/) : null;
  const hostname = (parsed ? parsed[1] : trimmed).replace(/^\[|\]$/g, '').toLowerCase();
  return {
    hostname: hostname.replace(/^\*?\./, ''),
    port: parsed ? Number.parseInt(parsed[2], 10) : 0,
  };
}

function shouldBypassEnvProxy(url: URL, noProxy?: string): boolean {
  if (!noProxy) {
    return false;
  }

  const trimmed = noProxy.trim();
  if (!trimmed) {
    return false;
  }
  if (trimmed === '*') {
    return true;
  }

  const hostname = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
  const port = Number.parseInt(getUrlPort(url), 10) || 0;

  for (const entry of trimmed.split(/[,\s]/)) {
    if (!entry) {
      continue;
    }
    if (entry === '*') {
      return true;
    }

    const proxyEntry = getProxyEntryPort(entry);
    if (proxyEntry.port && proxyEntry.port !== port) {
      continue;
    }
    if (matchesNoProxyIPPattern(hostname, proxyEntry.hostname)) {
      return true;
    }
    if (hostname === proxyEntry.hostname || hostname.endsWith(`.${proxyEntry.hostname}`)) {
      return true;
    }
  }

  return false;
}

function getProxyUrlForRequest(
  proxyConfig: MCPProxyConfig | undefined,
  urlString: string,
): string | undefined {
  if (!proxyConfig || !urlString) {
    return undefined;
  }
  if (proxyConfig.type === 'explicit') {
    return proxyConfig.proxyUrl;
  }

  const url = new URL(urlString);
  if (shouldBypassEnvProxy(url, proxyConfig.noProxy)) {
    return undefined;
  }
  if (url.protocol === 'https:') {
    return proxyConfig.httpsProxy ?? proxyConfig.httpProxy;
  }
  if (url.protocol === 'http:') {
    return proxyConfig.httpProxy;
  }
  return undefined;
}

function createMCPDispatcher(options: {
  bodyTimeout: number;
  headersTimeout: number;
  proxyUrl?: string;
  keepAliveTimeout?: number;
  keepAliveMaxTimeout?: number;
  connect?: ReturnType<typeof createSSRFSafeUndiciConnect>;
}): ManagedDispatcher {
  const { bodyTimeout, headersTimeout, proxyUrl, keepAliveTimeout, keepAliveMaxTimeout, connect } =
    options;

  const baseOptions = {
    bodyTimeout,
    headersTimeout,
    ...(keepAliveTimeout != null ? { keepAliveTimeout } : {}),
    ...(keepAliveMaxTimeout != null ? { keepAliveMaxTimeout } : {}),
  };

  if (proxyUrl) {
    return new ProxyAgent({
      uri: proxyUrl,
      ...baseOptions,
    });
  }

  return new Agent({
    ...baseOptions,
    ...(connect != null ? { connect } : {}),
  });
}

async function assertProxiedRequestTargetAllowed(
  urlString: string,
  proxyConfig: MCPProxyConfig | undefined,
  useSSRFProtection: boolean,
  allowedAddresses?: string[] | null,
): Promise<void> {
  const proxyUrl = getProxyUrlForRequest(proxyConfig, urlString);
  if (!proxyUrl || !useSSRFProtection) {
    return;
  }

  const targetUrl = new URL(urlString);
  const port = getUrlPort(targetUrl);
  if (isAddressAllowed(targetUrl.hostname, allowedAddresses, port)) {
    return;
  }
  if (!parseIPLiteral(targetUrl.hostname)) {
    throw new Error(
      `SSRF protection: proxied MCP request target "${targetUrl.hostname}" must be an IP literal or an explicitly allowed host`,
    );
  }

  const isBlockedTarget =
    isSSRFTarget(targetUrl.hostname, allowedAddresses, port) ||
    (await resolveHostnameSSRF(targetUrl.hostname, allowedAddresses, port));

  if (!isBlockedTarget) {
    return;
  }

  throw new Error(
    `SSRF protection: proxied MCP request target "${targetUrl.hostname}" resolved to a private/reserved address`,
  );
}

/**
 * Drops credential-bearing headers when a 307/308 redirect crosses an origin
 * boundary. Removes the always-forbidden set plus any caller-supplied secret
 * headers (runtime `setRequestHeaders` values and config-level API keys).
 */
function stripCrossOriginHeaders(
  headers: Record<string, string>,
  secretHeaderKeys: ReadonlySet<string>,
): Record<string, string> {
  const stripped: Record<string, string> = {};
  for (const [key, value] of Object.entries(headers)) {
    const lowered = key.toLowerCase();
    if (CROSS_ORIGIN_FORBIDDEN_HEADERS.has(lowered)) {
      continue;
    }
    if (secretHeaderKeys.has(lowered)) {
      continue;
    }
    stripped[key] = value;
  }
  return stripped;
}

interface CircuitBreakerState {
  cycleCount: number;
  cycleWindowStart: number;
  cooldownUntil: number;
  failedRounds: number;
  failedWindowStart: number;
  failedBackoffUntil: number;
}

/** Default body timeout for Streamable HTTP GET SSE streams that idle between server pushes */
const DEFAULT_SSE_READ_TIMEOUT = FIVE_MINUTES;

/**
 * Error message prefixes emitted by the MCP SDK's StreamableHTTPClientTransport
 * (client/streamableHttp.ts → _handleSseStream / _scheduleReconnection).
 * These are SDK-internal strings, not part of a public API. If the SDK changes
 * them, suppression in setupTransportErrorHandlers will silently stop working.
 */
const SDK_SSE_STREAM_DISCONNECTED = 'SSE stream disconnected';
const SDK_SSE_RECONNECT_FAILED = 'Failed to reconnect SSE stream';
const SDK_SSE_RETRIES_EXHAUSTED = 'Maximum reconnection attempts';

/**
 * Headers for SSE connections.
 *
 * Headers we intentionally DO NOT include:
 * - Accept: text/event-stream - Already set by eventsource library AND MCP SDK
 * - X-Accel-Buffering: This is a RESPONSE header for Nginx, not a request header.
 *   The upstream MCP server must send this header for Nginx to respect it.
 * - Connection: keep-alive: Forbidden in HTTP/2 (RFC 7540 §8.1.2.2).
 *   HTTP/2 manages connection persistence differently.
 */
const SSE_REQUEST_HEADERS = {
  'Cache-Control': 'no-cache',
};

interface MCPConnectionParams {
  resolveRequestHeaders?: t.MCPRequestHeaderResolver;
  serverName: string;
  serverConfig: t.MCPOptions;
  userId?: string;
  oauthTokens?: MCPOAuthTokens | null;
  useSSRFProtection?: boolean;
  allowedAddresses?: string[] | null;
  ephemeralConnection?: boolean;
  /** The owner will replace this connection after a tools/list authentication rejection. */
  directBearerRecoveryEnabled?: boolean;
  capabilityProfile?: MCPClientCapabilityProfile;
  operationLimits?: TMCPAppOperationLimits;
}

/** Result of an MCP `tools/list` request: one page of tools plus an optional pagination cursor. */
type MCPListToolsResult = Awaited<ReturnType<Client['listTools']>>;

export interface MCPToolsSnapshot {
  tools: MCPListToolsResult['tools'];
  complete: boolean;
  /** Authentication rejection observed by this exact catalog read. */
  authenticationError?: unknown;
  /** Ordering ticket reserved before this snapshot's `tools/list`; app scope only. */
  publicationRevision?: string;
  /** Set when reserving that ticket failed, which is retryable — unlike a scope that simply
   * has no ordering to reserve, where the ticket is absent because none was ever needed. */
  orderingUnavailable?: boolean;
}

/** Fatal initialization evidence cannot become a partial or optional catalog. */
function requireToolsSnapshot(snapshot: MCPToolsSnapshot): MCPToolsSnapshot {
  if (isMCPInitializationError(snapshot.authenticationError)) throw snapshot.authenticationError;
  return snapshot;
}

export class MCPConnection extends EventEmitter {
  public client: Client;
  private options: t.MCPOptions;
  private transport: Transport | null = null; // Make this nullable
  private connectionState: t.ConnectionState = 'disconnected';
  private connectPromise: Promise<void> | null = null;
  private readonly MAX_RECONNECT_ATTEMPTS = 3;
  public readonly serverName: string;
  public readonly capabilityProfile: MCPClientCapabilityProfile;
  private readonly operationLimits?: TMCPAppOperationLimits;
  private shouldStopReconnecting = false;
  private isReconnecting = false;
  private isInitializing = false;
  private reconnectAttempts = 0;
  /** Set once per transport, so only the first of a conflict's repeat reports escalates. */
  private reportedStandaloneSseConflict = false;
  private agents: Dispatcher[] = [];
  private readonly userId?: string;
  private lastPingTime: number;
  private lastConnectionCheckAt: number = 0;
  private lastConnectionCheckError?: unknown;
  private lastConnectionCheckCredentialSetId?: string | null;
  private transportCredentialSetId: string | null = null;
  private oauthTokens?: MCPOAuthTokens | null;
  private requestHeaders?: Record<string, string> | null;
  private readonly resolveRequestHeaders?: t.MCPRequestHeaderResolver;
  private readonly requestAuthorizationController?: AbortController;
  private readonly requestAuthorization: { error?: unknown; closed: boolean } = { closed: false };
  private readonly pendingRequests = new Set<Promise<unknown>>();
  private readonly sdkRequestScopes = new Map<string | number, MCPRequestScopeRunner>();
  private oauthRequired = false;
  private oauthRecovery = false;
  private readonly useSSRFProtection: boolean;
  private readonly allowedAddresses?: string[] | null;
  private readonly ephemeralConnection: boolean;
  private readonly directBearerRecoveryEnabled: boolean;
  private readonly proxyConfig?: MCPProxyConfig;
  private toolListChangeGeneration = 0;
  private handledToolListChangeGeneration = 0;
  private toolListRefreshFailures = 0;
  private toolListRefreshPromise: Promise<MCPToolsSnapshot | undefined> | null = null;
  private toolListRefreshRetryTimer: ReturnType<typeof setTimeout> | null = null;
  private toolListRefreshEpoch = 0;
  private toolListRefreshSuspended = false;
  private suspendedToolListSnapshot?: MCPToolsSnapshot;
  private publishedToolListSnapshot: {
    epoch: number;
    generation: number;
    tools: MCPListToolsResult['tools'];
    publicationRevision?: string;
  } | null = null;

  private hasConnected = false;
  private isDisposed = false;
  iconPath?: string;
  timeout?: number;
  sseReadTimeout?: number;
  url?: string;

  /**
   * Timestamp when this connection was created.
   * Used to detect if connection is stale compared to updated config.
   */
  public readonly createdAt: number;

  /**
   * Bumped on every tools/list_changed notification. Consumers that cache tool metadata can fold
   * this into their freshness check to detect tool changes that happen on a live connection, which
   * createdAt alone (stable until reconnect) cannot.
   */
  public toolListVersion = 0;

  private static circuitBreakers: Map<string, CircuitBreakerState> = new Map();

  public static clearCooldown(serverName: string): void {
    MCPConnection.circuitBreakers.delete(serverName);
    logger.debug('[MCP] Circuit breaker state cleared');
  }

  private getCircuitBreaker(): CircuitBreakerState {
    let cb = MCPConnection.circuitBreakers.get(this.serverName);
    if (!cb) {
      cb = {
        cycleCount: 0,
        cycleWindowStart: Date.now(),
        cooldownUntil: 0,
        failedRounds: 0,
        failedWindowStart: Date.now(),
        failedBackoffUntil: 0,
      };
      MCPConnection.circuitBreakers.set(this.serverName, cb);
    }
    return cb;
  }

  private isCircuitOpen(): boolean {
    const cb = this.getCircuitBreaker();
    const now = Date.now();
    return now < cb.cooldownUntil || now < cb.failedBackoffUntil;
  }

  private recordCycle(): void {
    const cb = this.getCircuitBreaker();
    const now = Date.now();
    if (now - cb.cycleWindowStart > mcpConfig.CB_CYCLE_WINDOW_MS) {
      cb.cycleCount = 0;
      cb.cycleWindowStart = now;
    }
    cb.cycleCount++;
    if (cb.cycleCount >= mcpConfig.CB_MAX_CYCLES) {
      cb.cooldownUntil = now + mcpConfig.CB_CYCLE_COOLDOWN_MS;
      cb.cycleCount = 0;
      cb.cycleWindowStart = now;
      logger.warn(
        `${this.getLogPrefix()} Circuit breaker: too many cycles, cooling down for ${mcpConfig.CB_CYCLE_COOLDOWN_MS}ms`,
      );
    }
  }

  private recordFailedRound(): void {
    const cb = this.getCircuitBreaker();
    const now = Date.now();
    if (now - cb.failedWindowStart > mcpConfig.CB_FAILED_WINDOW_MS) {
      cb.failedRounds = 0;
      cb.failedWindowStart = now;
    }
    cb.failedRounds++;
    if (cb.failedRounds >= mcpConfig.CB_MAX_FAILED_ROUNDS) {
      const backoff = Math.min(
        mcpConfig.CB_BASE_BACKOFF_MS *
          Math.pow(2, cb.failedRounds - mcpConfig.CB_MAX_FAILED_ROUNDS),
        mcpConfig.CB_MAX_BACKOFF_MS,
      );
      cb.failedBackoffUntil = now + backoff;
      logger.warn(
        `${this.getLogPrefix()} Circuit breaker: too many failures, backing off for ${backoff}ms`,
      );
    }
  }

  private resetFailedRounds(): void {
    const cb = this.getCircuitBreaker();
    cb.failedRounds = 0;
    cb.failedWindowStart = Date.now();
    cb.failedBackoffUntil = 0;
  }

  public static decrementCycleCount(serverName: string): void {
    const cb = MCPConnection.circuitBreakers.get(serverName);
    if (cb && cb.cycleCount > 0) {
      cb.cycleCount--;
    }
  }

  setRequestHeaders(headers: Record<string, string> | null): void {
    if (!headers) {
      return;
    }
    const normalizedHeaders: Record<string, string> = {};
    for (const [key, value] of Object.entries(headers)) {
      normalizedHeaders[key.toLowerCase()] = value;
    }
    this.requestHeaders = normalizedHeaders;
  }

  /** Stable routing identity captured by this connection, without live authorization headers. */
  getMCPAppRuntimeTarget(): MCPAppRuntimeTarget {
    return projectMCPAppRuntimeTarget(this.options);
  }

  getRequestHeaders(): Record<string, string> | null | undefined {
    return this.requestHeaders;
  }

  /**
   * Replaces only the runtime bearer, leaving the rest of the per-request headers
   * a tool call installed intact. Runtime headers outrank the ones baked into the
   * transport (see `buildFetchInit`), so a credential refreshed mid-connection has
   * to land here as well or the stale `authorization` from the last tool call would
   * keep winning on the retry.
   */
  setAuthorizationHeader(accessToken: string): void {
    this.requestHeaders = {
      ...(this.requestHeaders ?? {}),
      authorization: `Bearer ${accessToken}`,
    };
  }

  /**
   * Halts reconnect attempts for a credential this connection cannot refresh on its
   * own. Retrying would replay the rejected bearer through every backoff step and
   * spend the circuit breaker's cycle budget; the connection is instead left for its
   * next borrower to dispose and rebuild with a live credential.
   */
  stopReconnecting(): void {
    this.shouldStopReconnecting = true;
  }

  constructor(params: MCPConnectionParams) {
    super();
    this.options = params.serverConfig;
    this.resolveRequestHeaders = params.resolveRequestHeaders;
    if (this.resolveRequestHeaders) this.requestAuthorizationController = new AbortController();
    this.serverName = params.serverName;
    this.capabilityProfile = params.capabilityProfile ?? STANDARD_MCP_CAPABILITY_PROFILE;
    this.operationLimits = params.operationLimits;
    this.userId = params.userId;
    this.useSSRFProtection = params.useSSRFProtection === true;
    this.allowedAddresses = params.allowedAddresses ?? null;
    this.ephemeralConnection = params.ephemeralConnection === true;
    this.directBearerRecoveryEnabled = params.directBearerRecoveryEnabled === true;
    this.proxyConfig = getMCPProxyConfig(params.serverConfig);
    this.iconPath = params.serverConfig.iconPath;
    this.timeout = params.serverConfig.timeout;
    this.sseReadTimeout = params.serverConfig.sseReadTimeout;
    this.lastPingTime = Date.now();
    this.createdAt = Date.now(); // Record creation timestamp for staleness detection
    if (params.oauthTokens) {
      this.oauthTokens = params.oauthTokens;
    }
    const capabilities: ClientCapabilities =
      this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE
        ? { extensions: { [MCP_UI_EXTENSION_ID]: { mimeTypes: [RESOURCE_MIME_TYPE] } } }
        : {};
    this.client = new Client(
      {
        name: '@librechat/api-client',
        version: '1.2.3',
      },
      { capabilities },
    );

    this.setupEventListeners();
  }

  /** Helper to generate consistent log prefixes */
  private getLogPrefix(): string {
    const userPart = this.userId ? `[User: ${this.userId}]` : '';
    return `[MCP]${userPart}`;
  }

  /**
   * Factory function to create fetch functions without capturing the entire `this` context.
   * This helps prevent memory leaks by only passing necessary dependencies.
   *
   * When `sseBodyTimeout` is provided, a second Agent is created with a much longer
   * body timeout for GET requests (the Streamable HTTP SSE stream). POST requests
   * continue using the normal timeout so they fail fast on real errors.
   */
  private createFetchFunction(
    getHeaders: () => Record<string, string> | null | undefined,
    timeout?: number,
    sseBodyTimeout?: number,
    configuredSecretHeaderKeys?: ReadonlySet<string>,
    baseUrl?: string,
    guardStreamableHTTPResponses = false,
  ): (input: UndiciRequestInfo, init?: UndiciRequestInit) => Promise<UndiciResponse> {
    const proxyConfig = this.proxyConfig;
    const useSSRFProtection = this.useSSRFProtection;
    const allowedAddresses = this.allowedAddresses;
    /** Capture only the fields needed by the fetch closure; see factory note above. */
    const agents = this.agents;
    const logPrefix = this.getLogPrefix();
    const rejectDirectBearerAuthentication = this.directBearerRecoveryEnabled;
    const authorizeHeaders = this.resolveRequestHeaders
      ? this.authorizeRequestHeaders.bind(this)
      : undefined;
    const trackRequest = this.resolveRequestHeaders ? this.trackRequest.bind(this) : undefined;
    const assertDispatch = this.resolveRequestHeaders
      ? this.assertRequestDispatch.bind(this)
      : undefined;
    const reportRejection = this.resolveRequestHeaders?.recordFailure
      ? this.failRequestAuthorization.bind(this)
      : undefined;
    const thisAppProfile = this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE;
    const appOperationLimits = this.operationLimits;
    const effectiveTimeout = timeout || DEFAULT_TIMEOUT;
    const requestDispatchers = new Map<string, ManagedDispatcher>();
    const ssrfConnects = new Map<string, ReturnType<typeof createSSRFSafeUndiciConnect>>();

    const getSSRFConnect = (
      targetPort: string,
      dispatcherAllowedAddresses: string[] | null | undefined,
      forceSafeDirectConnect: boolean,
    ): ReturnType<typeof createSSRFSafeUndiciConnect> => {
      const key = `${forceSafeDirectConnect ? 'redirect' : 'configured'}:${targetPort}`;
      const existingConnect = ssrfConnects.get(key);
      if (existingConnect) {
        return existingConnect;
      }

      const connect = forceSafeDirectConnect
        ? createSSRFSafeUndiciConnect()
        : createSSRFSafeUndiciConnect(dispatcherAllowedAddresses, targetPort);
      ssrfConnects.set(key, connect);
      return connect;
    };

    /**
     * Proxy selection depends on the resolved request URL, not just the
     * configured MCP base URL. SSE message endpoints can be absolute URLs, so
     * cache dispatchers by the target URL's proxy decision and connect policy.
     */
    const getRequestDispatcher = (
      isGetRequest: boolean,
      targetUrlString: string,
      dispatcherAllowedAddresses: string[] | null | undefined,
      forceSafeDirectConnect = false,
    ): ManagedDispatcher => {
      const bodyTimeout =
        isGetRequest && sseBodyTimeout != null ? sseBodyTimeout : effectiveTimeout;
      const proxyUrl = getProxyUrlForRequest(proxyConfig, targetUrlString);
      const targetPort = getUrlPort(targetUrlString);
      const needsSSRFConnect = !proxyUrl && (useSSRFProtection || forceSafeDirectConnect);
      const key = [
        bodyTimeout,
        proxyUrl ?? 'direct',
        needsSSRFConnect ? targetPort : 'open',
        forceSafeDirectConnect ? 'redirect' : 'configured',
      ].join(':');
      const existingAgent = requestDispatchers.get(key);
      if (existingAgent) {
        return existingAgent;
      }

      const connect = needsSSRFConnect
        ? getSSRFConnect(targetPort, dispatcherAllowedAddresses, forceSafeDirectConnect)
        : undefined;
      const agent = createMCPDispatcher({
        bodyTimeout,
        headersTimeout: effectiveTimeout,
        proxyUrl,
        ...(connect != null ? { connect } : {}),
      });
      requestDispatchers.set(key, agent);
      agents.push(agent);
      return agent;
    };

    if (baseUrl) {
      getRequestDispatcher(false, baseUrl, allowedAddresses);
      if (sseBodyTimeout != null) {
        getRequestDispatcher(true, baseUrl, allowedAddresses);
      }
    }

    const customFetch = async (
      input: UndiciRequestInfo,
      init?: UndiciRequestInit,
    ): Promise<UndiciResponse> => {
      /**
       * Resolve the input shape upfront so the redirect loop can work with a
       * (string url, init) pair uniformly. When `input` is a `Request`, we
       * pull its method, headers, and body into the init — the body is
       * buffered because `Request.body` is a one-shot stream that can't be
       * replayed across redirect hops, and switching `url` to the new
       * `Location` would otherwise drop the original method/body and turn a
       * redirected POST into a GET with no payload.
       */
      const callerSignal = getMCPDispatchSignal();
      const { urlString, resolvedInit } = await resolveFetchInput(input, init);

      const isGet = (resolvedInit?.method ?? 'GET').toUpperCase() === 'GET';
      const requestHeaders = getHeaders();
      const reauthorize =
        authorizeHeaders && (resolvedInit?.method ?? 'GET').toUpperCase() !== 'DELETE';
      const admissionSignal =
        reauthorize && callerSignal
          ? AbortSignal.any([callerSignal, ...(resolvedInit?.signal ? [resolvedInit.signal] : [])])
          : (resolvedInit?.signal ?? undefined);
      let credentialsStripped = false;
      /**
       * Headers that originated from user/server configuration — runtime
       * `setRequestHeaders` plus any keys baked into the transport at
       * construction time (e.g. `serverConfig.headers` API keys). All are
       * treated as credentials and stripped on cross-origin redirect.
       */
      const secretHeaderKeys = new Set([
        ...Object.keys(requestHeaders ?? {}).map((key) => key.toLowerCase()),
        ...(configuredSecretHeaderKeys ?? []),
      ]);

      let currentUrlString = urlString;
      let currentAllowedAddresses = allowedAddresses;
      let forceRedirectSSRFConnect = false;
      let currentInit = buildFetchInit(
        resolvedInit,
        getRequestDispatcher(isGet, currentUrlString, currentAllowedAddresses),
        requestHeaders,
      );
      const originalOrigin = new URL(currentUrlString).origin;
      for (let redirects = 0; ; redirects++) {
        await assertProxiedRequestTargetAllowed(
          currentUrlString,
          proxyConfig,
          useSSRFProtection,
          currentAllowedAddresses,
        );
        if (reauthorize) {
          const authorized = await authorizeHeaders(admissionSignal);
          if (!credentialsStripped) {
            for (const key of Object.keys(authorized ?? {}))
              secretHeaderKeys.add(key.toLowerCase());
            currentInit = buildFetchInit(
              currentInit,
              getRequestDispatcher(
                isGet,
                currentUrlString,
                currentAllowedAddresses,
                forceRedirectSSRFConnect,
              ),
              { ...getHeaders(), ...authorized },
            );
          }
        }
        // No await may separate this cutoff from network admission.
        if (reauthorize) assertDispatch?.(admissionSignal);
        const response = await undiciFetch(currentUrlString, currentInit);
        if (
          (rejectDirectBearerAuthentication || (reportRejection && reauthorize)) &&
          (response.status === 401 || response.status === 403)
        ) {
          await response.body?.cancel().catch(() => undefined);
          const error = new MCPTransportAuthenticationError(response.status);
          if (reportRejection && reauthorize) return reportRejection(error);
          throw error;
        }
        const isMethodPreservingRedirect = response.status === 307 || response.status === 308;
        const responseContext = {
          logPrefix,
          method: (currentInit?.method ?? 'GET').toUpperCase(),
          url: currentUrlString,
          requestIds: getJSONRPCRequestIds(currentInit?.body),
          appProfile: thisAppProfile,
          operationLimits: appOperationLimits,
        };

        // A redirected tool request is another dispatch, not proof the first was inert.
        if (
          !isMethodPreservingRedirect ||
          redirects >= MAX_REDIRECTS ||
          (reauthorize && containsToolInvocation(currentInit.body))
        ) {
          return guardStreamableHTTPResponses
            ? guardMCPStreamableHTTPResponse(response, responseContext)
            : response;
        }

        const location = response.headers.get('location');
        if (!location) {
          return guardStreamableHTTPResponses
            ? guardMCPStreamableHTTPResponse(response, responseContext)
            : response;
        }

        const targetUrl = new URL(location, currentUrlString);
        const isCrossOriginRedirect = targetUrl.origin !== originalOrigin;

        /**
         * Keep the standalone check for immediate literal/current-DNS blocks.
         * Cross-origin allowlist redirects also switch to a connect-time
         * SSRF-safe dispatcher below so DNS rebinding cannot change the
         * address between this check and the socket connection.
         *
         * `allowedAddresses` is intentionally NOT consulted on either layer:
         * redirect targets are server-controlled (the MCP server's response
         * chooses where to send us), so they must not inherit the admin's
         * exemption for the originally-configured URL. A legitimate self-
         * redirect from a permitted private host is still blocked here, by
         * design — letting redirect targets inherit the exemption would open
         * an SSRF amplification primitive.
         */
        if (isSSRFTarget(targetUrl.hostname) || (await resolveHostnameSSRF(targetUrl.hostname))) {
          logger.warn('[MCP] Blocked redirect to private or reserved address');
          return response;
        }

        await response.body?.cancel().catch(() => undefined);

        if (isCrossOriginRedirect) credentialsStripped = true;
        if (isCrossOriginRedirect && currentInit.headers != null) {
          currentInit = {
            ...currentInit,
            headers: stripCrossOriginHeaders(
              currentInit.headers as Record<string, string>,
              secretHeaderKeys,
            ),
          };
        }

        if (isCrossOriginRedirect) {
          currentAllowedAddresses = null;
          forceRedirectSSRFConnect = true;
          /**
           * Once a server-controlled cross-origin hop is seen, keep the safe
           * dispatcher for the rest of this redirect chain. Restoring the
           * original dispatcher on a later hop back to the original origin
           * would re-open the allowlist-mode rebinding gap. When the original
           * dispatcher carries `allowedAddresses`, this also prevents a
           * redirect from inheriting that port-scoped exemption.
           */
          currentInit = {
            ...currentInit,
            dispatcher: getRequestDispatcher(
              isGet,
              targetUrl.href,
              currentAllowedAddresses,
              forceRedirectSSRFConnect,
            ),
          };
        } else {
          currentInit = {
            ...currentInit,
            dispatcher: getRequestDispatcher(
              isGet,
              targetUrl.href,
              currentAllowedAddresses,
              forceRedirectSSRFConnect,
            ),
          };
        }

        currentUrlString = targetUrl.href;
      }
    };
    return trackRequest
      ? (input, init) => trackRequest(() => customFetch(input, init))
      : customFetch;
  }

  private trackRequest<T>(operation: () => Promise<T>): Promise<T> {
    if (!this.resolveRequestHeaders) return operation();
    const request = operation();
    this.pendingRequests.add(request);
    void request.then(
      () => this.pendingRequests.delete(request),
      () => this.pendingRequests.delete(request),
    );
    return request;
  }

  private assertRequestDispatch(signal?: AbortSignal): void {
    signal?.throwIfAborted();
    if (this.requestAuthorization.closed) throw new MCPRequestQuiescedError();
    this.requestAuthorizationController?.signal.throwIfAborted();
    this.resolveRequestHeaders?.assertOpen?.();
  }

  private async authorizeRequestHeaders(
    signal?: AbortSignal,
  ): Promise<Record<string, string> | undefined> {
    if (!this.resolveRequestHeaders) return;
    try {
      if (this.requestAuthorization.closed) throw new Error('MCP connection is closed');
      const connectionSignal = this.requestAuthorizationController!.signal;
      signal = signal ? AbortSignal.any([signal, connectionSignal]) : connectionSignal;
      signal.throwIfAborted();
      // Detach this waiter only; shared mints retain their occurrence-owned signal.
      const headers = await awaitOboOperation(
        this.resolveRequestHeaders(signal, (error) => this.stopRequestAuthorization(error)),
        signal,
      );
      signal.throwIfAborted();
      if (this.requestAuthorization.closed) throw new Error('MCP connection is closed');
      return headers;
    } catch (error) {
      if (isOwnedAbortError(error, signal)) throw error;
      return this.failRequestAuthorization(error);
    }
  }

  private stopRequestAuthorization(error: unknown): void {
    this.requestAuthorization.error = error;
    this.shouldStopReconnecting = true;
  }

  private failRequestAuthorization(error: unknown): Promise<never> {
    // Stop retries before receipt admission waits; failure evidence outlives SDK deadlines.
    this.stopRequestAuthorization(error);
    const failure = (async () => {
      try {
        if (this.resolveRequestHeaders?.recordFailure)
          await this.resolveRequestHeaders.recordFailure(error);
      } catch (reported) {
        this.requestAuthorization.error = reported;
        throw reported;
      }
      throw error;
    })();
    if (
      this.resolveRequestHeaders?.recordFailure &&
      (isMCPInitializationError(error) || isMCPTransportAuthenticationError(error))
    )
      holdMCPRequestFailure(failure);
    return failure;
  }

  /** Owns only this SDK request's caller cutoff and admission, never a connection-global error. */
  public withRequestSignal<T>(
    signal: AbortSignal | undefined,
    request: (signal: AbortSignal | undefined) => Promise<T>,
  ): Promise<T> {
    return withMCPRequestSignal(signal, request, this.resolveRequestHeaders != null);
  }

  private emitError(_error: unknown, errorContext: string): void {
    logger.error(`${this.getLogPrefix()} ${errorContext}`);
  }

  private async constructTransport(options: t.MCPOptions): Promise<Transport> {
    try {
      let type: t.MCPOptions['type'];
      if (isStdioOptions(options)) {
        type = 'stdio';
      } else if (isWebSocketOptions(options)) {
        type = 'websocket';
      } else if (isStreamableHTTPOptions(options)) {
        // Could be either 'streamable-http' or 'http', normalize to 'streamable-http'
        type = 'streamable-http';
      } else if (isSSEOptions(options)) {
        type = 'sse';
      } else {
        throw new Error(
          'Cannot infer transport type: options.type is not provided and cannot be inferred from other properties.',
        );
      }

      switch (type) {
        case 'stdio':
          if (!isStdioOptions(options)) {
            throw new Error('Invalid options for stdio transport.');
          }
          return new StdioClientTransport({
            command: options.command,
            args: options.args,
            // workaround bug of mcp sdk that can't pass env:
            // https://github.com/modelcontextprotocol/typescript-sdk/issues/216
            env: { ...getDefaultEnvironment(), ...(options.env ?? {}) },
            ...(options.cwd !== undefined && { cwd: options.cwd }),
            ...(this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE && {
              maxBufferSize: getMCPAppOperationLimits(this.operationLimits).maxBytes,
            }),
          });

        case 'websocket': {
          if (!isWebSocketOptions(options)) {
            throw new Error('Invalid options for websocket transport.');
          }
          if (this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE) {
            // This SDK WebSocket transport JSON.parse's messages before exposing them and offers
            // no maxPayload option. Fail closed for Apps rather than claim a post-parse cap is safe.
            throw new Error('MCP Apps require a transport with a pre-parse response size limit');
          }
          this.url = options.url;
          /**
           * SSRF pre-check: always validate resolved IPs for WebSocket, regardless
           * of allowlist configuration. Allowlisting a domain grants trust to that
           * name, not to whatever IP it resolves to at runtime (DNS rebinding).
           *
           * Note: WebSocketClientTransport does its own DNS resolution, creating a
           * small TOCTOU window. This is an SDK limitation — the transport accepts
           * only a URL with no custom DNS lookup hook.
           */
          const wsUrl = new URL(options.url);
          const wsHostname = wsUrl.hostname;
          const isSSRF = await resolveHostnameSSRF(
            wsHostname,
            this.allowedAddresses,
            getUrlPort(wsUrl),
          );
          if (isSSRF) {
            throw new Error(
              `SSRF protection: WebSocket host "${wsHostname}" resolved to a private/reserved IP address`,
            );
          }
          return new WebSocketClientTransport(new URL(options.url));
        }

        case 'sse': {
          if (!isSSEOptions(options)) {
            throw new Error('Invalid options for sse transport.');
          }
          this.url = options.url;
          const url = new URL(options.url);
          logger.info(`${this.getLogPrefix()} Creating SSE transport`);
          const abortController = new AbortController();

          /** Add OAuth token to headers if available */
          const headers = { ...options.headers };
          if (this.oauthTokens?.access_token) {
            headers['Authorization'] = `Bearer ${this.oauthTokens.access_token}`;
          }

          /**
           * SSE connections need longer timeouts for reliability.
           * The connect timeout is extended because proxies may delay initial response.
           */
          const sseTimeout = this.timeout || SSE_CONNECT_TIMEOUT;
          const sseAgents = new Map<string, ManagedDispatcher>();
          const getSSEDispatcher = (targetUrlString: string): ManagedDispatcher => {
            const proxyUrl = getProxyUrlForRequest(this.proxyConfig, targetUrlString);
            const targetPort = getUrlPort(targetUrlString);
            const key = `${proxyUrl ?? 'direct'}:${this.useSSRFProtection && !proxyUrl ? targetPort : 'open'}`;
            const existingAgent = sseAgents.get(key);
            if (existingAgent) {
              return existingAgent;
            }

            const connect =
              this.useSSRFProtection && !proxyUrl
                ? createSSRFSafeUndiciConnect(this.allowedAddresses, targetPort)
                : undefined;
            const agent = createMCPDispatcher({
              bodyTimeout: sseTimeout,
              headersTimeout: sseTimeout,
              keepAliveTimeout: sseTimeout,
              keepAliveMaxTimeout: sseTimeout * 2,
              proxyUrl,
              ...(connect != null ? { connect } : {}),
            });
            sseAgents.set(key, agent);
            this.agents.push(agent);
            return agent;
          };
          getSSEDispatcher(options.url);
          const sseConfiguredSecretHeaderKeys: ReadonlySet<string> = new Set(
            Object.keys(headers).map((key) => key.toLowerCase()),
          );
          const transport = new SSEClientTransport(url, {
            redirectPolicy: SDK_REDIRECT_POLICY,
            requestInit: {
              /** User/OAuth headers override SSE defaults */
              headers: { ...SSE_REQUEST_HEADERS, ...headers },
              signal: abortController.signal,
            },
            eventSourceInit: {
              fetch: (url, init) =>
                this.trackRequest(async () => {
                  const callerSignal = getMCPDispatchSignal();
                  const { urlString, resolvedInit } = await resolveFetchInput(
                    url as UndiciRequestInfo,
                    init as UndiciRequestInit,
                  );
                  await assertProxiedRequestTargetAllowed(
                    urlString,
                    this.proxyConfig,
                    this.useSSRFProtection,
                    this.allowedAddresses,
                  );
                  /** Merge headers: SSE defaults < init headers < user headers (user wins) */
                  const fetchHeaders = Object.assign(
                    {},
                    SSE_REQUEST_HEADERS,
                    resolvedInit?.headers,
                    headers,
                  );
                  const admissionSignal = callerSignal
                    ? AbortSignal.any([
                        callerSignal,
                        ...(resolvedInit?.signal ? [resolvedInit.signal] : []),
                      ])
                    : (resolvedInit?.signal ?? undefined);
                  const authorized = this.resolveRequestHeaders
                    ? await this.authorizeRequestHeaders(admissionSignal)
                    : undefined;
                  let liveHeaders = this.directBearerRecoveryEnabled
                    ? this.getRequestHeaders()
                    : undefined;
                  if (authorized) liveHeaders = { ...this.getRequestHeaders(), ...authorized };
                  if (liveHeaders) {
                    for (const key of Object.keys(fetchHeaders)) {
                      const normalized = key.toLowerCase();
                      if (
                        sseConfiguredSecretHeaderKeys.has(normalized) &&
                        liveHeaders[normalized] != null
                      ) {
                        delete fetchHeaders[key];
                        fetchHeaders[normalized] = liveHeaders[normalized];
                      }
                    }
                  }
                  const requestInit: UndiciRequestInit = {
                    ...resolvedInit,
                    redirect: 'manual',
                    dispatcher: getSSEDispatcher(urlString),
                    headers: fetchHeaders,
                  };
                  if (this.resolveRequestHeaders) this.assertRequestDispatch(admissionSignal);
                  const response = await undiciFetch(urlString, requestInit);
                  if (
                    this.resolveRequestHeaders?.recordFailure &&
                    (response.status === 401 || response.status === 403)
                  ) {
                    await response.body?.cancel().catch(() => undefined);
                    return this.failRequestAuthorization(
                      new MCPTransportAuthenticationError(response.status),
                    );
                  }
                  return this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE
                    ? guardMCPStreamableHTTPResponse(response, {
                        logPrefix: this.getLogPrefix(),
                        method: 'GET',
                        url: urlString,
                        appProfile: true,
                        operationLimits: this.operationLimits,
                        onAppSSEOverflow: () => {
                          // Let the SDK observe its stream error and reject an in-flight start before
                          // closing EventSource. Closing synchronously leaves start() pending forever.
                          // A short bounded grace also prevents the SDK's automatic retry loop.
                          const stop = setTimeout(() => {
                            abortController.abort();
                            void transport.close().catch(() => undefined);
                          }, 30);
                          stop.unref?.();
                        },
                      })
                    : response;
                }),
            },
            fetch: this.createFetchFunction(
              this.getRequestHeaders.bind(this),
              sseTimeout,
              undefined,
              sseConfiguredSecretHeaderKeys,
              options.url,
              this.capabilityProfile === MCP_APPS_CAPABILITY_PROFILE,
            ) as unknown as FetchLike,
          });

          transport.onclose = () => {
            logger.info(`${this.getLogPrefix()} SSE transport closed`);
            this.emit('connectionChange', 'disconnected');
          };

          this.setupTransportErrorHandlers(transport);
          return transport;
        }

        case 'streamable-http': {
          if (!isStreamableHTTPOptions(options)) {
            throw new Error('Invalid options for streamable-http transport.');
          }
          this.url = options.url;
          const url = new URL(options.url);
          logger.info(`${this.getLogPrefix()} Creating streamable-http transport`);
          const abortController = new AbortController();

          /** Add OAuth token to headers if available */
          const headers = { ...options.headers };
          if (this.oauthTokens?.access_token) {
            headers['Authorization'] = `Bearer ${this.oauthTokens.access_token}`;
          }

          const httpConfiguredSecretHeaderKeys: ReadonlySet<string> = new Set(
            Object.keys(headers).map((key) => key.toLowerCase()),
          );
          const transport = new StreamableHTTPClientTransport(url, {
            redirectPolicy: SDK_REDIRECT_POLICY,
            requestInit: {
              headers,
              signal: abortController.signal,
            },
            fetch: this.createFetchFunction(
              this.getRequestHeaders.bind(this),
              this.timeout,
              this.sseReadTimeout || DEFAULT_SSE_READ_TIMEOUT,
              httpConfiguredSecretHeaderKeys,
              options.url,
              true,
            ) as unknown as FetchLike,
          });

          transport.onclose = () => {
            logger.info(`${this.getLogPrefix()} Streamable-http transport closed`);
            this.emit('connectionChange', 'disconnected');
          };

          this.setupTransportErrorHandlers(transport);
          return transport;
        }

        default: {
          throw new Error(`Unsupported transport type: ${type}`);
        }
      }
    } catch (error) {
      this.emitError(error, 'Failed to construct transport');
      throw error;
    }
  }

  private setupEventListeners(): void {
    this.isInitializing = true;
    this.on('connectionChange', (state: t.ConnectionState) => {
      this.connectionState = state;
      this.suspendedToolListSnapshot = undefined;
      if (state === 'connected') {
        this.lastConnectionCheckError = undefined;
        this.lastConnectionCheckCredentialSetId = undefined;
        const isReconnect = this.hasConnected;
        this.hasConnected = true;
        this.toolListRefreshSuspended = false;
        this.isReconnecting = false;
        this.isInitializing = false;
        this.shouldStopReconnecting = false;
        this.reconnectAttempts = 0;
        if (isReconnect) {
          if (this.client.getServerCapabilities()?.tools != null) {
            this.toolListChangeGeneration++;
          } else {
            this.handledToolListChangeGeneration = this.toolListChangeGeneration;
            this.toolListRefreshFailures = 0;
            this.dispatchToolsChanged([]);
          }
        }
        if (this.handledToolListChangeGeneration < this.toolListChangeGeneration) {
          this.startToolListRefresh();
        }
        /**
         * // FOR DEBUGGING
         * // this.client.setRequestHandler(PingRequestSchema, async (request, extra) => {
         * //    logger.info(`[MCP][${this.serverName}] PingRequest: ${JSON.stringify(request)}`);
         * //    if (getEventListeners && extra.signal) {
         * //      const listenerCount = getEventListeners(extra.signal, 'abort').length;
         * //      logger.debug(`Signal has ${listenerCount} abort listeners`);
         * //    }
         * //    return {};
         * //  });
         */
      } else {
        /** Invalidate work started on the previous transport. A reconnect can complete before an
         * old `tools/list` request settles, so checking connectionState alone is not sufficient. */
        this.toolListRefreshEpoch++;
        this.toolListRefreshSuspended = true;
        this.clearToolListRefreshRetry();
      }

      if (state === 'error' && !this.isReconnecting && !this.isInitializing) {
        this.handleReconnection().catch(() => {
          logger.error(`${this.getLogPrefix()} Reconnection handler failed`);
        });
      }
    });

    this.subscribeToResources();
    this.subscribeToToolListChanges();
  }

  private async handleReconnection(): Promise<void> {
    if (
      this.isReconnecting ||
      this.shouldStopReconnecting ||
      this.isInitializing ||
      this.oauthRequired
    ) {
      if (this.oauthRequired) {
        logger.info(`${this.getLogPrefix()} OAuth required, skipping reconnection attempts`);
      }
      return;
    }

    this.isReconnecting = true;
    const backoffDelay = (attempt: number) => {
      const base = Math.min(1000 * Math.pow(2, attempt), 30000);
      const jitter = Math.floor(Math.random() * 1000); // up to 1s of random jitter
      return base + jitter;
    };

    try {
      while (
        this.reconnectAttempts < this.MAX_RECONNECT_ATTEMPTS &&
        !(this.shouldStopReconnecting as boolean)
      ) {
        this.reconnectAttempts++;
        const delay = backoffDelay(this.reconnectAttempts);

        logger.info(
          `${this.getLogPrefix()} Reconnecting ${this.reconnectAttempts}/${this.MAX_RECONNECT_ATTEMPTS} (delay: ${delay}ms)`,
        );

        await new Promise((resolve) => setTimeout(resolve, delay));

        try {
          await this.connect();
          this.reconnectAttempts = 0;
          return;
        } catch (error) {
          logger.error(`${this.getLogPrefix()} Reconnection attempt failed`);

          // Stop immediately if rate limited - retrying will only make it worse
          if (this.isRateLimitError(error)) {
            /**
             * Rate limiting sets shouldStopReconnecting to prevent hammering the server.
             * Silent return here (vs throw in connectClient) because we're already in
             * error recovery mode - throwing would just add noise. The connection
             * must be recreated to retry after rate limit lifts.
             */
            logger.warn(
              `${this.getLogPrefix()} Rate limited (429), stopping reconnection attempts`,
            );
            logger.debug(
              `${this.getLogPrefix()} Rate limit block is permanent for this connection instance`,
            );
            this.shouldStopReconnecting = true;
            return;
          }

          if (
            this.reconnectAttempts === this.MAX_RECONNECT_ATTEMPTS ||
            (this.shouldStopReconnecting as boolean)
          ) {
            logger.error(`${this.getLogPrefix()} Stopping reconnection attempts`);
            return;
          }
        }
      }
    } finally {
      this.isReconnecting = false;
    }
  }

  private subscribeToResources(): void {
    this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
      this.emit('resourcesChanged');
    });
  }

  /**
   * A server that builds tools at runtime tells us so instead of us polling for it.
   *
   * The spec's list-changed flow is: the server notifies, the client asks for the list again. Until
   * this was handled the tool list stayed at whatever it was when the connection came up, so a
   * server that adds a tool mid-session was invisible until a restart (#7117).
   */
  private subscribeToToolListChanges(): void {
    this.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
      logger.debug(`${this.getLogPrefix()} Server reported a changed tool list`);
      // Stamps the MCP Apps per-tool metadata caches (resourceUri, visibility) as stale; createdAt
      // alone cannot see a list change on a still-live connection.
      this.toolListVersion += 1;
      await this.refreshToolList();
    });
  }

  /** Queues a live tool-list refresh through the same coalescing path used by notifications. */
  public async refreshToolList(signal?: AbortSignal): Promise<MCPToolsSnapshot | undefined> {
    signal?.throwIfAborted();
    this.toolListChangeGeneration++;
    this.clearToolListRefreshRetry();
    this.startToolListRefresh(signal);
    const refresh = this.toolListRefreshPromise;
    if (signal && refresh) {
      await this.settlesBefore(refresh, undefined, signal);
      signal.throwIfAborted();
    }
    const snapshot = (await refresh) ?? this.suspendedToolListSnapshot;
    return snapshot && requireToolsSnapshot(snapshot);
  }

  private clearToolListRefreshRetry(): void {
    if (this.toolListRefreshRetryTimer) {
      clearTimeout(this.toolListRefreshRetryTimer);
      this.toolListRefreshRetryTimer = null;
    }
  }

  private scheduleToolListRefreshRetry(): void {
    if (
      this.isDisposed ||
      this.toolListRefreshSuspended ||
      this.connectionState !== 'connected' ||
      this.toolListRefreshRetryTimer
    ) {
      return;
    }

    const delay = Math.min(
      TOOL_LIST_REFRESH_RETRY_BASE_MS * Math.pow(2, Math.max(0, this.toolListRefreshFailures - 1)),
      TOOL_LIST_REFRESH_RETRY_MAX_MS,
    );
    this.toolListRefreshRetryTimer = setTimeout(() => {
      this.toolListRefreshRetryTimer = null;
      this.startToolListRefresh();
    }, delay);
    this.toolListRefreshRetryTimer.unref?.();
  }

  private startToolListRefresh(signal?: AbortSignal): void {
    if (
      this.isDisposed ||
      this.toolListRefreshSuspended ||
      this.connectionState !== 'connected' ||
      this.toolListRefreshPromise
    ) {
      return;
    }

    this.toolListRefreshPromise = this.refreshChangedTools(signal).finally(() => {
      this.toolListRefreshPromise = null;
      if (
        !this.toolListRefreshRetryTimer &&
        this.handledToolListChangeGeneration < this.toolListChangeGeneration
      ) {
        this.startToolListRefresh();
      }
    });
  }

  private async refreshChangedTools(signal?: AbortSignal): Promise<MCPToolsSnapshot | undefined> {
    const refreshEpoch = this.toolListRefreshEpoch;
    let latestSnapshot: MCPToolsSnapshot | undefined;
    while (this.handledToolListChangeGeneration < this.toolListChangeGeneration) {
      const targetGeneration = this.toolListChangeGeneration;
      const snapshot: MCPToolsSnapshot =
        this.client.getServerCapabilities()?.tools == null
          ? { tools: [], complete: true, ...(await this.reserveToolsPublicationRevision()) }
          : await this.readToolsSnapshot(undefined, signal);
      if (signal?.aborted) {
        if (this.toolListRefreshEpoch === refreshEpoch) {
          this.toolListRefreshSuspended = true;
        }
        return;
      }
      latestSnapshot = snapshot;
      if (
        this.toolListRefreshEpoch !== refreshEpoch ||
        this.toolListRefreshSuspended ||
        this.connectionState !== 'connected'
      ) {
        return;
      }
      /** Publishing unordered would drop this catalog silently; retry until it can be ordered. */
      if (!snapshot.complete || snapshot.orderingUnavailable) {
        if (
          snapshot.authenticationError &&
          (isMCPInitializationError(snapshot.authenticationError) ||
            this.directBearerRecoveryEnabled)
        ) {
          /** Keep the stopped queue's outcome available to an owner arriving after settlement. */
          this.suspendedToolListSnapshot = snapshot;
          this.toolListRefreshSuspended = true;
          return snapshot;
        }
        this.toolListRefreshFailures++;
        this.scheduleToolListRefreshRetry();
        return;
      }

      this.toolListRefreshFailures = 0;
      this.handledToolListChangeGeneration = targetGeneration;
      this.publishedToolListSnapshot = {
        epoch: refreshEpoch,
        generation: targetGeneration,
        tools: snapshot.tools,
        publicationRevision: snapshot.publicationRevision,
      };
      this.dispatchToolsChanged(snapshot.tools, snapshot.publicationRevision);
    }
    return latestSnapshot;
  }

  private dispatchToolsChanged(
    tools: MCPListToolsResult['tools'],
    publicationRevision?: string,
  ): void {
    try {
      this.emit('toolsChanged', tools, publicationRevision);
    } catch (error) {
      logger.error(`${this.getLogPrefix()} Failed to dispatch refreshed tools:`, error);
    }
  }

  async connectClient(): Promise<void> {
    if (this.connectionState === 'connected') {
      return;
    }

    if (this.connectPromise) {
      return this.connectPromise;
    }

    if (this.shouldStopReconnecting) {
      return;
    }

    if (this.isCircuitOpen()) {
      this.connectionState = 'error';
      this.emit('connectionChange', 'error');
      throw new Error(`${this.getLogPrefix()} Circuit breaker is open, connection attempt blocked`);
    }

    this.emit('connectionChange', 'connecting');

    this.connectPromise = (async () => {
      let rejectedCredentialSetId = this.oauthTokens?.credential_set_id ?? null;
      try {
        if (this.transport) {
          try {
            await this.terminateStreamableSession();
            await this.client.close();
          } catch {
            logger.warn(`${this.getLogPrefix()} Error closing connection`);
          }
          this.transport = null;
          await this.closeAgents();
        }

        this.transport = await runOutsideTracing(() => this.constructTransport(this.options));
        rejectedCredentialSetId = this.getOAuthCredentialSetId();
        /** `dispose()` can land while the transport is still being constructed — it finds nothing
         *  to close and returns, so without this check the attempt would go on to connect and
         *  leave a live connection on a disposed object. Ownership of teardown is ours here. */
        if (await this.abandonIfDisposed()) {
          return;
        }
        this.patchTransportSend();

        const connectTimeout = this.options.initTimeout ?? DEFAULT_INIT_TIMEOUT;
        await runOutsideTracing(() =>
          withTimeout(
            this.client.connect(this.transport!),
            connectTimeout,
            `Connection timeout after ${connectTimeout}ms`,
          ),
        );

        if (await this.abandonIfDisposed()) {
          return;
        }
        this.setupTransportOnMessageHandler();
        this.connectionState = 'connected';
        this.emit('connectionChange', 'connected');
        this.reconnectAttempts = 0;
        this.resetFailedRounds();
        if (this.oauthRecovery) {
          MCPConnection.decrementCycleCount(this.serverName);
          this.oauthRecovery = false;
          logger.debug(
            `${this.getLogPrefix()} OAuth recovery: decremented cycle count after successful reconnect`,
          );
        }
      } catch (error) {
        if (this.isDisposed) {
          throw error;
        }
        if (this.requestAuthorization.error !== undefined) {
          this.lastConnectionCheckError = this.requestAuthorization.error;
          this.connectionState = 'error';
          this.emit('connectionChange', 'error');
          throw this.requestAuthorization.error;
        }
        // Check if it's a rate limit error - stop immediately to avoid making it worse
        if (this.isRateLimitError(error)) {
          /**
           * Rate limiting sets shouldStopReconnecting to prevent hammering the server.
           * This is a permanent block for this connection instance - the connection
           * must be recreated (e.g., by user re-initiating) to retry after rate limit lifts.
           *
           * We throw here (unlike handleReconnection which returns silently) because:
           * - connectClient() is a public API - callers expect async errors to throw
           * - Other errors in this catch block also throw for consistency
           * - handleReconnection is private/internal error recovery, different context
           */
          logger.warn(`${this.getLogPrefix()} Rate limited (429), stopping connection attempts`);
          this.shouldStopReconnecting = true;
          this.connectionState = 'error';
          this.emit('connectionChange', 'error');
          throw error;
        }

        // Check if it's an OAuth authentication error
        if (
          this.directBearerRecoveryEnabled
            ? isMCPTransportAuthenticationError(error)
            : isOAuthAuthenticationError(error)
        ) {
          logger.warn(`${this.getLogPrefix()} OAuth authentication required`);
          this.oauthRequired = true;
          const serverUrl = this.url;
          logger.debug(`${this.getLogPrefix()} OAuth server URL state`, {
            hasServerUrl: Boolean(serverUrl),
          });

          const oauthTimeout = mcpConfig.OAUTH_HANDLING_TIMEOUT;
          /** Promise that will resolve when OAuth is handled */
          const oauthHandledPromise = new Promise<void>((resolve, reject) => {
            let timeoutId: NodeJS.Timeout | null = null;
            let oauthHandledListener: (() => void) | null = null;
            let oauthFailedListener: ((error: Error) => void) | null = null;

            /** Cleanup function to remove listeners and clear timeout */
            const cleanup = () => {
              if (timeoutId) {
                clearTimeout(timeoutId);
              }
              if (oauthHandledListener) {
                this.off('oauthHandled', oauthHandledListener);
              }
              if (oauthFailedListener) {
                this.off('oauthFailed', oauthFailedListener);
              }
            };

            // Success handler
            oauthHandledListener = () => {
              cleanup();
              resolve();
            };

            // Failure handler
            oauthFailedListener = (error: Error) => {
              cleanup();
              reject(error);
            };

            // Timeout handler
            timeoutId = setTimeout(() => {
              cleanup();
              reject(new Error(`OAuth handling timeout after ${oauthTimeout}ms`));
            }, oauthTimeout);

            // Listen for both success and failure events
            this.once('oauthHandled', oauthHandledListener);
            this.once('oauthFailed', oauthFailedListener);
          });

          // Emit the event
          this.emit('oauthRequired', {
            rejectedCredentialSetId,
            serverName: this.serverName,
            error,
            serverUrl,
            userId: this.userId,
          });

          try {
            // Wait for OAuth to be handled
            await oauthHandledPromise;
            this.oauthRequired = false;
            this.oauthRecovery = true;
            logger.info(
              `${this.getLogPrefix()} OAuth handled successfully, connection will be retried`,
            );
            return;
          } catch {
            // OAuth failed or timed out
            this.oauthRequired = false;
            logger.error(`${this.getLogPrefix()} OAuth handling failed`);
            // Re-throw the original authentication error
            throw error;
          }
        }

        this.connectionState = 'error';
        this.emit('connectionChange', 'error');
        this.recordFailedRound();
        throw error;
      } finally {
        this.connectPromise = null;
      }
    })();

    return this.connectPromise;
  }

  /**
   * Tears down a transport this attempt created after the connection was already disposed.
   * Returns whether the caller should abandon the rest of the connect sequence.
   */
  private async abandonIfDisposed(): Promise<boolean> {
    if (!this.isDisposed) {
      return false;
    }
    logger.debug(`${this.getLogPrefix()} Disposed mid-connect; discarding the transport it opened`);
    const transport = this.transport;
    this.transport = null;
    /** Closing the client only closes a transport the client has already adopted, which it has
     *  not when disposal beat `client.connect()`. Close the transport itself first, or the
     *  session this attempt opened outlives the connection that owned it. */
    try {
      await transport?.close();
    } catch {
      // Ignore cleanup errors
    }
    try {
      await this.client.close();
    } catch {
      // Ignore cleanup errors
    }
    return true;
  }

  private patchTransportSend(): void {
    if (!this.transport) {
      return;
    }

    const originalSend = this.transport.send.bind(this.transport);
    this.transport.send = async (msg) => {
      if ('result' in msg && !('method' in msg) && Object.keys(msg.result ?? {}).length === 0) {
        if (Date.now() - this.lastPingTime < FIVE_MINUTES) {
          throw new Error('Empty result');
        }
        this.lastPingTime = Date.now();
      }
      const method = 'method' in msg ? msg.method : undefined;
      const id = 'id' in msg ? msg.id : undefined;
      if (
        this.resolveRequestHeaders &&
        method &&
        (typeof id === 'string' || typeof id === 'number')
      ) {
        const scope: MCPRequestScopeRunner | undefined = captureMCPRequestScope(() => {
          if (this.sdkRequestScopes.get(id) === scope) this.sdkRequestScopes.delete(id);
        });
        if (scope) this.sdkRequestScopes.set(id, scope);
      }
      if ('method' in msg && msg.method === 'notifications/cancelled' && msg.params) {
        const cancelledId = msg.params.requestId;
        if (typeof cancelledId === 'string' || typeof cancelledId === 'number') {
          const scope = this.sdkRequestScopes.get(cancelledId);
          if (scope) return scope(() => originalSend(msg));
        }
      }
      if (method === 'tools/call') {
        await assertToolApprovalTransportEpoch(
          this.serverName,
          this.oauthTokens?.credential_set_id ?? null,
        );
      }
      logger.debug(
        `${this.getLogPrefix()} Transport sending: method=${method ?? 'response'} id=${id ?? 'none'}`,
      );
      // Only initialization opens an autonomous stream; cancellation retains its caller cutoff.
      return method === 'notifications/initialized'
        ? outsideMCPRequestScope(() => originalSend(msg))
        : originalSend(msg);
    };
  }

  private setupTransportOnMessageHandler(): void {
    if (!this.transport?.onmessage) {
      return;
    }

    const sdkHandler = this.transport.onmessage;
    this.transport.onmessage = (msg) => {
      const method = 'method' in msg ? msg.method : undefined;
      const id = 'id' in msg ? (msg as { id: string | number | null }).id : undefined;
      logger.debug(
        `${this.getLogPrefix()} Transport received: method=${method ?? 'response'} id=${id ?? 'none'}`,
      );
      sdkHandler(msg);
    };
  }

  async connect(): Promise<void> {
    try {
      /**
       * Persistent connections preserve cycle tracking across reconnects so the
       * circuit breaker can detect storms. Request-scoped connections are
       * intentionally short-lived per tool call, so their clean lifecycle should
       * not consume the reconnect-storm cycle budget.
       */
      await this.disconnect(this.ephemeralConnection);
      await this.connectClient();
      if (!(await this.isConnected())) {
        throw new Error('Connection not established');
      }
    } catch (error) {
      logger.error(`${this.getLogPrefix()} Connection failed`);
      throw error;
    }
  }

  private setupTransportErrorHandlers(transport: Transport): void {
    this.reportedStandaloneSseConflict = false;
    const transportCredentialSetId = this.oauthTokens?.credential_set_id ?? null;
    this.transportCredentialSetId = transportCredentialSetId;

    transport.onerror = (error) => {
      if (this.resolveRequestHeaders && isOwnedAbortError(error, getMCPDispatchSignal())) {
        logger.debug(`${this.getLogPrefix()} Request cancelled before dispatch`);
        return;
      }
      const rawMessage =
        error && typeof error === 'object' ? ((error as { message?: string }).message ?? '') : '';

      /**
       * The MCP SDK's StreamableHTTPClientTransport fires onerror for SSE GET stream
       * disconnects but also handles reconnection internally via _scheduleReconnection.
       * Escalating these to a full transport rebuild creates a redundant reconnection
       * loop. Log at debug level and let the SDK recover the GET stream on its own.
       *
       * "Maximum reconnection attempts … exceeded" means the SDK gave up — that one
       * must fall through so our higher-level reconnection takes over.
       */
      if (
        rawMessage.startsWith(SDK_SSE_STREAM_DISCONNECTED) ||
        rawMessage.startsWith(SDK_SSE_RECONNECT_FAILED)
      ) {
        logger.debug(`${this.getLogPrefix()} SDK SSE stream recovery in progress`);
        return;
      }

      /**
       * A stale server-side stream can only be cleared by rebuilding the session, so escalate
       * on the first report and treat the rest as the echo they are: the SDK keeps retrying the
       * `GET` on its own schedule, and each of those retries conflicts for the same reason while
       * the rebuild triggered here is already running.
       */
      if (isStandaloneSseConflict(error)) {
        if (this.reportedStandaloneSseConflict) {
          logger.debug(
            `${this.getLogPrefix()} SSE stream still conflicting; session rebuild already underway`,
          );
          return;
        }

        this.reportedStandaloneSseConflict = true;
        logger.warn(
          `${this.getLogPrefix()} SSE stream conflicted with a stale server-side stream for this ` +
            `session (409). Rebuilding the session; no action needed.`,
        );
        this.emit('connectionChange', 'error');
        return;
      }

      /**
       * The SDK announcing it is out of retries normally has to fall through so our reconnection
       * takes over, but adds nothing once a conflict rebuild is already running — that rebuild is
       * what exhausted the retries, and it is the recovery.
       */
      if (this.reportedStandaloneSseConflict && rawMessage.startsWith(SDK_SSE_RETRIES_EXHAUSTED)) {
        logger.debug(
          `${this.getLogPrefix()} SDK reconnection budget exhausted; session rebuild already underway`,
        );
        return;
      }

      const {
        message: errorMessage,
        code: errorCode,
        isProxyHint,
        isTransient,
      } = extractSSEErrorMessage(error);

      if (errorCode === 400 || errorCode === 404 || errorCode === 405 || errorCode === 406) {
        const hasSession =
          'sessionId' in transport &&
          (transport as { sessionId?: string }).sessionId != null &&
          (transport as { sessionId?: string }).sessionId !== '';

        if (!hasSession && errorMessage.toLowerCase().includes('failed to open sse stream')) {
          logger.warn(
            `${this.getLogPrefix()} SSE stream not available (${errorCode}), no session. Ignoring.`,
          );
          return;
        }

        if (hasSession) {
          logger.warn(
            `${this.getLogPrefix()} ${errorCode} with active session — session lost, triggering reconnection.`,
          );
        }
      }

      // Check if it's an OAuth authentication error
      if (
        this.directBearerRecoveryEnabled
          ? isMCPTransportAuthenticationError(error)
          : isOAuthAuthenticationError(error)
      ) {
        logger.warn(`${this.getLogPrefix()} OAuth authentication error detected`);
        this.lastConnectionCheckError = error;
        this.lastConnectionCheckCredentialSetId = transportCredentialSetId;
        this.connectionState = 'error';
        this.emit('oauthError', error);
        return;
      }

      /**
       * Log with enhanced context for debugging.
       * All transport.onerror events are logged as errors to preserve stack traces.
       * isTransient indicates whether auto-reconnection is expected to succeed.
       *
       * The MCP SDK's SseError extends Error and includes:
       * - code: HTTP status code or eventsource error code
       * - event: The original eventsource ErrorEvent
       * - stack: Full stack trace
       */
      const errorContext: Record<string, unknown> = {
        code: errorCode,
        isTransient,
      };

      if (isProxyHint) {
        errorContext.hint = 'Check Nginx/proxy configuration for SSE endpoints';
      }

      const errorLabel = isTransient
        ? 'Transport error (transient, will reconnect)'
        : 'Transport error (may require manual intervention)';

      logger.error(`${this.getLogPrefix()} ${errorLabel}`, errorContext);

      this.emit('connectionChange', 'error');
    };
  }

  private async closeAgents(force = false): Promise<void> {
    const logPrefix = this.getLogPrefix();
    const closing = this.agents.map((agent) =>
      (force ? agent.destroy() : agent.close()).catch(() => {
        logger.debug(`${logPrefix} Agent close error (non-fatal)`);
      }),
    );
    this.agents = [];
    await Promise.all(closing);
  }

  /**
   * Ends a Streamable HTTP session with the spec-mandated `HTTP DELETE` before
   * the transport is discarded. Stateful MCP servers (the SDK default) keep each
   * session's transport, tasks, and buffers in memory with no TTL, so without an
   * explicit DELETE every idle eviction, reconnect, or restart leaks one
   * server-side session. Must run before `client.close()`, which aborts the
   * transport's controller and would cancel the in-flight DELETE.
   *
   * `terminateSession()` no-ops when there is no session id and already tolerates
   * a 405 (server opts out of termination). Any other failure is non-fatal to
   * teardown, so it is bounded by a timeout and swallowed.
   *
   * The transport's `onerror` is detached first: on any non-405 failure (the
   * session already expired, a network error, or `client.close()` aborting the
   * request after the timeout) `terminateSession()` invokes `onerror` before
   * rejecting. Left attached, our handler would emit `connectionChange('error')`
   * and trigger `handleReconnection()`, reopening the connection we are tearing
   * down and re-leaking the session. The transport is discarded right after, so
   * clearing the handler is safe.
   */
  private async terminateStreamableSession(): Promise<void> {
    if (!(this.transport instanceof StreamableHTTPClientTransport)) {
      return;
    }
    this.transport.onerror = undefined;
    try {
      await withTimeout(
        this.transport.terminateSession(),
        SESSION_TERMINATION_TIMEOUT,
        `Streamable HTTP session termination timed out after ${SESSION_TERMINATION_TIMEOUT}ms`,
      );
    } catch {
      logger.debug(`${this.getLogPrefix()} Error terminating streamable HTTP session`);
    }
  }

  public async disconnect(resetCycleTracking = true, forceAgentClose = false): Promise<void> {
    let failure: unknown;
    try {
      // Include dispatches whose rejection arrives after the completion cutoff.
      if (this.requestAuthorization.closed) {
        while (this.pendingRequests.size > 0) await Promise.allSettled(this.pendingRequests);
      }
      if (this.resolveRequestHeaders?.settle) await this.resolveRequestHeaders.settle();
    } catch (error) {
      failure = error;
    }
    this.toolListRefreshEpoch++;
    this.suspendedToolListSnapshot = undefined;
    this.toolListRefreshSuspended = true;
    this.clearToolListRefreshRetry();
    try {
      if (this.transport) {
        await this.terminateStreamableSession();
        await this.client.close();
        this.transport = null;
      }
      if (this.connectionState !== 'disconnected') {
        this.connectionState = 'disconnected';
        this.emit('connectionChange', 'disconnected');
      }
    } catch (error) {
      failure ??= error;
    } finally {
      await this.closeAgents(forceAgentClose);
      this.connectPromise = null;
      if (!resetCycleTracking) this.recordCycle();
    }
    // Fenced evidence still fails, but cannot skip DELETE/client/dispatcher teardown.
    if (failure != null) throw failure;
  }

  /** Permanently tears down a connection that will never be reused. */
  public async dispose(): Promise<void> {
    this.isDisposed = true;
    this.requestAuthorization.closed = true;
    // Failed-init teardown must cancel pre-dispatch waits before joining requests.
    // Network responses and durable rejection admission keep their own drain barrier.
    this.requestAuthorizationController?.abort(new MCPRequestQuiescedError());
    this.clearToolListRefreshRetry();
    this.shouldStopReconnecting = true;
    this.removeAllListeners();
    await this.disconnect(true, true);
  }

  async fetchResources(): Promise<t.MCPResource[]> {
    try {
      const { resources } = await this.client.listResources();
      return resources;
    } catch (error) {
      this.emitError(error, 'Failed to fetch resources');
      return [];
    }
  }

  /**
   * Fetches the server's tools, following MCP `tools/list` cursor pagination so a
   * server that spans multiple pages (e.g. an aggregating gateway exposing many
   * tools) is loaded in full instead of being truncated to the first page.
   *
   * Pagination is bounded by {@link mcpConfig.TOOLS_LIST_MAX_PAGES}, aggregate
   * tool count, approximate serialized size, elapsed time, and a repeated-cursor
   * guard. Transient failures preserve partial pages; fatal initialization
   * failures propagate to the owning run.
   */
  async fetchTools(): Promise<MCPListToolsResult['tools']> {
    return (await this.fetchToolsSnapshot()).tools;
  }

  /**
   * Fetches a bounded tool snapshot while preserving whether every requested page succeeded.
   * Notification refreshes use `complete` to avoid replacing a known-good cache with an empty or
   * partial list after a transient `tools/list` failure.
   *
   * @param deadlineMs Absolute epoch-ms cap for a caller working to a fixed budget. Pagination
   * stops at whichever comes first, this or `TOOLS_LIST_TIMEOUT_MS`, and the partial result is
   * returned as incomplete so it is never published as an authoritative catalog.
   * @param signal Cancels the in-flight `tools/list` request itself, not just the wait for it —
   * the SDK raises an abort from `request()` and the failed page ends pagination gracefully.
   */
  public async fetchToolsSnapshot(
    deadlineMs?: number,
    signal?: AbortSignal,
  ): Promise<MCPToolsSnapshot> {
    return requireToolsSnapshot(await this.readToolsSnapshot(deadlineMs, signal));
  }

  /** Refresh workers retain failure evidence without publishing or retrying a fatal denial. */
  private async readToolsSnapshot(
    deadlineMs?: number,
    signal?: AbortSignal,
  ): Promise<MCPToolsSnapshot> {
    const maxPages = mcpConfig.TOOLS_LIST_MAX_PAGES;
    const maxTools = mcpConfig.TOOLS_LIST_MAX_TOOLS;
    const maxBytes = mcpConfig.TOOLS_LIST_MAX_BYTES;
    /** A spent budget ends the fetch before the reservation below spends cache round trips on an
     *  ordering this incomplete result can never publish under. */
    if ((deadlineMs != null && Date.now() >= deadlineMs) || signal?.aborted === true) {
      this.warnToolsListBudgetExceeded('time', 0);
      return { tools: [], complete: false };
    }
    /** Reserved before the first page so the resulting catalog can never outrank one published
     * from a `tools/list` that started later. Every app-level publisher reads its ordering off
     * the snapshot it received, which is the only way to know when the data was actually read. */
    const ordering = await this.reserveToolsPublicationRevision();
    const budgetDeadline = Date.now() + mcpConfig.TOOLS_LIST_TIMEOUT_MS;
    const deadline = deadlineMs != null ? Math.min(budgetDeadline, deadlineMs) : budgetDeadline;
    const allTools: MCPListToolsResult['tools'] = [];
    const seenCursors = new Set<string>();
    let cursor: string | undefined;
    let totalBytes = 0;
    const snapshot = (complete: boolean, authenticationError?: unknown): MCPToolsSnapshot => ({
      tools: allTools,
      complete,
      ...(authenticationError != null && { authenticationError }),
      ...ordering,
    });

    for (let page = 1; page <= maxPages; page++) {
      const exhaustedBudget = getToolsListBudgetExceededReason(
        allTools.length,
        totalBytes,
        maxTools,
        maxBytes,
      );
      if (exhaustedBudget != null) {
        this.warnToolsListBudgetExceeded(exhaustedBudget, allTools.length);
        return snapshot(true);
      }

      const remainingMs = deadline - Date.now();
      if (remainingMs <= 0) {
        this.warnToolsListBudgetExceeded('time', allTools.length);
        return snapshot(false);
      }

      let result: MCPListToolsResult;
      try {
        result = await this.listToolsPage(cursor, remainingMs, signal);
      } catch (cause) {
        let error = cause;
        if (
          this.resolveRequestHeaders?.recordFailure &&
          (isMCPInitializationError(error) || isMCPTransportAuthenticationError(error))
        ) {
          try {
            await this.failRequestAuthorization(error);
          } catch (reported) {
            error = reported;
          }
        }
        if (isMCPInitializationError(error)) {
          // The SDK may stop the stream before refresh can retain this denial.
          this.suspendedToolListSnapshot = snapshot(false, error);
          this.toolListRefreshSuspended = true;
          return this.suspendedToolListSnapshot;
        }
        /** Request failed mid-pagination: preserve partial pages for transient errors. */
        return snapshot(false, isMCPTransportAuthenticationError(error) ? error : undefined);
      }

      for (const tool of result.tools) {
        if (allTools.length >= maxTools) {
          this.warnToolsListBudgetExceeded('tool count', allTools.length);
          return snapshot(true);
        }

        const toolBytes = getApproximateToolBytes(tool);
        if (totalBytes + toolBytes > maxBytes) {
          this.warnToolsListBudgetExceeded('size', allTools.length);
          return snapshot(true);
        }

        allTools.push(tool);
        totalBytes += toolBytes;
      }

      const { nextCursor } = result;
      if (nextCursor == null) {
        return snapshot(true);
      }

      const nextPageBudget = getToolsListBudgetExceededReason(
        allTools.length,
        totalBytes,
        maxTools,
        maxBytes,
      );
      if (nextPageBudget != null) {
        this.warnToolsListBudgetExceeded(nextPageBudget, allTools.length);
        return snapshot(true);
      }

      if (seenCursors.has(nextCursor)) {
        logger.warn(
          `${this.getLogPrefix()} MCP server returned a repeated tools/list cursor; stopping pagination after ${page} page(s).`,
        );
        return snapshot(false);
      }

      seenCursors.add(nextCursor);
      cursor = nextCursor;
    }

    logger.warn(
      `${this.getLogPrefix()} Reached the tools/list pagination limit of ${maxPages} page(s); some tools may be omitted. Set MCP_TOOLS_LIST_MAX_PAGES higher if this server legitimately exposes more.`,
    );
    return snapshot(true);
  }

  /**
   * Allocates app-catalog ordering. A reservation failure must not fail the request that asked
   * for the tools, so it is reported on the snapshot for publishers to retry on instead.
   */
  public async reserveToolsPublicationRevision(): Promise<{
    publicationRevision?: string;
    orderingUnavailable?: boolean;
  }> {
    try {
      return {
        publicationRevision: await reserveMCPToolsChangedRevision({
          serverName: this.serverName,
          serverConfig: this.options,
          userId: this.userId,
          capabilityProfile: this.capabilityProfile,
        }),
      };
    } catch (error) {
      logger.warn(`${this.getLogPrefix()} Failed to reserve tool-list publication order:`, error);
      return { orderingUnavailable: true };
    }
  }

  /**
   * Returns a complete snapshot that cannot precede a concurrent `list_changed` refresh.
   * If the notification refresh cannot complete, the caller receives an incomplete snapshot
   * instead of publishing a request result that may already be stale.
   *
   * @param deadlineMs Absolute epoch-ms cap; see `fetchToolsSnapshot`. It also bounds the wait
   * for a concurrent refresh, so a caller on a budget is never held by another caller's fetch.
   * @param signal Cancels this caller's own `tools/list` requests; see `fetchToolsSnapshot`. A
   * concurrent refresh is shared work and is never aborted on one caller's behalf.
   */
  public async fetchOrderedToolsSnapshot(
    deadlineMs?: number,
    signal?: AbortSignal,
  ): Promise<MCPToolsSnapshot> {
    const startEpoch = this.toolListRefreshEpoch;
    const startGeneration = this.toolListChangeGeneration;
    const snapshot = await this.fetchToolsSnapshot(deadlineMs, signal);

    if (
      startEpoch === this.toolListRefreshEpoch &&
      startGeneration === this.toolListChangeGeneration
    ) {
      return snapshot;
    }

    while (
      startEpoch === this.toolListRefreshEpoch &&
      this.handledToolListChangeGeneration < this.toolListChangeGeneration
    ) {
      if ((deadlineMs != null && Date.now() >= deadlineMs) || signal?.aborted === true) {
        break;
      }
      this.startToolListRefresh();
      const refresh = this.toolListRefreshPromise;
      if (!refresh) {
        break;
      }
      /** The refresh runs on the connection's own budget, not the caller's, so a refresh already
       *  in flight can outlast this deadline — and a cancelled caller must stop waiting even
       *  though the shared refresh itself is never aborted on one caller's behalf. Stop waiting
       *  rather than adopting its budget; it keeps running for whoever else wants it and this
       *  caller reports an incomplete read. */
      if (deadlineMs == null && signal == null) {
        await refresh;
      } else if (!(await this.settlesBefore(refresh, deadlineMs, signal))) {
        break;
      }
      if (this.toolListRefreshRetryTimer) {
        break;
      }
    }

    const published = this.publishedToolListSnapshot;
    if (
      published?.epoch === this.toolListRefreshEpoch &&
      published.generation === this.toolListChangeGeneration &&
      this.handledToolListChangeGeneration === this.toolListChangeGeneration
    ) {
      /** Ordering travels with the data: this is the refresh's catalog, so it must publish under
       * the refresh's revision rather than the one reserved for the superseded fetch above. */
      return {
        tools: published.tools,
        complete: true,
        publicationRevision: published.publicationRevision,
      };
    }

    if (
      startEpoch === this.toolListRefreshEpoch &&
      !signal?.aborted &&
      (deadlineMs == null || Date.now() < deadlineMs) &&
      this.suspendedToolListSnapshot
    ) {
      return requireToolsSnapshot(this.suspendedToolListSnapshot);
    }

    return { tools: [], complete: false };
  }

  /** Waits for `promise` only until `deadlineMs` or an abort, reporting whether it settled first. */
  private async settlesBefore(
    promise: Promise<unknown>,
    deadlineMs?: number,
    signal?: AbortSignal,
  ): Promise<boolean> {
    if (signal?.aborted === true) {
      return false;
    }
    let timer: NodeJS.Timeout | undefined;
    let onAbort: (() => void) | undefined;
    const interrupted = new Promise<false>((resolve) => {
      if (deadlineMs != null) {
        timer = setTimeout(() => resolve(false), Math.max(0, deadlineMs - Date.now()));
        timer.unref?.();
      }
      if (signal != null) {
        onAbort = () => resolve(false);
        signal.addEventListener('abort', onAbort, { once: true });
      }
    });
    try {
      return await Promise.race([promise.then(() => true), interrupted]);
    } finally {
      clearTimeout(timer);
      if (onAbort != null) {
        signal?.removeEventListener('abort', onAbort);
      }
    }
  }

  private warnToolsListBudgetExceeded(reason: string, toolCount: number): void {
    logger.warn(
      `${this.getLogPrefix()} Stopping tools/list pagination because the ${reason} budget was reached after ${toolCount} tool(s).`,
    );
  }

  /** Fetches one `tools/list` page. The public snapshot interface classifies any rejection. */
  private async listToolsPage(
    cursor: string | undefined,
    timeoutMs: number,
    signal?: AbortSignal,
  ): Promise<MCPListToolsResult> {
    try {
      return await this.withRequestSignal(signal, (requestSignal) =>
        this.client.listTools(cursor != null ? { cursor } : undefined, {
          timeout: timeoutMs,
          maxTotalTimeout: timeoutMs,
          signal: requestSignal,
        }),
      );
    } catch (error) {
      this.emitError(error, 'Failed to fetch tools');
      throw error;
    }
  }

  async fetchPrompts(): Promise<t.MCPPrompt[]> {
    try {
      const { prompts } = await this.client.listPrompts();
      return prompts;
    } catch (error) {
      this.emitError(error, 'Failed to fetch prompts');
      return [];
    }
  }

  /**
   * @param signal Aborts the in-flight verification request (ping or its fallback) so a caller on
   * a budget is not held for the probe's own SDK timeout. An aborted probe reports `false` for
   * this caller only; it never mutates connection state, so a shared connection stays usable.
   */
  public async isConnected(signal?: AbortSignal): Promise<boolean> {
    // First check if we're in a connected state
    if (this.connectionState !== 'connected') {
      return false;
    }

    // If we recently checked, skip expensive verification
    const now = Date.now();
    if (now - this.lastConnectionCheckAt < mcpConfig.CONNECTION_CHECK_TTL) {
      return true;
    }
    let probeCredentialSetId = this.getOAuthCredentialSetId();
    const previousCheckAt = this.lastConnectionCheckAt;
    this.lastConnectionCheckAt = now;
    this.lastConnectionCheckError = undefined;
    this.lastConnectionCheckCredentialSetId = undefined;
    /** An aborted probe answered nothing: restore the TTL stamp so the next caller probes for
     *  real, instead of a dead shared connection reading as healthy for the whole TTL window. */
    const probeAborted = (): boolean => signal?.aborted === true;
    const abandonProbe = (): false => {
      this.lastConnectionCheckAt = previousCheckAt;
      logger.debug(`${this.getLogPrefix()} Health probe aborted by caller signal`);
      return false;
    };

    try {
      // Try ping first as it's the lightest check
      await this.withRequestSignal(signal, (requestSignal) =>
        this.client.ping({ signal: requestSignal }),
      );
      return this.connectionState === 'connected';
    } catch (error) {
      if (probeAborted()) {
        return abandonProbe();
      }
      // Check if the error is because ping is not supported (method not found)
      const pingUnsupported =
        error instanceof Error &&
        ((error as Error)?.message.includes('-32601') ||
          (error as Error)?.message.includes('-32602') ||
          (error as Error)?.message.includes('invalid method ping') ||
          (error as Error)?.message.includes('Unsupported method: ping') ||
          (error as Error)?.message.includes('method not found'));

      if (!pingUnsupported) {
        this.lastConnectionCheckError = error;
        this.lastConnectionCheckCredentialSetId = probeCredentialSetId;
        logger.error(`${this.getLogPrefix()} Ping failed`);
        return false;
      }

      // Ping is not supported by this server, try an alternative verification
      logger.debug(
        `${this.getLogPrefix()} Server does not support ping method, verifying connection with capabilities`,
      );

      try {
        probeCredentialSetId = this.getOAuthCredentialSetId();
        // Get server capabilities to verify connection is truly active
        const capabilities = this.client.getServerCapabilities();

        // If we have capabilities, try calling a supported method to verify connection
        if (capabilities?.tools) {
          await this.withRequestSignal(signal, (requestSignal) =>
            this.client.listTools(undefined, { signal: requestSignal }),
          );
          return this.connectionState === 'connected';
        } else if (capabilities?.resources) {
          await this.withRequestSignal(signal, (requestSignal) =>
            this.client.listResources(undefined, { signal: requestSignal }),
          );
          return this.connectionState === 'connected';
        } else if (capabilities?.prompts) {
          await this.withRequestSignal(signal, (requestSignal) =>
            this.client.listPrompts(undefined, { signal: requestSignal }),
          );
          return this.connectionState === 'connected';
        } else {
          // No capabilities to test, but we're in connected state and initialization succeeded
          logger.debug(
            `${this.getLogPrefix()} No capabilities to test, assuming connected based on state`,
          );
          return this.connectionState === 'connected';
        }
      } catch (capabilityError) {
        if (probeAborted()) {
          return abandonProbe();
        }
        // If capability check fails, the connection is likely broken
        this.lastConnectionCheckError = capabilityError;
        this.lastConnectionCheckCredentialSetId = probeCredentialSetId;
        logger.error(`${this.getLogPrefix()} Connection verification failed`);
        return false;
      }
    }
  }

  /** Identifies the installed transport credential; pending replacement tokens are not sent yet. */
  public getOAuthCredentialSetId(): string | null {
    return this.transport
      ? this.transportCredentialSetId
      : (this.oauthTokens?.credential_set_id ?? null);
  }

  public setOAuthTokens(tokens: MCPOAuthTokens): void {
    this.oauthTokens = tokens;
  }

  /** Whether this connection's resolved runtime config uses MCP OAuth. */
  public usesOAuth(): boolean {
    return isOAuthServer(this.options);
  }

  public isOAuthAuthenticationError(error: unknown): boolean {
    return isOAuthAuthenticationError(error);
  }

  public getLastConnectionCheckCredentialSetId(): string | null | undefined {
    return this.lastConnectionCheckCredentialSetId;
  }

  public getLastConnectionCheckError(): unknown {
    return this.lastConnectionCheckError;
  }

  /**
   * Check if this connection is stale compared to config update time.
   * A connection is stale if it was created before the config was updated.
   *
   * @param configUpdatedAt - Unix timestamp (ms) when config was last updated
   * @returns true if connection was created before config update, false otherwise
   */
  public isStale(configUpdatedAt: number): boolean {
    return this.createdAt < configUpdatedAt;
  }

  /**
   * Checks if an error indicates rate limiting (HTTP 429).
   * Rate limited requests should stop reconnection attempts to avoid making the situation worse.
   */
  private isRateLimitError(error: unknown): boolean {
    if (!error || typeof error !== 'object') {
      return false;
    }

    // Check for error code
    if ('code' in error) {
      const code = (error as { code?: number }).code;
      if (code === 429) {
        return true;
      }
    }

    // Check message for rate limit indicators
    if ('message' in error && typeof error.message === 'string') {
      const message = error.message.toLowerCase();
      if (
        message.includes('429') ||
        message.includes('rate limit') ||
        message.includes('too many requests')
      ) {
        return true;
      }
    }

    return false;
  }
}