feat(ai-proxy): log MCP unreachable server errors as Warn instead of Error

When MCP servers are unreachable (connection refused, DNS not found, timeout,
network unreachable), log as 'Warn' instead of 'Error' to reduce noise.

All other errors (authentication, configuration, protocol errors) remain as 'Error'.

Unreachable error codes: ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ENETUNREACH, EHOSTUNREACH

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: alban bertolini

packages/ai-proxy/src/mcp-client.ts

@@ -1,10 +1,34 @@
-import type { Logger } from '@forestadmin/datasource-toolkit';
+import type { Logger, LoggerLevel } from '@forestadmin/datasource-toolkit';
 
 import { MultiServerMCPClient } from '@langchain/mcp-adapters';
 
 import { McpConnectionError } from './types/errors';
 import McpServerRemoteTool from './types/mcp-server-remote-tool';
 
+const UNREACHABLE_ERROR_CODES = [
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'ETIMEDOUT',
+  'ENETUNREACH',
+  'EHOSTUNREACH',
+];
+
+function isServerUnreachable(error: Error): boolean {
+  const errorCode = (error as NodeJS.ErrnoException).code;
+
+  if (errorCode && UNREACHABLE_ERROR_CODES.includes(errorCode)) {
+    return true;
+  }
+
+  const { message } = error;
+
+  return UNREACHABLE_ERROR_CODES.some(code => message.includes(code));
+}
+
+function getLogLevelForError(error: Error): LoggerLevel {
+  return isServerUnreachable(error) ? 'Warn' : 'Error';
+}
+
 export type McpConfiguration = {
   configs: MultiServerMCPClient['config']['mcpServers'];
 } & Omit<MultiServerMCPClient['config'], 'mcpServers'>;
@@ -39,7 +63,8 @@ export default class McpClient {
           );
           this.tools.push(...extendedTools);
         } catch (error) {
-          this.logger?.('Error', `Error loading tools for ${name}`, error as Error);
+          const logLevel = getLogLevelForError(error as Error);
+          this.logger?.(logLevel, `Error loading tools for ${name}`, error as Error);
           errors.push({ server: name, error: error as Error });
         }
       }),
@@ -48,8 +73,10 @@ export default class McpClient {
     // Surface partial failures to provide better feedback
     if (errors.length > 0) {
       const errorMessage = errors.map(e => `${e.server}: ${e.error.message}`).join('; ');
+      const allConnectionErrors = errors.every(e => isServerUnreachable(e.error));
+      const summaryLogLevel = allConnectionErrors ? 'Warn' : 'Error';
       this.logger?.(
-        'Error',
+        summaryLogLevel,
         `Failed to load tools from ${errors.length}/${Object.keys(this.mcpClients).length} ` +
           `MCP server(s): ${errorMessage}`,
       );
@@ -72,7 +99,8 @@ export default class McpClient {
         await this.closeConnections();
       } catch (cleanupError) {
         // Log but don't throw - we don't want to mask the original connection error
-        this.logger?.('Error', 'Error during test connection cleanup', cleanupError as Error);
+        const logLevel = getLogLevelForError(cleanupError as Error);
+        this.logger?.(logLevel, 'Error during test connection cleanup', cleanupError as Error);
       }
     }
   }
@@ -88,14 +116,16 @@ export default class McpClient {
 
     if (failures.length > 0) {
       failures.forEach(({ name, result }) => {
-        this.logger?.(
-          'Error',
-          `Failed to close MCP connection for ${name}`,
-          (result as PromiseRejectedResult).reason,
-        );
+        const error = (result as PromiseRejectedResult).reason;
+        const logLevel = getLogLevelForError(error);
+        this.logger?.(logLevel, `Failed to close MCP connection for ${name}`, error);
       });
+      const allConnectionErrors = failures.every(({ result }) =>
+        isServerUnreachable((result as PromiseRejectedResult).reason),
+      );
+      const summaryLogLevel = allConnectionErrors ? 'Warn' : 'Error';
       this.logger?.(
-        'Error',
+        summaryLogLevel,
         `Failed to close ${failures.length}/${results.length} MCP connections. ` +
           `This may result in resource leaks.`,
       );

packages/ai-proxy/test/mcp-client.test.ts

@@ -106,6 +106,67 @@ describe('McpClient', () => {
         expect(mcpClient.tools.length).toEqual(2);
       });
     });
+
+    describe('error logging levels', () => {
+      it('should log unreachable server errors as Warn', async () => {
+        const loggerMock = jest.fn();
+        const mcpClient = new McpClient(aConfig, loggerMock);
+        const unreachableError = new Error('ECONNREFUSED: Connection refused');
+        getToolsMock.mockRejectedValue(unreachableError);
+
+        await mcpClient.loadTools();
+
+        expect(loggerMock).toHaveBeenCalledWith(
+          'Warn',
+          expect.stringContaining('Error loading tools for'),
+          unreachableError,
+        );
+        expect(loggerMock).toHaveBeenCalledWith(
+          'Warn',
+          expect.stringContaining('Failed to load tools from'),
+        );
+      });
+
+      it('should log other errors as Error', async () => {
+        const loggerMock = jest.fn();
+        const mcpClient = new McpClient(aConfig, loggerMock);
+        const otherError = new Error('Authentication failed');
+        getToolsMock.mockRejectedValue(otherError);
+
+        await mcpClient.loadTools();
+
+        expect(loggerMock).toHaveBeenCalledWith(
+          'Error',
+          expect.stringContaining('Error loading tools for'),
+          otherError,
+        );
+        expect(loggerMock).toHaveBeenCalledWith(
+          'Error',
+          expect.stringContaining('Failed to load tools from'),
+        );
+      });
+
+      it.each([
+        ['ECONNREFUSED', 'ECONNREFUSED: Connection refused'],
+        ['ENOTFOUND', 'ENOTFOUND: getaddrinfo ENOTFOUND hostname'],
+        ['ETIMEDOUT', 'ETIMEDOUT: Connection timed out'],
+        ['ENETUNREACH', 'ENETUNREACH: Network is unreachable'],
+        ['EHOSTUNREACH', 'EHOSTUNREACH: No route to host'],
+      ])('should log %s errors as Warn', async (_, errorMessage) => {
+        const loggerMock = jest.fn();
+        const mcpClient = new McpClient(aConfig, loggerMock);
+        const error = new Error(errorMessage);
+        getToolsMock.mockRejectedValue(error);
+
+        await mcpClient.loadTools();
+
+        expect(loggerMock).toHaveBeenCalledWith(
+          'Warn',
+          expect.stringContaining('Error loading tools for'),
+          error,
+        );
+      });
+    });
   });
 
   describe('closeConnection', () => {