@juspay/neurolink 12.49.16 → 12.49.18

package/dist/mcp/externalServerManager.js

@@ -56,6 +56,16 @@ if (process.stdin && typeof process.stdin.unref === "function") {
         }
     });
 }
+const isMCPTransportFetch = (value) => typeof value === "function";
+const readMCPTransportFetch = (value) => {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (!isMCPTransportFetch(value)) {
+        throw new Error("MCP fetch hook must be a function");
+    }
+    return value;
+};
 /**
  * Recursively substitute environment variables in strings
  * Replaces ${VAR_NAME} with the value from process.env.VAR_NAME
@@ -389,6 +399,12 @@ export class ExternalServerManager extends EventEmitter {
     inFlightToolCalls = new Map();
     /** Consecutive pings missed while idle, per server. */
     unresponsiveChecks = new Map();
+    consecutiveFailures = new Map();
+    retryDeadlines = new Map();
+    lastHealth = new Map();
+    lifecycleStates = new Map();
+    /** Closed clients must never publish readiness after an awaited startup phase. */
+    closedClients = new WeakSet();
     toolDiscovery;
     enableMainRegistryIntegration;
     hitlManager; // Optional HITL manager for safety mechanisms
@@ -552,6 +568,7 @@ export class ExternalServerManager extends EventEmitter {
                         headers: isNonNullObject(serverConfig.headers)
                             ? substituteEnvVariables(serverConfig.headers)
                             : undefined,
+                        fetch: readMCPTransportFetch(serverConfig.fetch),
                         httpOptions: isNonNullObject(serverConfig.httpOptions)
                             ? serverConfig.httpOptions
                             : undefined,
@@ -690,6 +707,7 @@ export class ExternalServerManager extends EventEmitter {
                         headers: isNonNullObject(serverConfig.headers)
                             ? substituteEnvVariables(serverConfig.headers)
                             : undefined,
+                        fetch: readMCPTransportFetch(serverConfig.fetch),
                         httpOptions: isNonNullObject(serverConfig.httpOptions)
                             ? serverConfig.httpOptions
                             : undefined,
@@ -749,6 +767,17 @@ export class ExternalServerManager extends EventEmitter {
         if (!["stdio", "sse", "websocket", "http"].includes(config.transport)) {
             errors.push("Transport must be one of: stdio, sse, websocket, http");
         }
+        if (config.fetch !== undefined && !isMCPTransportFetch(config.fetch)) {
+            errors.push("MCP fetch hook must be a function");
+        }
+        for (const [name, value] of Object.entries({
+            connectionTimeout: config.httpOptions?.connectionTimeout,
+            requestTimeout: config.httpOptions?.requestTimeout,
+        })) {
+            if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+                errors.push(`${name} must be a positive finite number`);
+            }
+        }
         // Transport-specific validation
         if (config.transport === "stdio") {
             // stdio transport requires command
@@ -812,6 +841,12 @@ export class ExternalServerManager extends EventEmitter {
             minTools: config.minTools,
             cwd: config.cwd,
             url: config.url,
+            headers: config.headers,
+            fetch: config.fetch,
+            httpOptions: config.httpOptions,
+            retryConfig: config.retryConfig,
+            rateLimiting: config.rateLimiting,
+            auth: config.auth,
             metadata: {
                 category: "external",
                 ...(safeMetadataConversion(config.metadata) || {}),
@@ -820,6 +855,7 @@ export class ExternalServerManager extends EventEmitter {
     }
     async addServer(serverId, configOrServerInfo) {
         const startTime = Date.now();
+        let ownedInstance;
         try {
             // Use MCPServerInfo directly (zero-conversion architecture)
             const serverInfo = "transport" in configOrServerInfo &&
@@ -858,6 +894,7 @@ export class ExternalServerManager extends EventEmitter {
                 metadata: safeMetadataConversion(serverInfo.metadata),
                 // HTTP transport-specific fields
                 headers: serverInfo.headers,
+                fetch: serverInfo.fetch,
                 httpOptions: serverInfo.httpOptions,
                 retryConfig: serverInfo.retryConfig,
                 rateLimiting: serverInfo.rateLimiting,
@@ -904,7 +941,8 @@ export class ExternalServerManager extends EventEmitter {
                 },
                 config: tempConfig,
             };
-            // Store the instance
+            // Store the captured instance; failure cleanup may only remove this owner.
+            ownedInstance = instance;
             this.servers.set(serverId, instance);
             // Start the server
             await this.startServer(serverId);
@@ -949,8 +987,16 @@ export class ExternalServerManager extends EventEmitter {
             // debug, not error: NeuroLink.addExternalMCPServer (the public entry
             // point) emits the single ERROR record for a failed registration.
             mcpLogger.debug(`[ExternalServerManager] Failed to add server ${serverId}:`, error);
-            // Clean up if instance was created
-            this.servers.delete(serverId);
+            // A removed/replaced startup must not delete its successor's slot or health.
+            if (ownedInstance !== undefined &&
+                this.servers.get(serverId) === ownedInstance &&
+                ownedInstance.status !== "stopping") {
+                this.servers.delete(serverId);
+                this.consecutiveFailures.delete(serverId);
+                this.retryDeadlines.delete(serverId);
+                this.lastHealth.delete(serverId);
+                this.lifecycleStates.delete(serverId);
+            }
             // The minTools readiness gate carries structured metadata a generic
             // start failure does not: how many tools were actually discovered, so
             // a caller can distinguish "too few tools" from "could not connect".
@@ -997,14 +1043,19 @@ export class ExternalServerManager extends EventEmitter {
             // Stop the server
             await this.stopServer(serverId);
             // Remove from registry
-            this.servers.delete(serverId);
-            // Emit event
-            this.emit("disconnected", {
-                serverId,
-                serverName,
-                reason: "Manually removed",
-                timestamp: new Date(),
-            });
+            if (this.servers.get(serverId) === instance) {
+                this.servers.delete(serverId);
+                this.consecutiveFailures.delete(serverId);
+                this.retryDeadlines.delete(serverId);
+                this.lastHealth.delete(serverId);
+                this.lifecycleStates.delete(serverId);
+                this.emit("disconnected", {
+                    serverId,
+                    serverName,
+                    reason: "Manually removed",
+                    timestamp: new Date(),
+                });
+            }
             return {
                 success: true,
                 serverId,
@@ -1046,6 +1097,10 @@ export class ExternalServerManager extends EventEmitter {
         });
         try {
             this.updateServerStatus(serverId, "connecting");
+            this.toolDiscovery.clearServerTools(serverId);
+            instance.toolsMap.clear();
+            instance.toolsArray = undefined;
+            instance.tools = [];
             mcpLogger.debug(`[ExternalServerManager] Starting server: ${serverId}`, {
                 command: config.command,
                 args: redactSensitiveArgs(config.args),
@@ -1058,6 +1113,11 @@ export class ExternalServerManager extends EventEmitter {
                 !clientResult.transport) {
                 throw new Error(`Failed to create MCP client: ${clientResult.error}`);
             }
+            // Client creation is awaited: a host can remove and replace this slot meanwhile.
+            if (this.servers.get(serverId) !== instance || this.isShuttingDown) {
+                await MCPClientFactory.closeClient(clientResult.client, clientResult.transport, clientResult.process ?? undefined);
+                throw new Error(`MCP startup for '${serverId}' was superseded`);
+            }
             // Store client components
             instance.client = clientResult.client;
             instance.transportInstance = clientResult.transport;
@@ -1073,9 +1133,20 @@ export class ExternalServerManager extends EventEmitter {
             instance.metrics.totalConnections++;
             this.unresponsiveChecks.delete(serverId);
             this.attachClientLifecycle(serverId, clientResult.client, clientResult.transport);
-            this.updateServerStatus(serverId, "connected");
-            // Discover tools from the server
+            const assertStartupConnection = () => {
+                if (this.servers.get(serverId) !== instance ||
+                    instance.client !== clientResult.client ||
+                    clientResult.client.transport !== clientResult.transport ||
+                    this.closedClients.has(clientResult.client) ||
+                    instance.status !== "initializing" ||
+                    this.isShuttingDown) {
+                    throw new Error(`MCP connection for '${serverId}' was lost during startup`);
+                }
+            };
+            assertStartupConnection();
+            // Readiness belongs to this live client generation and successful discovery.
             await this.discoverServerTools(serverId);
+            assertStartupConnection();
             // Readiness gate: a server whose discovered tool count falls below
             // its configured minTools (default 0 — no minimum, so resource/prompt
             // -only servers stay valid) is torn back down instead of being marked
@@ -1096,7 +1167,13 @@ export class ExternalServerManager extends EventEmitter {
             if (this.enableMainRegistryIntegration) {
                 await this.registerServerToolsWithMainRegistry(serverId);
             }
+            assertStartupConnection();
             // Start health monitoring
+            this.consecutiveFailures.delete(serverId);
+            this.lastHealth.delete(serverId);
+            this.retryDeadlines.delete(serverId);
+            instance.lastError = undefined;
+            this.updateServerStatus(serverId, "connected");
             this.startHealthMonitoring(serverId);
             // Emit connected event
             this.emit("connected", {
@@ -1113,9 +1190,37 @@ export class ExternalServerManager extends EventEmitter {
             // debug, not error: the failure is rethrown below and surfaces once at
             // the NeuroLink.addExternalMCPServer entry point.
             mcpLogger.debug(`[ExternalServerManager] Failed to start server ${serverId}:`, error);
-            this.updateServerStatus(serverId, "failed");
-            instance.lastError =
-                error instanceof Error ? error.message : String(error);
+            if (this.servers.get(serverId) === instance &&
+                instance.status !== "stopping") {
+                await this.closeInstanceConnection(serverId, instance);
+                // Closing is asynchronous; removal or shutdown can revoke this owner.
+                const retainedOwner = this.servers.get(serverId);
+                if (retainedOwner === instance &&
+                    retainedOwner.status !== "stopping" &&
+                    !this.isShuttingDown) {
+                    this.updateServerStatus(serverId, "failed", instance);
+                    instance.lastError =
+                        error instanceof Error ? error.message : String(error);
+                    this.consecutiveFailures.set(serverId, (this.consecutiveFailures.get(serverId) ?? 0) + 1);
+                    this.emit("failed", {
+                        serverId,
+                        serverName: this.getServerName(serverId),
+                        error: instance.lastError,
+                        timestamp: new Date(),
+                    });
+                }
+            }
+            else if (this.servers.get(serverId) !== instance &&
+                instance.client &&
+                instance.transportInstance) {
+                // Dispose only this superseded client's handles; shared maps belong to its successor.
+                instance.client.onclose = undefined;
+                instance.client.onerror = undefined;
+                await MCPClientFactory.closeClient(instance.client, instance.transportInstance, instance.process ?? undefined);
+                instance.client = null;
+                instance.transportInstance = null;
+                instance.process = null;
+            }
             span.recordException(error instanceof Error ? error : new Error(String(error)));
             span.setStatus({
                 code: SpanStatusCode.ERROR,
@@ -1136,6 +1241,14 @@ export class ExternalServerManager extends EventEmitter {
      * callers set whatever status fits their case.
      */
     async closeInstanceConnection(serverId, instance) {
+        // A failed or stopped client cannot retain metadata from its own or an older discovery.
+        if (this.enableMainRegistryIntegration) {
+            this.unregisterServerToolsFromMainRegistry(serverId);
+        }
+        this.toolDiscovery.clearServerTools(serverId);
+        instance.toolsMap.clear();
+        instance.toolsArray = undefined;
+        instance.tools = [];
         if (!instance.client || !instance.transportInstance) {
             return;
         }
@@ -1174,7 +1287,7 @@ export class ExternalServerManager extends EventEmitter {
             },
         });
         try {
-            this.updateServerStatus(serverId, "stopping");
+            this.updateServerStatus(serverId, "stopping", instance);
             // Clear timers
             if (instance.healthTimer) {
                 clearInterval(instance.healthTimer);
@@ -1195,13 +1308,13 @@ export class ExternalServerManager extends EventEmitter {
             // the onclose it triggers cannot schedule a restart of a server we
             // are deliberately stopping.
             await this.closeInstanceConnection(serverId, instance);
-            this.updateServerStatus(serverId, "stopped");
+            this.updateServerStatus(serverId, "stopped", instance);
             span.setStatus({ code: SpanStatusCode.OK });
             mcpLogger.info(`[ExternalServerManager] Server stopped: ${serverId}`);
         }
         catch (error) {
             mcpLogger.error(`[ExternalServerManager] Error stopping server ${serverId}:`, error);
-            this.updateServerStatus(serverId, "failed");
+            this.updateServerStatus(serverId, "failed", instance);
             span.recordException(error instanceof Error ? error : new Error(String(error)));
             span.setStatus({
                 code: SpanStatusCode.ERROR,
@@ -1215,12 +1328,13 @@ export class ExternalServerManager extends EventEmitter {
     /**
      * Update server status and emit events
      */
-    updateServerStatus(serverId, newStatus) {
+    updateServerStatus(serverId, newStatus, owner) {
         const instance = this.servers.get(serverId);
-        if (!instance) {
+        if (!instance || (owner !== undefined && instance !== owner)) {
             return;
         }
         const oldStatus = instance.status;
+        this.lifecycleStates.set(serverId, newStatus);
         // Map ExternalMCPServerStatus to MCPServerInfo status
         const mappedStatus = newStatus === "connecting" || newStatus === "restarting"
             ? "initializing"
@@ -1254,6 +1368,7 @@ export class ExternalServerManager extends EventEmitter {
      */
     attachClientLifecycle(serverId, client, transport) {
         client.onclose = () => {
+            this.closedClients.add(client);
             const instance = this.servers.get(serverId);
             const pidNote = instance?.pid ? ` (pid ${instance.pid})` : "";
             const stderrTail = MCPClientFactory.getStderrTail(transport);
@@ -1277,7 +1392,7 @@ export class ExternalServerManager extends EventEmitter {
      * with the SDK's connection-closed error — so it is idempotent on the
      * (client, status) pair rather than trusting any one caller to be first.
      */
-    handleConnectionLost(serverId, client, reason, stderrTail = []) {
+    handleConnectionLost(serverId, client, reason, stderrTail = [], failureAlreadyCounted = false) {
         const instance = this.servers.get(serverId);
         if (!instance ||
             instance.client !== client ||
@@ -1286,7 +1401,7 @@ export class ExternalServerManager extends EventEmitter {
         }
         mcpLogger.warn(`[ExternalServerManager] Connection lost for ${serverId}: ${reason}`, stderrTail.length > 0 ? { stderrTail } : undefined);
         instance.lastError = reason;
-        this.handleServerDisconnection(serverId, reason);
+        this.handleServerDisconnection(serverId, reason, failureAlreadyCounted);
     }
     trackToolCall(serverId, delta) {
         const next = (this.inFlightToolCalls.get(serverId) ?? 0) + delta;
@@ -1307,6 +1422,7 @@ export class ExternalServerManager extends EventEmitter {
         }
         instance.lastError = error.message;
         instance.metrics.totalErrors++;
+        this.consecutiveFailures.set(serverId, (this.consecutiveFailures.get(serverId) ?? 0) + 1);
         mcpLogger.error(`[ExternalServerManager] Server error for ${serverId}:`, error);
         // Emit failed event
         this.emit("failed", {
@@ -1316,7 +1432,8 @@ export class ExternalServerManager extends EventEmitter {
             timestamp: new Date(),
         });
         // Attempt restart if enabled
-        if (this.config.enableAutoRestart && !this.isShuttingDown) {
+        if ((instance.config.autoRestart ?? this.config.enableAutoRestart) &&
+            !this.isShuttingDown) {
             this.scheduleRestart(serverId);
         }
         else {
@@ -1326,12 +1443,15 @@ export class ExternalServerManager extends EventEmitter {
     /**
      * Handle server disconnection
      */
-    handleServerDisconnection(serverId, reason) {
+    handleServerDisconnection(serverId, reason, failureAlreadyCounted = false) {
         const instance = this.servers.get(serverId);
         if (!instance) {
             return;
         }
         instance.metrics.totalDisconnections++;
+        if (!failureAlreadyCounted) {
+            this.consecutiveFailures.set(serverId, (this.consecutiveFailures.get(serverId) ?? 0) + 1);
+        }
         mcpLogger.warn(`[ExternalServerManager] Server disconnected ${serverId}: ${reason}`);
         // Emit disconnected event
         this.emit("disconnected", {
@@ -1357,9 +1477,13 @@ export class ExternalServerManager extends EventEmitter {
         if (!instance) {
             return;
         }
+        if (instance.restartTimer) {
+            return;
+        }
         if (instance.reconnectAttempts >= instance.maxReconnectAttempts) {
             mcpLogger.error(`[ExternalServerManager] Max restart attempts reached for ${serverId}`);
             this.updateServerStatus(serverId, "failed");
+            this.retryDeadlines.delete(serverId);
             return;
         }
         instance.reconnectAttempts++;
@@ -1367,10 +1491,18 @@ export class ExternalServerManager extends EventEmitter {
         const delay = Math.min(1000 *
             Math.pow(this.config.restartBackoffMultiplier, instance.reconnectAttempts - 1), 30000);
         mcpLogger.info(`[ExternalServerManager] Scheduling restart for ${serverId} in ${delay}ms (attempt ${instance.reconnectAttempts})`);
-        if (instance.restartTimer) {
-            return;
-        } // already scheduled
+        this.retryDeadlines.set(serverId, new Date(Date.now() + delay));
+        const health = this.getServerStatuses().find((status) => status.serverId === serverId);
+        if (health) {
+            this.emit("healthCheck", {
+                serverId,
+                serverName: this.getServerName(serverId),
+                health,
+                timestamp: new Date(),
+            });
+        }
         instance.restartTimer = setTimeout(async () => {
+            this.retryDeadlines.delete(serverId);
             const restartSpan = tracers.mcp.startSpan("neurolink.mcp.server.restart", {
                 attributes: {
                     "mcp.server_id": serverId,
@@ -1379,8 +1511,17 @@ export class ExternalServerManager extends EventEmitter {
                 },
             });
             try {
+                if (this.servers.get(serverId) !== instance) {
+                    return;
+                }
                 await this.stopServer(serverId);
+                if (this.servers.get(serverId) !== instance) {
+                    return;
+                }
                 await this.startServer(serverId);
+                if (this.servers.get(serverId) !== instance) {
+                    return;
+                }
                 // Reset restart attempts on successful restart
                 instance.reconnectAttempts = 0;
                 restartSpan.setStatus({ code: SpanStatusCode.OK });
@@ -1392,7 +1533,9 @@ export class ExternalServerManager extends EventEmitter {
                     code: SpanStatusCode.ERROR,
                     message: error instanceof Error ? error.message : String(error),
                 });
-                this.scheduleRestart(serverId); // Try again
+                if (this.servers.get(serverId) === instance) {
+                    this.scheduleRestart(serverId); // Try again only for this retained owner.
+                }
             }
             finally {
                 restartSpan.end();
@@ -1459,10 +1602,21 @@ export class ExternalServerManager extends EventEmitter {
         try {
             try {
                 await client.ping({ timeout: pingTimeoutMs });
+                if (instance.client !== client || instance.status !== "connected") {
+                    return;
+                }
                 this.unresponsiveChecks.delete(serverId);
+                this.consecutiveFailures.delete(serverId);
+                instance.lastError = undefined;
             }
             catch (error) {
+                if (instance.client !== client || instance.status !== "connected") {
+                    return;
+                }
                 isHealthy = false;
+                this.consecutiveFailures.set(serverId, (this.consecutiveFailures.get(serverId) ?? 0) + 1);
+                instance.lastError =
+                    error instanceof Error ? error.message : String(error);
                 if (isConnectionLostError(error)) {
                     connectionLost = true;
                     issues.push("connection closed");
@@ -1485,11 +1639,14 @@ export class ExternalServerManager extends EventEmitter {
             const health = {
                 serverId,
                 isHealthy,
-                status: instance.status,
+                status: this.lifecycleStates.get(serverId) ?? instance.status,
                 checkedAt: new Date(),
                 responseTime,
                 toolCount: instance.toolsMap.size,
                 issues,
+                consecutiveFailures: this.consecutiveFailures.get(serverId) ?? 0,
+                lastError: instance.lastError,
+                nextRetryAt: this.retryDeadlines.get(serverId),
                 performance: {
                     uptime: instance.startTime
                         ? Date.now() - instance.startTime.getTime()
@@ -1498,6 +1655,7 @@ export class ExternalServerManager extends EventEmitter {
                 },
             };
             // Emit health check event
+            this.lastHealth.set(serverId, health);
             this.emit("healthCheck", {
                 serverId,
                 serverName: this.getServerName(serverId),
@@ -1505,7 +1663,7 @@ export class ExternalServerManager extends EventEmitter {
                 timestamp: new Date(),
             });
             if (connectionLost || unresponsive) {
-                this.handleConnectionLost(serverId, client, `Health check failed: ${issues.join(", ")}`);
+                this.handleConnectionLost(serverId, client, `Health check failed: ${issues.join(", ")}`, [], true);
             }
             else if (!isHealthy) {
                 mcpLogger.warn(`[ExternalServerManager] Health check failed for ${serverId}:`, issues);
@@ -1591,11 +1749,15 @@ export class ExternalServerManager extends EventEmitter {
                 : 0;
             statuses.push({
                 serverId,
-                isHealthy: instance.status === "connected",
-                status: instance.status,
+                isHealthy: instance.status === "connected" &&
+                    (this.lastHealth.get(serverId)?.isHealthy ?? true),
+                status: this.lifecycleStates.get(serverId) ?? instance.status,
                 checkedAt: instance.lastHealthCheck || new Date(),
                 toolCount: instance.toolsMap.size,
                 issues: instance.lastError ? [instance.lastError] : [],
+                consecutiveFailures: this.consecutiveFailures.get(serverId) ?? 0,
+                lastError: instance.lastError,
+                nextRetryAt: this.retryDeadlines.get(serverId),
                 performance: {
                     uptime,
                     averageResponseTime: instance.metrics.averageResponseTime,
@@ -1671,9 +1833,23 @@ export class ExternalServerManager extends EventEmitter {
         if (!instance || !instance.client) {
             throw new Error(`Server '${serverId}' not found or not connected`);
         }
+        // Resource/prompt-only servers legitimately advertise no tools capability.
+        if (instance.client.getServerCapabilities()?.tools === undefined) {
+            return;
+        }
         try {
             mcpLogger.debug(`[ExternalServerManager] Discovering tools for server: ${serverId}`);
-            const discoveryResult = await this.toolDiscovery.discoverTools(serverId, instance.client, instance.config.timeout || this.config.defaultTimeout);
+            const client = instance.client;
+            const isCurrentDiscovery = () => this.servers.get(serverId) === instance &&
+                instance.client === client &&
+                instance.status === "initializing" &&
+                client.transport === instance.transportInstance &&
+                !this.closedClients.has(client) &&
+                !this.isShuttingDown;
+            const discoveryResult = await this.toolDiscovery.discoverTools(serverId, client, instance.config.timeout || this.config.defaultTimeout, isCurrentDiscovery, true);
+            if (!isCurrentDiscovery()) {
+                throw new Error(`MCP discovery for '${serverId}' was superseded`);
+            }
             if (discoveryResult.success) {
                 instance.toolsMap.clear();
                 instance.toolsArray = undefined;
@@ -1697,11 +1873,12 @@ export class ExternalServerManager extends EventEmitter {
                 mcpLogger.info(`[ExternalServerManager] Discovered ${discoveryResult.toolCount} tools for ${serverId} (${blockedCount} blocked, ${instance.toolsMap.size} available)`);
             }
             else {
-                mcpLogger.warn(`[ExternalServerManager] Tool discovery failed for ${serverId}: ${discoveryResult.error}`);
+                throw new Error(`Tool discovery failed for ${serverId}: ${discoveryResult.error ?? "unknown failure"}`);
             }
         }
         catch (error) {
             mcpLogger.error(`[ExternalServerManager] Tool discovery error for ${serverId}:`, error);
+            throw error;
         }
     }
     /**

package/dist/mcp/mcpClientFactory.js

@@ -82,6 +82,10 @@ export class MCPClientFactory {
      * Enhanced with retry logic, rate limiting, and circuit breaker protection
      */
     static async createClient(config, timeout = DEFAULT_CLIENT_TIMEOUT) {
+        const connectionTimeout = config.httpOptions?.connectionTimeout;
+        if (connectionTimeout !== undefined) {
+            timeout = Math.min(timeout, connectionTimeout);
+        }
         const startTime = Date.now();
         const { traceId, parentSpanId } = getActiveTraceContext();
         const obsSpan = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.connect", {
@@ -208,8 +212,17 @@ export class MCPClientFactory {
             const client = new Client(this.NEUROLINK_IMPLEMENTATION, {
                 capabilities: this.DEFAULT_CAPABILITIES,
             });
+            const requestTimeout = config.httpOptions?.requestTimeout;
+            if (requestTimeout !== undefined) {
+                const request = client.request.bind(client);
+                client.request = (payload, resultSchema, options) => request(payload, resultSchema, {
+                    ...options,
+                    timeout: Math.min(requestTimeout, options?.timeout ?? requestTimeout),
+                    maxTotalTimeout: Math.min(requestTimeout, options?.maxTotalTimeout ?? requestTimeout),
+                });
+            }
             // Connect with timeout
-            await this.raceWithTimeout(client.connect(transport), timeout, `Client connection timeout for ${config.id}`);
+            await this.raceWithTimeout(client.connect(transport, { timeout }), timeout, `Client connection timeout for ${config.id}`);
             // Perform handshake to get server capabilities
             const serverCapabilities = await this.performHandshake(client, timeout);
             mcpLogger.debug(`[MCPClientFactory] Handshake completed for ${config.id}`, {
@@ -331,7 +344,13 @@ export class MCPClientFactory {
         try {
             const url = new URL(config.url);
             const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
-            const transport = new SSEClientTransport(url);
+            const transportFetch = this.createEnhancedFetch(config, config.httpOptions?.requestTimeout ?? 60000);
+            const transport = new SSEClientTransport(url, {
+                requestInit: { headers: config.headers },
+                fetch: transportFetch,
+                // EventSource prefers this fetch over the transport-level hook for GET.
+                eventSourceInit: { fetch: transportFetch },
+            });
             return { transport };
         }
         catch (error) {
@@ -415,12 +434,25 @@ export class MCPClientFactory {
     /**
      * Create a fetch wrapper with timeout support
      */
-    static createFetchWithTimeout(timeoutMs) {
+    static createFetchWithTimeout(timeoutMs, transportFetch) {
         return async (input, init) => {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             try {
-                return await fetch(input, { ...init, signal: controller.signal });
+                const response = await transportFetch(input, {
+                    ...init,
+                    // EventSource requests "follow"; enforcing this here covers its GET
+                    // as well as MCP POSTs and prevents credentials crossing a redirect.
+                    redirect: "manual",
+                    signal: init?.signal
+                        ? AbortSignal.any([controller.signal, init.signal])
+                        : controller.signal,
+                });
+                if (response.status >= 300 && response.status < 400) {
+                    await response.body?.cancel();
+                    throw new Error("MCP transport redirects are not permitted");
+                }
+                return response;
             }
             finally {
                 clearTimeout(timeoutId);
@@ -431,7 +463,7 @@ export class MCPClientFactory {
      * Create an enhanced fetch function with timeout and optional retry
      */
     static createEnhancedFetch(config, timeoutMs, oauthProvider) {
-        const fetchWithTimeout = this.createFetchWithTimeout(timeoutMs);
+        const fetchWithTimeout = this.createFetchWithTimeout(timeoutMs, config.fetch ?? globalThis.fetch);
         return async (input, init) => {
             // If OAuth is configured, ensure we have valid tokens
             if (oauthProvider && config.auth?.type === "oauth2") {

package/dist/mcp/toolDiscoveryService.d.ts

@@ -28,8 +28,10 @@ export declare class ToolDiscoveryService extends EventEmitter {
     setOutputNormalizer(normalizer: McpOutputNormalizer): void;
     /**
      * Discover tools from an external MCP server
+     * Startup probes use the fresh connection directly under the same operation
+     * deadline, so an ordinary discovery cooldown cannot exhaust reconnects.
      */
-    discoverTools(serverId: string, client: Client, timeout?: number): Promise<ToolDiscoveryResult>;
+    discoverTools(serverId: string, client: Client, timeout?: number, isCurrentDiscovery?: () => boolean, startupDiscovery?: boolean): Promise<ToolDiscoveryResult>;
     /**
      * Perform the actual tool discovery
      */