@dotsetlabs/bellwether 2.1.0 → 2.1.2

package/dist/discovery/discovery.js

@@ -8,6 +8,7 @@ const logger = getLogger('discovery');
 export async function discover(client, command, args) {
     // Initialize connection
     const initResult = await client.initialize();
+    const capabilityWarnings = [];
     // Discover tools
     let tools = [];
     if (initResult.capabilities.tools) {
@@ -16,6 +17,7 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list tools');
+            throw new Error(`Failed to list tools despite advertised tools capability: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     // Discover prompts
@@ -26,6 +28,11 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list prompts');
+            capabilityWarnings.push({
+                level: 'warning',
+                message: `Failed to list prompts: ${error instanceof Error ? error.message : String(error)}`,
+                recommendation: 'Check server prompt implementation and transport health.',
+            });
         }
     }
     // Discover resources
@@ -37,18 +44,30 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list resources');
+            capabilityWarnings.push({
+                level: 'warning',
+                message: `Failed to list resources: ${error instanceof Error ? error.message : String(error)}`,
+                recommendation: 'Check server resource implementation and transport health.',
+            });
         }
         try {
             resourceTemplates = await client.listResourceTemplates();
         }
         catch (error) {
             logger.debug({ error }, 'Failed to list resource templates (server may not support them)');
+            capabilityWarnings.push({
+                level: 'info',
+                message: `Failed to list resource templates: ${error instanceof Error ? error.message : String(error)}`,
+            });
         }
     }
     // Collect transport errors from the client
     const transportErrors = client.getTransportErrors();
     // Generate warnings based on discovery results
-    const warnings = generateDiscoveryWarnings(initResult.capabilities, tools, prompts, resources, transportErrors, initResult.protocolVersion);
+    const warnings = [
+        ...capabilityWarnings,
+        ...generateDiscoveryWarnings(initResult.capabilities, tools, prompts, resources, transportErrors, initResult.protocolVersion),
+    ];
     return {
         serverInfo: initResult.serverInfo,
         protocolVersion: initResult.protocolVersion,

package/dist/discovery/types.d.ts

@@ -60,7 +60,7 @@ export interface PropertySchema {
  * Classification of transport-level errors.
  * Used to differentiate between server bugs, protocol issues, and environment problems.
  */
-export type TransportErrorCategory = 'invalid_json' | 'buffer_overflow' | 'connection_refused' | 'connection_lost' | 'protocol_violation' | 'timeout' | 'shutdown_error' | 'unknown';
+export type TransportErrorCategory = 'invalid_json' | 'buffer_overflow' | 'connection_refused' | 'auth_failed' | 'connection_lost' | 'protocol_violation' | 'timeout' | 'shutdown_error' | 'unknown';
 /**
  * Record of a transport-level error that occurred during MCP communication.
  */

package/dist/docs/contract.js

@@ -624,9 +624,13 @@ function generateTransportIssuesSection(transportErrors, warnings) {
         // Recommendations
         const hasInvalidJson = transportErrors.some((e) => e.category === 'invalid_json');
         const hasProtocolError = transportErrors.some((e) => e.category === 'protocol_violation');
-        if (hasInvalidJson || hasProtocolError) {
+        const hasAuthError = transportErrors.some((e) => e.category === 'auth_failed');
+        if (hasInvalidJson || hasProtocolError || hasAuthError) {
             lines.push('### Recommendations');
             lines.push('');
+            if (hasAuthError) {
+                lines.push('- **Auth Failed**: Configure remote authentication headers (for example `Authorization: Bearer <token>`) and verify credentials are valid.');
+            }
             if (hasInvalidJson) {
                 lines.push('- **Invalid JSON**: The server may be writing debug output to stdout. Ensure all non-JSON-RPC output goes to stderr.');
             }
@@ -649,6 +653,8 @@ function formatTransportErrorCategory(category) {
             return 'Buffer Overflow';
         case 'connection_refused':
             return 'Connection Refused';
+        case 'auth_failed':
+            return 'Auth Failed';
         case 'connection_lost':
             return 'Connection Lost';
         case 'protocol_violation':

package/dist/errors/retry.js

@@ -2,7 +2,7 @@
  * Retry logic with exponential backoff.
  */
 import { getLogger } from '../logging/logger.js';
-import { BellwetherError, LLMRateLimitError, isRetryable, wrapError, createTimingContext, } from './types.js';
+import { BellwetherError, LLMRateLimitError, ServerAuthError, isRetryable, wrapError, createTimingContext, } from './types.js';
 import { RETRY_STRATEGIES, CIRCUIT_BREAKER, MATH_FACTORS } from '../constants.js';
 const DEFAULT_OPTIONS = {
     maxAttempts: RETRY_STRATEGIES.DEFAULT.maxAttempts,
@@ -191,7 +191,21 @@ export const TRANSPORT_RETRY_OPTIONS = {
     backoffMultiplier: RETRY_STRATEGIES.TRANSPORT.backoffMultiplier,
     jitter: RETRY_STRATEGIES.TRANSPORT.jitter,
     shouldRetry: (error) => {
+        if (error instanceof ServerAuthError) {
+            return false;
+        }
         const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        // Authentication/authorization failures are terminal until credentials change
+        if (message.includes('401') ||
+            message.includes('403') ||
+            message.includes('407') ||
+            message.includes('unauthorized') ||
+            message.includes('forbidden') ||
+            message.includes('authentication') ||
+            message.includes('authorization') ||
+            message.includes('access denied')) {
+            return false;
+        }
         // Timeouts might be transient
         if (message.includes('timeout')) {
             return true;

package/dist/errors/types.d.ts

@@ -120,6 +120,16 @@ export declare class ServerExitError extends TransportError {
 export declare class ProtocolError extends TransportError {
     constructor(message: string, context?: ErrorContext, cause?: Error);
 }
+/**
+ * Remote server authentication/authorization failed.
+ */
+export declare class ServerAuthError extends TransportError {
+    /** HTTP status code if available */
+    readonly statusCode?: number;
+    /** Suggested remediation hint */
+    readonly hint?: string;
+    constructor(message: string, statusCode?: number, hint?: string, context?: ErrorContext, cause?: Error);
+}
 /**
  * Buffer overflow during message processing.
  */

package/dist/errors/types.js

@@ -146,6 +146,34 @@ export class ProtocolError extends TransportError {
         this.name = 'ProtocolError';
     }
 }
+/**
+ * Remote server authentication/authorization failed.
+ */
+export class ServerAuthError extends TransportError {
+    /** HTTP status code if available */
+    statusCode;
+    /** Suggested remediation hint */
+    hint;
+    constructor(message, statusCode, hint, context, cause) {
+        super(message, {
+            code: 'TRANSPORT_AUTH_FAILED',
+            severity: 'high',
+            retryable: 'terminal',
+            context: {
+                ...context,
+                metadata: {
+                    ...context?.metadata,
+                    statusCode,
+                    hint,
+                },
+            },
+            cause,
+        });
+        this.name = 'ServerAuthError';
+        this.statusCode = statusCode;
+        this.hint = hint;
+    }
+}
 /**
  * Buffer overflow during message processing.
  */

package/dist/logging/logger.js

@@ -1,11 +1,14 @@
 import pino from 'pino';
+const IS_TEST_ENV = process.env.NODE_ENV === 'test' ||
+    process.env.VITEST === 'true' ||
+    process.env.VITEST_WORKER_ID !== undefined;
 /**
  * Default configuration.
  * Default level is 'warn' to keep CLI output clean.
  * Users can enable verbose output with --log-level info or --log-level debug.
  */
 const DEFAULT_CONFIG = {
-    level: 'warn',
+    level: IS_TEST_ENV ? 'silent' : 'warn',
     pretty: false,
     timestamp: true,
 };
@@ -50,7 +53,7 @@ export function createLogger(config = {}) {
  */
 export function getLogger(name) {
     if (!globalLogger) {
-        globalLogger = createLogger({ level: 'warn' });
+        globalLogger = createLogger({ level: DEFAULT_CONFIG.level });
     }
     if (name) {
         return globalLogger.child({ component: name });

package/dist/transport/env-filter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filter sensitive variables from process.env before spawning subprocesses.
+ * Explicitly provided additional environment variables are still allowed.
+ */
+export declare function filterSpawnEnv(baseEnv: NodeJS.ProcessEnv, additionalEnv?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=env-filter.d.ts.map

package/dist/transport/env-filter.js

@@ -0,0 +1,76 @@
+/**
+ * Environment variables to filter out when spawning MCP server processes.
+ * These may contain sensitive credentials that should not be exposed.
+ */
+const FILTERED_ENV_VARS = new Set([
+    // LLM API keys
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GOOGLE_API_KEY',
+    'AZURE_OPENAI_API_KEY',
+    'COHERE_API_KEY',
+    'HUGGINGFACE_API_KEY',
+    'REPLICATE_API_TOKEN',
+    // Provider credentials
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AZURE_CLIENT_SECRET',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    // SCM/CI tokens
+    'GITHUB_TOKEN',
+    'GH_TOKEN',
+    'GITLAB_TOKEN',
+    'BITBUCKET_TOKEN',
+    'NPM_TOKEN',
+    'PYPI_TOKEN',
+    // Database credentials
+    'DATABASE_URL',
+    'DATABASE_PASSWORD',
+    'POSTGRES_PASSWORD',
+    'MYSQL_PASSWORD',
+    'REDIS_PASSWORD',
+    'MONGODB_URI',
+    // Application secrets
+    'COOKIE_SECRET',
+    'SESSION_SECRET',
+    'JWT_SECRET',
+    'ENCRYPTION_KEY',
+    'PRIVATE_KEY',
+]);
+/**
+ * Patterns for environment variable names that should be filtered.
+ * Matches common naming conventions for secrets.
+ */
+const FILTERED_ENV_PATTERNS = [
+    /_API_KEY$/i,
+    /_SECRET$/i,
+    /_TOKEN$/i,
+    /_PASSWORD$/i,
+    /_PRIVATE_KEY$/i,
+    /_CREDENTIALS$/i,
+    /^SECRET_/i,
+    /^PRIVATE_/i,
+];
+function isSensitiveEnvVar(name) {
+    if (FILTERED_ENV_VARS.has(name)) {
+        return true;
+    }
+    return FILTERED_ENV_PATTERNS.some((pattern) => pattern.test(name));
+}
+/**
+ * Filter sensitive variables from process.env before spawning subprocesses.
+ * Explicitly provided additional environment variables are still allowed.
+ */
+export function filterSpawnEnv(baseEnv, additionalEnv) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (value !== undefined && !isSensitiveEnvVar(key)) {
+            filtered[key] = value;
+        }
+    }
+    if (additionalEnv) {
+        Object.assign(filtered, additionalEnv);
+    }
+    return filtered;
+}
+//# sourceMappingURL=env-filter.js.map

package/dist/transport/http-transport.js

@@ -1,5 +1,6 @@
 import { BaseTransport } from './base-transport.js';
 import { TIMEOUTS, DISPLAY_LIMITS, MCP } from '../constants.js';
+import { ServerAuthError } from '../errors/types.js';
 /**
  * HTTPTransport connects to MCP servers over HTTP using POST requests.
  *
@@ -111,6 +112,15 @@ export class HTTPTransport extends BaseTransport {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
+                if (response.status === 401) {
+                    throw new ServerAuthError('Remote MCP server authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
+                }
+                if (response.status === 403) {
+                    throw new ServerAuthError('Remote MCP server authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
+                }
+                if (response.status === 407) {
+                    throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+                }
                 // MCP 2025-11-25: 404 means session expired, clear session ID
                 if (response.status === 404 && this.sessionId) {
                     this.log('Session expired (404), clearing session ID');

package/dist/transport/mcp-client.d.ts

@@ -19,6 +19,8 @@ export interface MCPClientOptions {
     sseConfig?: Omit<SSETransportConfig, 'debug'>;
     /** Configuration for HTTP transport */
     httpConfig?: Omit<HTTPTransportConfig, 'debug'>;
+    /** Optional preflight check for remote transports (default: true) */
+    remotePreflight?: boolean;
 }
 /**
  * MCPClient connects to an MCP server via various transports and provides
@@ -55,7 +57,21 @@ export declare class MCPClient {
     private connectionState;
     /** Protocol version negotiated with the server during initialization */
     private negotiatedProtocolVersion;
+    /** Whether to run an explicit preflight before remote connection */
+    private remotePreflight;
     constructor(options?: MCPClientOptions);
+    /**
+     * Merge two header maps, giving precedence to override values.
+     */
+    private mergeHeaders;
+    /**
+     * Optional remote connectivity/auth preflight (enabled by default).
+     * Uses GET (not HEAD/OPTIONS) for broader compatibility.
+     *
+     * Any successful HTTP response (including 404/405/etc.) confirms network reachability.
+     * Only auth failures and hard network/timeouts are treated as terminal preflight failures.
+     */
+    private preflightRemote;
     /**
      * Classify a transport error based on its message.
      */
@@ -86,15 +102,6 @@ export declare class MCPClient {
      */
     getTransportType(): TransportType;
     private log;
-    /**
-     * Check if an environment variable name looks like a secret.
-     */
-    private isSensitiveEnvVar;
-    /**
-     * Filter sensitive environment variables before passing to subprocess.
-     * Uses both explicit list and pattern matching to catch common secret naming conventions.
-     */
-    private filterEnv;
     /**
      * Connect to an MCP server by spawning it as a subprocess.
      */

package/dist/transport/mcp-client.js

@@ -6,59 +6,8 @@ import { getLogger, startTiming } from '../logging/logger.js';
 import { TIMEOUTS, MCP, TRANSPORT_ERRORS } from '../constants.js';
 import { VERSION } from '../version.js';
 import { getFeatureFlags, isKnownProtocolVersion, } from '../protocol/index.js';
-/**
- * Environment variables to filter out when spawning MCP server processes.
- * These may contain sensitive credentials that should not be exposed.
- */
-const FILTERED_ENV_VARS = new Set([
-    // LLM API keys
-    'OPENAI_API_KEY',
-    'ANTHROPIC_API_KEY',
-    'GOOGLE_API_KEY',
-    'AZURE_OPENAI_API_KEY',
-    'COHERE_API_KEY',
-    'HUGGINGFACE_API_KEY',
-    'REPLICATE_API_TOKEN',
-    // Provider credentials
-    'AWS_SECRET_ACCESS_KEY',
-    'AWS_SESSION_TOKEN',
-    'AZURE_CLIENT_SECRET',
-    'GOOGLE_APPLICATION_CREDENTIALS',
-    // SCM/CI tokens
-    'GITHUB_TOKEN',
-    'GH_TOKEN',
-    'GITLAB_TOKEN',
-    'BITBUCKET_TOKEN',
-    'NPM_TOKEN',
-    'PYPI_TOKEN',
-    // Database credentials
-    'DATABASE_URL',
-    'DATABASE_PASSWORD',
-    'POSTGRES_PASSWORD',
-    'MYSQL_PASSWORD',
-    'REDIS_PASSWORD',
-    'MONGODB_URI',
-    // Application secrets
-    'COOKIE_SECRET',
-    'SESSION_SECRET',
-    'JWT_SECRET',
-    'ENCRYPTION_KEY',
-    'PRIVATE_KEY',
-]);
-/**
- * Patterns for environment variable names that should be filtered.
- * Matches common naming conventions for secrets.
- */
-const FILTERED_ENV_PATTERNS = [
-    /_API_KEY$/i,
-    /_SECRET$/i,
-    /_TOKEN$/i,
-    /_PASSWORD$/i,
-    /_PRIVATE_KEY$/i,
-    /_CREDENTIALS$/i,
-    /^SECRET_/i,
-    /^PRIVATE_/i,
-];
+import { filterSpawnEnv } from './env-filter.js';
+import { ConnectionError, ServerAuthError } from '../errors/types.js';
 const DEFAULT_TIMEOUT = TIMEOUTS.DEFAULT;
 const DEFAULT_STARTUP_DELAY = TIMEOUTS.SERVER_STARTUP;
 /**
@@ -96,6 +45,8 @@ export class MCPClient {
     connectionState = { attempted: false };
     /** Protocol version negotiated with the server during initialization */
     negotiatedProtocolVersion = null;
+    /** Whether to run an explicit preflight before remote connection */
+    remotePreflight;
     constructor(options) {
         this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
         this.startupDelay = options?.startupDelay ?? DEFAULT_STARTUP_DELAY;
@@ -103,6 +54,96 @@ export class MCPClient {
         this.transportType = options?.transport ?? 'stdio';
         this.sseConfig = options?.sseConfig;
         this.httpConfig = options?.httpConfig;
+        this.remotePreflight = options?.remotePreflight ?? true;
+    }
+    /**
+     * Merge two header maps, giving precedence to override values.
+     */
+    mergeHeaders(base, override) {
+        if (!base && !override)
+            return undefined;
+        const merged = {};
+        const apply = (headers) => {
+            if (!headers)
+                return;
+            for (const [name, value] of Object.entries(headers)) {
+                const normalized = name.toLowerCase();
+                for (const existing of Object.keys(merged)) {
+                    if (existing.toLowerCase() === normalized) {
+                        delete merged[existing];
+                        break;
+                    }
+                }
+                merged[name] = value;
+            }
+        };
+        apply(base);
+        apply(override);
+        return Object.keys(merged).length > 0 ? merged : undefined;
+    }
+    /**
+     * Optional remote connectivity/auth preflight (enabled by default).
+     * Uses GET (not HEAD/OPTIONS) for broader compatibility.
+     *
+     * Any successful HTTP response (including 404/405/etc.) confirms network reachability.
+     * Only auth failures and hard network/timeouts are treated as terminal preflight failures.
+     */
+    async preflightRemote(url, transport, headers) {
+        if (!this.remotePreflight) {
+            return;
+        }
+        const endpoint = transport === 'sse' ? `${url.replace(/\/$/, '')}/sse` : url;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), Math.min(this.timeout, 5000));
+        try {
+            const response = await fetch(endpoint, {
+                method: 'GET',
+                headers: {
+                    Accept: transport === 'sse' ? 'text/event-stream' : 'application/json, text/event-stream',
+                    ...(headers ?? {}),
+                },
+                signal: controller.signal,
+            });
+            const closePreflightBody = async () => {
+                try {
+                    await response.body?.cancel();
+                }
+                catch {
+                    // Ignore body cancellation failures; preflight status handling is primary.
+                }
+            };
+            if (response.status === 401) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: unauthorized (${response.status})`, response.status, 'Add authentication headers (for example Authorization) and retry.');
+            }
+            if (response.status === 403) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: forbidden (${response.status})`, response.status, 'Credentials are valid but lack required permissions/scopes.');
+            }
+            if (response.status === 407) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: proxy authentication required (${response.status})`, response.status, 'Configure proxy credentials and retry.');
+            }
+            if (!response.ok) {
+                // Non-auth HTTP statuses are compatibility-safe to continue:
+                // some MCP servers reject generic GET preflight paths but still
+                // support their actual protocol endpoints for normal operation.
+                this.logger.debug({ endpoint, status: response.status }, 'Remote preflight received non-auth HTTP status; continuing to transport connect');
+            }
+            await closePreflightBody();
+        }
+        catch (error) {
+            if (error instanceof ServerAuthError || error instanceof ConnectionError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new ConnectionError(`Remote MCP preflight timed out for ${endpoint}`);
+            }
+            throw new ConnectionError(`Remote MCP preflight failed for ${endpoint}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Classify a transport error based on its message.
@@ -127,6 +168,12 @@ export class MCPClient {
                 return { category: 'connection_refused', likelyServerBug: false };
             }
         }
+        // Check for authentication failures (environment/config issue)
+        for (const pattern of TRANSPORT_ERRORS.AUTH_FAILURE_PATTERNS) {
+            if (pattern.test(msg)) {
+                return { category: 'auth_failed', likelyServerBug: false };
+            }
+        }
         // Check for connection lost
         for (const pattern of TRANSPORT_ERRORS.CONNECTION_LOST_PATTERNS) {
             if (pattern.test(msg)) {
@@ -190,6 +237,8 @@ export class MCPClient {
                 return 'Server response exceeded buffer limits';
             case 'connection_refused':
                 return 'Failed to connect to server process';
+            case 'auth_failed':
+                return 'Authentication failed when connecting to remote MCP server';
             case 'connection_lost':
                 return 'Connection to server was lost unexpectedly';
             case 'protocol_violation':
@@ -247,35 +296,6 @@ export class MCPClient {
             this.logger.debug({ args }, 'MCP Debug');
         }
     }
-    /**
-     * Check if an environment variable name looks like a secret.
-     */
-    isSensitiveEnvVar(name) {
-        // Check explicit list
-        if (FILTERED_ENV_VARS.has(name)) {
-            return true;
-        }
-        // Check patterns
-        return FILTERED_ENV_PATTERNS.some((pattern) => pattern.test(name));
-    }
-    /**
-     * Filter sensitive environment variables before passing to subprocess.
-     * Uses both explicit list and pattern matching to catch common secret naming conventions.
-     */
-    filterEnv(baseEnv, additionalEnv) {
-        const filtered = {};
-        // Copy process.env, filtering out sensitive variables
-        for (const [key, value] of Object.entries(baseEnv)) {
-            if (value !== undefined && !this.isSensitiveEnvVar(key)) {
-                filtered[key] = value;
-            }
-        }
-        // Add additional env vars (these are explicitly provided, so allow them)
-        if (additionalEnv) {
-            Object.assign(filtered, additionalEnv);
-        }
-        return filtered;
-    }
     /**
      * Connect to an MCP server by spawning it as a subprocess.
      */
@@ -291,7 +311,7 @@ export class MCPClient {
             args,
         };
         // Filter out sensitive environment variables before spawning subprocess
-        const filteredEnv = this.filterEnv(process.env, env);
+        const filteredEnv = filterSpawnEnv(process.env, env);
         this.process = spawn(command, args, {
             stdio: ['pipe', 'pipe', 'pipe'],
             env: filteredEnv,
@@ -309,6 +329,7 @@ export class MCPClient {
         this.transport.on('error', (error) => {
             this.logger.error({ error: error.message }, 'Transport error');
             this.recordTransportError(error, 'stdio_transport');
+            this.clearPendingRequests(error.message);
         });
         this.transport.on('close', () => {
             this.logger.debug('Transport closed');
@@ -360,27 +381,36 @@ export class MCPClient {
         // Reset flags for new connection
         this.cleaningUp = false;
         this.disconnecting = false;
+        // Track connection state for diagnostics
+        this.connectionState = {
+            attempted: true,
+            url,
+        };
         this.logger.info({ url, transport }, 'Connecting to remote MCP server');
+        const mergedHeaders = transport === 'sse'
+            ? this.mergeHeaders(this.sseConfig?.headers, options?.headers)
+            : this.mergeHeaders(this.httpConfig?.headers, options?.headers);
+        await this.preflightRemote(url, transport, mergedHeaders);
         if (transport === 'sse') {
             const sseTransport = new SSETransport({
+                ...this.sseConfig,
                 baseUrl: url,
                 sessionId: options?.sessionId ?? this.sseConfig?.sessionId,
-                headers: options?.headers ?? this.sseConfig?.headers,
+                headers: mergedHeaders,
                 timeout: this.timeout,
                 debug: this.debug,
-                ...this.sseConfig,
             });
             await sseTransport.connect();
             this.transport = sseTransport;
         }
         else if (transport === 'streamable-http') {
             const httpTransport = new HTTPTransport({
+                ...this.httpConfig,
                 baseUrl: url,
                 sessionId: options?.sessionId ?? this.httpConfig?.sessionId,
-                headers: options?.headers ?? this.httpConfig?.headers,
+                headers: mergedHeaders,
                 timeout: this.timeout,
                 debug: this.debug,
-                ...this.httpConfig,
             });
             await httpTransport.connect();
             this.transport = httpTransport;
@@ -405,6 +435,7 @@ export class MCPClient {
         this.transport.on('error', (error) => {
             this.logger.error({ error: error.message }, 'Transport error');
             this.recordTransportError(error, 'remote_transport');
+            this.clearPendingRequests(error.message);
         });
         this.transport.on('close', () => {
             this.logger.debug('Transport closed');
@@ -418,7 +449,7 @@ export class MCPClient {
      */
     async waitForStartup() {
         // Enforce minimum startup delay to allow server to fully start
-        // npx-based servers often need significant time to download and start
+        // while still honoring explicit higher startupDelay values from config/tests.
         const delay = Math.max(this.startupDelay, TIMEOUTS.MIN_SERVER_STARTUP_WAIT);
         this.logger.debug({ delay }, 'Waiting for server startup');
         await new Promise((resolve) => setTimeout(resolve, delay));