@juspay/neurolink 12.7.7 → 12.7.8

package/dist/mcp/externalServerManager.d.ts

@@ -13,6 +13,12 @@ export declare class ExternalServerManager extends EventEmitter {
     private servers;
     private config;
     private isShuttingDown;
+    /** Servers whose previous ping has not returned; the interval must not stack. */
+    private healthChecksInFlight;
+    /** Tool calls currently executing per server; a busy server is not a hung one. */
+    private inFlightToolCalls;
+    /** Consecutive pings missed while idle, per server. */
+    private unresponsiveChecks;
     private toolDiscovery;
     private enableMainRegistryIntegration;
     private hitlManager?;
@@ -94,6 +100,27 @@ export declare class ExternalServerManager extends EventEmitter {
      * Update server status and emit events
      */
     private updateServerStatus;
+    /**
+     * Hook the SDK client's lifecycle so the manager learns about the server
+     * dying from the object that actually owns the process.
+     *
+     * `client.onclose` fires when the stdio child closes or a network
+     * transport drops. It also fires during our own `stopServer()`, which is
+     * why every path into `handleConnectionLost` checks that the client is
+     * still the instance's current one and the status is still "connected":
+     * a close that arrives while stopping or restarting is intentional.
+     */
+    private attachClientLifecycle;
+    /**
+     * Transition a server whose connection is gone, exactly once.
+     *
+     * Reached from three places that can all observe the same death — the
+     * client's onclose, a failed health-check ping, and a tool call rejected
+     * 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.
+     */
+    private handleConnectionLost;
+    private trackToolCall;
     /**
      * Handle server errors
      */
@@ -111,7 +138,20 @@ export declare class ExternalServerManager extends EventEmitter {
      */
     private startHealthMonitoring;
     /**
-     * Perform health check on a server
+     * Perform a health check by pinging the server over its live transport.
+     *
+     * The previous check read `process.killed` — a flag Node sets only when we
+     * call `kill()` ourselves, on a process handle that was not even the
+     * server's — so it could never observe a server that died on its own.
+     *
+     * A ping that comes back with the SDK's connection-closed error is a
+     * definitive death and is handled immediately. A ping that merely times
+     * out is ambiguous: single-threaded servers (a Python MCP server running a
+     * synchronous tool) cannot answer while a tool call is executing, and
+     * restarting one mid-call would destroy the work in flight. So a timeout
+     * counts toward a restart only while the server has no tool call in
+     * flight, and only after UNRESPONSIVE_CHECKS_BEFORE_RESTART consecutive
+     * misses.
      */
     private performHealthCheck;
     /**

package/dist/mcp/externalServerManager.js

@@ -7,6 +7,7 @@
  * - Tool discovery and registration
  */
 import { EventEmitter } from "events";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { mcpLogger } from "../utils/logger.js";
 import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
@@ -47,6 +48,25 @@ function substituteEnvVariables(value) {
     }
     return value;
 }
+/**
+ * The two messages the MCP SDK produces when the transport underneath a
+ * request is gone: `Protocol._onclose` rejects every pending request with
+ * `MCP error -32000: Connection closed`, and `StdioClientTransport.send`
+ * throws a bare `Not connected` once the child has closed. Both are matched
+ * on the SDK's exact text so a tool's own error output that happens to
+ * mention a closed connection cannot be mistaken for the server dying.
+ */
+const CONNECTION_LOST_PATTERN = /^Not connected$|MCP error -32000: Connection closed/;
+function isConnectionLostError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return CONNECTION_LOST_PATTERN.test(message);
+}
+/**
+ * Consecutive idle health checks a server may fail to answer before it is
+ * treated as hung and restarted. Two, not one: a single missed ping right
+ * after a long tool call is the server draining its queue, not a wedge.
+ */
+const UNRESPONSIVE_CHECKS_BEFORE_RESTART = 2;
 /**
  * Sensitive CLI flag patterns whose following value should be masked in logs.
  */
@@ -193,6 +213,12 @@ export class ExternalServerManager extends EventEmitter {
     servers = new Map();
     config;
     isShuttingDown = false;
+    /** Servers whose previous ping has not returned; the interval must not stack. */
+    healthChecksInFlight = new Set();
+    /** Tool calls currently executing per server; a busy server is not a hung one. */
+    inFlightToolCalls = new Map();
+    /** Consecutive pings missed while idle, per server. */
+    unresponsiveChecks = new Map();
     toolDiscovery;
     enableMainRegistryIntegration;
     hitlManager; // Optional HITL manager for safety mechanisms
@@ -718,6 +744,7 @@ export class ExternalServerManager extends EventEmitter {
             const convertedInstance = {
                 config: finalInstance.config,
                 process: finalInstance.process,
+                pid: finalInstance.pid,
                 client: finalInstance.client,
                 transport: finalInstance.transportInstance,
                 status: finalInstance.status,
@@ -845,31 +872,16 @@ export class ExternalServerManager extends EventEmitter {
             instance.client = clientResult.client;
             instance.transportInstance = clientResult.transport;
             instance.process = clientResult.process || null;
+            instance.pid =
+                clientResult.transport instanceof StdioClientTransport
+                    ? (clientResult.transport.pid ?? undefined)
+                    : undefined;
             instance.capabilities = safeMetadataConversion(clientResult.capabilities);
             instance.startTime = new Date();
             instance.lastHealthCheck = new Date();
             instance.metrics.totalConnections++;
-            // Handle process events if there's a process
-            if (instance.process) {
-                instance.process.on("error", (error) => {
-                    mcpLogger.error(`[ExternalServerManager] Process error for ${serverId}:`, error);
-                    this.handleServerError(serverId, error);
-                });
-                instance.process.on("exit", (code, signal) => {
-                    mcpLogger.warn(`[ExternalServerManager] Process exited for ${serverId}`, {
-                        code,
-                        signal,
-                    });
-                    this.handleServerDisconnection(serverId, `Process exited with code ${code}`);
-                });
-                // Log stderr for debugging
-                instance.process.stderr?.on("data", (data) => {
-                    const message = data.toString().trim();
-                    if (message) {
-                        mcpLogger.debug(`[ExternalServerManager] ${serverId} stderr:`, message);
-                    }
-                });
-            }
+            this.unresponsiveChecks.delete(serverId);
+            this.attachClientLifecycle(serverId, clientResult.client, clientResult.transport);
             this.updateServerStatus(serverId, "connected");
             // Discover tools from the server
             await this.discoverServerTools(serverId);
@@ -938,10 +950,14 @@ export class ExternalServerManager extends EventEmitter {
             }
             // Clear server tools from discovery service
             this.toolDiscovery.clearServerTools(serverId);
-            // Close MCP client using factory cleanup
+            // Close MCP client using factory cleanup. This close is ours, not a
+            // crash: drop the lifecycle hooks first so the onclose it triggers
+            // cannot schedule a restart of a server we are deliberately stopping.
             if (instance.client && instance.transportInstance) {
+                instance.client.onclose = undefined;
+                instance.client.onerror = undefined;
                 try {
-                    await MCPClientFactory.closeClient(instance.client, instance.transportInstance, instance.process || undefined);
+                    await MCPClientFactory.closeClient(instance.client, instance.transportInstance);
                 }
                 catch (error) {
                     mcpLogger.debug(`[ExternalServerManager] Error closing client for ${serverId}:`, error);
@@ -949,6 +965,7 @@ export class ExternalServerManager extends EventEmitter {
                 instance.client = null;
                 instance.transportInstance = null;
                 instance.process = null;
+                instance.pid = undefined;
             }
             this.updateServerStatus(serverId, "stopped");
             span.setStatus({ code: SpanStatusCode.OK });
@@ -997,6 +1014,61 @@ export class ExternalServerManager extends EventEmitter {
         });
         mcpLogger.debug(`[ExternalServerManager] Status changed for ${serverId}: ${oldStatus} -> ${newStatus}`);
     }
+    /**
+     * Hook the SDK client's lifecycle so the manager learns about the server
+     * dying from the object that actually owns the process.
+     *
+     * `client.onclose` fires when the stdio child closes or a network
+     * transport drops. It also fires during our own `stopServer()`, which is
+     * why every path into `handleConnectionLost` checks that the client is
+     * still the instance's current one and the status is still "connected":
+     * a close that arrives while stopping or restarting is intentional.
+     */
+    attachClientLifecycle(serverId, client, transport) {
+        client.onclose = () => {
+            const instance = this.servers.get(serverId);
+            const pidNote = instance?.pid ? ` (pid ${instance.pid})` : "";
+            const stderrTail = MCPClientFactory.getStderrTail(transport);
+            const reason = stderrTail.length > 0
+                ? `Server process closed${pidNote}; last stderr: ${stderrTail.slice(-5).join(" | ")}`
+                : `Server process closed${pidNote}`;
+            this.handleConnectionLost(serverId, client, reason, stderrTail);
+        };
+        client.onerror = (error) => {
+            // Transport-level noise: a stdin EPIPE after the child died, a line on
+            // stdout that is not JSON-RPC. Diagnostic only — a fatal error is
+            // followed by onclose, and that is where state changes.
+            mcpLogger.warn(`[ExternalServerManager] Transport error for ${serverId}: ${error.message}`);
+        };
+    }
+    /**
+     * Transition a server whose connection is gone, exactly once.
+     *
+     * Reached from three places that can all observe the same death — the
+     * client's onclose, a failed health-check ping, and a tool call rejected
+     * 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 = []) {
+        const instance = this.servers.get(serverId);
+        if (!instance ||
+            instance.client !== client ||
+            instance.status !== "connected") {
+            return;
+        }
+        mcpLogger.warn(`[ExternalServerManager] Connection lost for ${serverId}: ${reason}`, stderrTail.length > 0 ? { stderrTail } : undefined);
+        instance.lastError = reason;
+        this.handleServerDisconnection(serverId, reason);
+    }
+    trackToolCall(serverId, delta) {
+        const next = (this.inFlightToolCalls.get(serverId) ?? 0) + delta;
+        if (next <= 0) {
+            this.inFlightToolCalls.delete(serverId);
+        }
+        else {
+            this.inFlightToolCalls.set(serverId, next);
+        }
+    }
     /**
      * Handle server errors
      */
@@ -1114,21 +1186,62 @@ export class ExternalServerManager extends EventEmitter {
         }, interval);
     }
     /**
-     * Perform health check on a server
+     * Perform a health check by pinging the server over its live transport.
+     *
+     * The previous check read `process.killed` — a flag Node sets only when we
+     * call `kill()` ourselves, on a process handle that was not even the
+     * server's — so it could never observe a server that died on its own.
+     *
+     * A ping that comes back with the SDK's connection-closed error is a
+     * definitive death and is handled immediately. A ping that merely times
+     * out is ambiguous: single-threaded servers (a Python MCP server running a
+     * synchronous tool) cannot answer while a tool call is executing, and
+     * restarting one mid-call would destroy the work in flight. So a timeout
+     * counts toward a restart only while the server has no tool call in
+     * flight, and only after UNRESPONSIVE_CHECKS_BEFORE_RESTART consecutive
+     * misses.
      */
     async performHealthCheck(serverId) {
         const instance = this.servers.get(serverId);
-        if (!instance || instance.status !== "connected") {
+        if (!instance || instance.status !== "connected" || !instance.client) {
+            return;
+        }
+        if (this.healthChecksInFlight.has(serverId)) {
             return;
         }
+        this.healthChecksInFlight.add(serverId);
+        const client = instance.client;
+        const interval = instance.config.healthCheckInterval ??
+            this.config.defaultHealthCheckInterval;
+        const pingTimeoutMs = Math.max(1, Math.min(instance.config.timeout || this.config.defaultTimeout, interval));
         const startTime = Date.now();
+        const issues = [];
+        let isHealthy = true;
+        let connectionLost = false;
+        let unresponsive = false;
         try {
-            // For now, simple process check
-            let isHealthy = true;
-            const issues = [];
-            if (instance.process && instance.process.killed) {
+            try {
+                await client.ping({ timeout: pingTimeoutMs });
+                this.unresponsiveChecks.delete(serverId);
+            }
+            catch (error) {
                 isHealthy = false;
-                issues.push("Process is killed");
+                if (isConnectionLostError(error)) {
+                    connectionLost = true;
+                    issues.push("connection closed");
+                }
+                else {
+                    const inFlight = this.inFlightToolCalls.get(serverId) ?? 0;
+                    if (inFlight > 0) {
+                        issues.push(`ping timed out after ${pingTimeoutMs}ms while ${inFlight} tool call(s) in flight`);
+                    }
+                    else {
+                        const misses = (this.unresponsiveChecks.get(serverId) ?? 0) + 1;
+                        this.unresponsiveChecks.set(serverId, misses);
+                        issues.push(`ping timed out after ${pingTimeoutMs}ms while idle (${misses}/${UNRESPONSIVE_CHECKS_BEFORE_RESTART})`);
+                        unresponsive = misses >= UNRESPONSIVE_CHECKS_BEFORE_RESTART;
+                    }
+                }
             }
             const responseTime = Date.now() - startTime;
             instance.lastHealthCheck = new Date();
@@ -1154,14 +1267,18 @@ export class ExternalServerManager extends EventEmitter {
                 health,
                 timestamp: new Date(),
             });
-            if (!isHealthy) {
+            if (connectionLost || unresponsive) {
+                this.handleConnectionLost(serverId, client, `Health check failed: ${issues.join(", ")}`);
+            }
+            else if (!isHealthy) {
                 mcpLogger.warn(`[ExternalServerManager] Health check failed for ${serverId}:`, issues);
-                this.handleServerError(serverId, new Error(`Health check failed: ${issues.join(", ")}`));
             }
         }
         catch (error) {
             mcpLogger.error(`[ExternalServerManager] Health check error for ${serverId}:`, error);
-            this.handleServerError(serverId, error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.healthChecksInFlight.delete(serverId);
         }
     }
     /**
@@ -1175,6 +1292,7 @@ export class ExternalServerManager extends EventEmitter {
         return {
             config: runtime.config,
             process: runtime.process,
+            pid: runtime.pid,
             client: runtime.client,
             transport: runtime.transportInstance,
             status: runtime.status,
@@ -1200,6 +1318,7 @@ export class ExternalServerManager extends EventEmitter {
             converted.set(serverId, {
                 config: runtime.config,
                 process: runtime.process,
+                pid: runtime.pid,
                 client: runtime.client,
                 transport: runtime.transportInstance,
                 status: runtime.status,
@@ -1427,7 +1546,8 @@ export class ExternalServerManager extends EventEmitter {
         if (!instance) {
             throw new Error(`Server '${serverId}' not found`);
         }
-        if (!instance.client) {
+        const client = instance.client;
+        if (!client) {
             throw new Error(`Server '${serverId}' is not connected`);
         }
         if (instance.status !== "connected") {
@@ -1487,11 +1607,18 @@ export class ExternalServerManager extends EventEmitter {
                 }
             }
             // Execute tool through discovery service (with potentially modified parameters)
-            const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, finalParameters, {
-                timeout: options?.timeout ||
-                    instance.config.timeout ||
-                    this.config.defaultTimeout,
-            });
+            this.trackToolCall(serverId, 1);
+            let result;
+            try {
+                result = await this.toolDiscovery.executeTool(toolName, serverId, client, finalParameters, {
+                    timeout: options?.timeout ||
+                        instance.config.timeout ||
+                        this.config.defaultTimeout,
+                });
+            }
+            finally {
+                this.trackToolCall(serverId, -1);
+            }
             const duration = Date.now() - startTime;
             // Update metrics
             instance.metrics.totalToolCalls++;
@@ -1528,6 +1655,12 @@ export class ExternalServerManager extends EventEmitter {
                 /* telemetry should not break execution */
             }
             mcpLogger.error(`[ExternalServerManager] Tool execution failed: ${toolName} on ${serverId}`, error);
+            // The SDK rejects with its connection-closed error when the server is
+            // gone. Without this transition the instance stayed "connected" and
+            // every later call failed the same way with no restart ever scheduled.
+            if (isConnectionLostError(error)) {
+                this.handleConnectionLost(serverId, client, `Connection lost during tool call '${toolName}': ${error instanceof Error ? error.message : String(error)}`);
+            }
             throw error;
         }
     }

package/dist/mcp/mcpClientFactory.d.ts

@@ -7,7 +7,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
-import { type ChildProcess } from "child_process";
+import type { ChildProcess } from "child_process";
 import type { MCPTransportType, MCPServerInfo, MCPClientResult } from "../types/index.js";
 /**
  * MCPClientFactory
@@ -25,12 +25,34 @@ export declare class MCPClientFactory {
      * Internal client creation logic
      */
     private static createClientInternal;
+    /**
+     * The most recent stderr lines written by the stdio server behind
+     * `transport`. Empty for network transports and for servers that have
+     * written nothing. Lines are captured from before the process is even
+     * started, so an early boot failure is included.
+     */
+    static getStderrTail(transport: Transport): string[];
     /**
      * Create transport based on configuration
      */
     private static createTransport;
     /**
-     * Create stdio transport with process spawning
+     * Create a stdio transport.
+     *
+     * The SDK's StdioClientTransport owns the server process: it spawns the
+     * child inside `client.connect()` and reports the child's death through
+     * `transport.onclose`, which the Client forwards as `client.onclose`. There
+     * is deliberately no `spawn()` here. An earlier "startup probe" launched
+     * the command a second time, and that duplicate — never spoken to, never
+     * closed — was the process every lifecycle hook ended up watching while
+     * the real server could die unnoticed. It also leaked as an orphan on
+     * every shutdown.
+     *
+     * stderr is piped rather than ignored so a crashing server's last lines
+     * survive to the disconnect log and the connect error. A pipe nobody reads
+     * would back-pressure the child once the buffer fills, so the tail
+     * listener is attached before `start()`; the SDK creates the stderr
+     * PassThrough in its constructor for exactly this reason.
      */
     private static createStdioTransport;
     /**

package/dist/mcp/mcpClientFactory.js

@@ -9,7 +9,6 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.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 { spawn } from "child_process";
 import { mcpLogger } from "../utils/logger.js";
 import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { CircuitBreakerOpenError } from "../types/index.js";
@@ -26,6 +25,48 @@ import { getActiveTraceContext } from "../telemetry/traceContext.js";
  * especially when multiple MCP servers are started concurrently.
  */
 const DEFAULT_CLIENT_TIMEOUT = Math.max(5000, Number(process.env.MCP_CLIENT_TIMEOUT) || 60000);
+/**
+ * How many stderr lines to keep per stdio server. Enough for a Python
+ * traceback or an OOM message; small enough that a chatty server logging
+ * every request to stderr costs nothing.
+ */
+const STDERR_TAIL_LINES = 20;
+/**
+ * Bounded buffer of the most recent stderr lines a stdio server wrote.
+ *
+ * A crashing server explains itself on stderr and nowhere else. With the
+ * stream ignored — as it was — a `Connection closed` said nothing about
+ * why, and the ExternalServerManager could only report that a process it
+ * never saw had gone. Keeping a short tail per transport lets the
+ * disconnect log, the connect error and the `disconnected` event all carry
+ * the server's last words.
+ */
+class StderrTail {
+    lines = [];
+    partial = "";
+    append(chunk) {
+        this.partial += chunk.toString();
+        const pieces = this.partial.split(/\r?\n/);
+        this.partial = pieces.pop() ?? "";
+        for (const piece of pieces) {
+            if (piece.trim().length === 0) {
+                continue;
+            }
+            this.lines.push(piece);
+            if (this.lines.length > STDERR_TAIL_LINES) {
+                this.lines.shift();
+            }
+        }
+    }
+    snapshot() {
+        const out = [...this.lines];
+        if (this.partial.trim().length > 0) {
+            out.push(this.partial);
+        }
+        return out.slice(-STDERR_TAIL_LINES);
+    }
+}
+const stderrTails = new WeakMap();
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -164,10 +205,8 @@ export class MCPClientFactory {
     static async createClientInternal(config, timeout) {
         // Create transport
         const transportResult = await this.createTransport(config);
-        // Extract transport and process with necessary type assertions
-        // Note: Type assertions required due to TransportResult using 'unknown' to avoid circular imports
+        // Note: Type assertion required due to TransportResult using 'unknown' to avoid circular imports
         const transport = transportResult.transport;
-        const process = transportResult.process;
         try {
             // Create client
             const client = new Client(this.NEUROLINK_IMPLEMENTATION, {
@@ -186,24 +225,37 @@ export class MCPClientFactory {
             return {
                 client,
                 transport,
-                process,
                 capabilities: serverCapabilities,
             };
         }
         catch (error) {
-            // Clean up on failure
+            // Clean up on failure. For stdio, transport.close() ends stdin and
+            // escalates SIGTERM → SIGKILL on the child it spawned.
             try {
                 await transport.close();
             }
             catch (closeError) {
                 mcpLogger.debug(`[MCPClientFactory] Error closing transport during cleanup:`, closeError);
             }
-            if (process && !process.killed) {
-                process.kill("SIGTERM");
+            // A server that died during the handshake wrote its reason to stderr.
+            // Attach it, so "Connection closed" arrives with the traceback that
+            // explains it instead of leaving the operator to reproduce by hand.
+            const stderrTail = this.getStderrTail(transport);
+            if (error instanceof Error && stderrTail.length > 0) {
+                throw new Error(`${error.message}\nServer stderr (last ${stderrTail.length} lines):\n${stderrTail.join("\n")}`, { cause: error });
             }
             throw error;
         }
     }
+    /**
+     * The most recent stderr lines written by the stdio server behind
+     * `transport`. Empty for network transports and for servers that have
+     * written nothing. Lines are captured from before the process is even
+     * started, so an early boot failure is included.
+     */
+    static getStderrTail(transport) {
+        return stderrTails.get(transport)?.snapshot() ?? [];
+    }
     /**
      * Create transport based on configuration
      */
@@ -222,68 +274,28 @@ export class MCPClientFactory {
         }
     }
     /**
-     * Create stdio transport with process spawning
+     * Create a stdio transport.
+     *
+     * The SDK's StdioClientTransport owns the server process: it spawns the
+     * child inside `client.connect()` and reports the child's death through
+     * `transport.onclose`, which the Client forwards as `client.onclose`. There
+     * is deliberately no `spawn()` here. An earlier "startup probe" launched
+     * the command a second time, and that duplicate — never spoken to, never
+     * closed — was the process every lifecycle hook ended up watching while
+     * the real server could die unnoticed. It also leaked as an orphan on
+     * every shutdown.
+     *
+     * stderr is piped rather than ignored so a crashing server's last lines
+     * survive to the disconnect log and the connect error. A pipe nobody reads
+     * would back-pressure the child once the buffer fills, so the tail
+     * listener is attached before `start()`; the SDK creates the stderr
+     * PassThrough in its constructor for exactly this reason.
      */
     static async createStdioTransport(config) {
         mcpLogger.debug(`[MCPClientFactory] Creating stdio transport for ${config.id}`, {
             command: config.command,
             args: config.args,
         });
-        // Validate command is present
-        if (!config.command) {
-            throw new Error(`Command is required for stdio transport`);
-        }
-        // Spawn the process
-        const childProcess = spawn(config.command, config.args || [], {
-            stdio: ["pipe", "pipe", "pipe"],
-            env: Object.fromEntries(Object.entries({
-                ...process.env,
-                ...config.env,
-            })
-                .filter(([, value]) => value !== undefined)
-                .map(([k, v]) => [k, String(v)])),
-            cwd: config.cwd,
-        });
-        // Handle process errors
-        const processErrorPromise = new Promise((_, reject) => {
-            childProcess.on("error", (error) => {
-                reject(new Error(`Process spawn error: ${error.message}`));
-            });
-            childProcess.on("exit", (code, signal) => {
-                if (code !== 0) {
-                    reject(new Error(`Process exited with code ${code}, signal ${signal}`));
-                }
-            });
-        });
-        // Wait for process to be ready or fail using AbortController for better async patterns
-        const processStartupController = new AbortController();
-        const processStartupTimeout = setTimeout(() => {
-            processStartupController.abort();
-        }, 1000);
-        try {
-            await Promise.race([
-                new Promise((resolve) => {
-                    const checkReady = () => {
-                        if (processStartupController.signal.aborted) {
-                            resolve(); // Timeout reached, continue
-                        }
-                        else {
-                            setTimeout(checkReady, 100);
-                        }
-                    };
-                    checkReady();
-                }),
-                processErrorPromise,
-            ]);
-        }
-        finally {
-            clearTimeout(processStartupTimeout);
-        }
-        // Check if process is still running
-        if (childProcess.killed || childProcess.exitCode !== null) {
-            throw new Error("Process failed to start or exited immediately");
-        }
-        // Create transport
         if (!config.command) {
             throw new Error(`Command is required for stdio transport`);
         }
@@ -297,9 +309,20 @@ export class MCPClientFactory {
                 .filter(([, value]) => value !== undefined)
                 .map(([key, value]) => [key, String(value)])),
             cwd: config.cwd,
-            stderr: "ignore", // Suppress MCP server startup messages
+            stderr: "pipe",
+        });
+        const tail = new StderrTail();
+        stderrTails.set(transport, tail);
+        transport.stderr?.on("data", (chunk) => {
+            tail.append(chunk);
+            if (mcpLogger.shouldLog("debug")) {
+                const text = chunk.toString().trim();
+                if (text.length > 0) {
+                    mcpLogger.debug(`[MCPClientFactory] ${config.id} stderr:`, text);
+                }
+            }
         });
-        return { transport, process: childProcess };
+        return { transport };
     }
     /**
      * Create SSE transport