fix: Log MCP client errors and disconnects as softFail (#679)

* fix: Implement soft-fail logging for MCP client errors

* fix: sanitize errMessage in softFail paths of logHttpError

Both softFail branches passed the raw error.message to the errMessage
key. Per the Mezmo promotion rule, any message containing " error:"
(e.g. SDK ParseError: "Parse error: ...") gets re-promoted to error
level, defeating the purpose of softFail.

Apply .replace(/ error:/gi, ' failure:') once at the top and reuse for
both the HTTP < 500 path and the new MCP soft-code path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jirispilka

src/mcp/server.ts

@@ -406,10 +406,14 @@ export class ActorsMcpServer {
 
     private setupErrorHandling(setupSIGINTHandler = true): void {
         this.server.onerror = (error) => {
-            if (error.message?.includes('No connection established')) {
+            // Client-disconnect noise from the MCP SDK (protocol.js). Two messages we see in prod:
+            //   - "No connection established" (sendRequest before transport attached)
+            //   - "Failed to send response: Error: Not connected" (client vanished mid-flight)
+            // Both are expected; log as softFail so they don't flood Mezmo error alerts.
+            if (/Not connected|No connection established/i.test(error.message ?? '')) {
                 // Mezmo (logDNA) promotes log entries to errors when the message contains "error".
                 // Use errMessage key and sanitize the string to preserve the soft-fail log level.
-                const errMessage = error.message.replace(/ error:/gi, ' failure:');
+                const errMessage = (error.message ?? '').replace(/ error:/gi, ' failure:');
                 log.softFail('MCP client disconnected before response could be sent', { errMessage });
             } else {
                 log.error('[MCP Error]', { error });
@@ -1286,16 +1290,35 @@ export class ActorsMcpServer {
                 failure_detail: failureDetail,
                 ...buildActorFields(actorName, actorId),
             };
-            log.error('Error executing tool for task', {
-                taskId,
-                toolName: tool.name,
-                toolStatus,
-                mcpSessionId,
-                failureCategory: callDiagnostics.failure_category,
-                failureHttpStatus: callDiagnostics.failure_http_status,
-                actorName: callDiagnostics.actor_name,
-                error,
-            });
+            // Log level follows the already-classified toolStatus:
+            //   SOFT_FAIL (e.g. 402/403 user quota, client-side issues) → softFail
+            //   FAILED/ABORTED/other                                    → error
+            if (toolStatus === TOOL_STATUS.SOFT_FAIL) {
+                // Mezmo promotes on "error" in message/keys — use errMessage key, sanitized.
+                const errMessage = (error instanceof Error ? error.message : String(error))
+                    .replace(/ error:/gi, ' failure:');
+                log.softFail('Tool execution soft-failed for task', {
+                    taskId,
+                    toolName: tool.name,
+                    toolStatus,
+                    mcpSessionId,
+                    failureCategory: callDiagnostics.failure_category,
+                    failureHttpStatus: callDiagnostics.failure_http_status,
+                    actorName: callDiagnostics.actor_name,
+                    errMessage,
+                });
+            } else {
+                log.error('Error executing tool for task', {
+                    taskId,
+                    toolName: tool.name,
+                    toolStatus,
+                    mcpSessionId,
+                    failureCategory: callDiagnostics.failure_category,
+                    failureHttpStatus: callDiagnostics.failure_http_status,
+                    actorName: callDiagnostics.actor_name,
+                    error,
+                });
+            }
             const userText = getToolCallErrorUserText(tool.name, error);
 
             // Check if task was cancelled before storing result

src/utils/logging.ts

@@ -1,3 +1,5 @@
+import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+
 import log from '@apify/log';
 
 /**
@@ -29,28 +31,71 @@ export function getHttpStatusCode(error: unknown): number | undefined {
 }
 
 /**
- * Logs HTTP errors based on status code, following apify-core pattern.
- * Uses `softFail` for status < 500 (API client errors) and `exception` for status >= 500 (API server errors).
+ * Client/caller faults and transient transport conditions that shouldn't trigger error alerts.
+ * Anything else in the JSON-RPC reserved range (-32768..-32000) is treated as a server fault.
+ */
+const SOFT_MCP_ERROR_CODES: ReadonlySet<number> = new Set([
+    ErrorCode.ParseError,
+    ErrorCode.InvalidRequest,
+    ErrorCode.MethodNotFound,
+    ErrorCode.InvalidParams,
+    ErrorCode.ConnectionClosed,
+    ErrorCode.RequestTimeout,
+]);
+
+/**
+ * Extract a JSON-RPC error code from an `McpError`-shaped object.
+ * Returns `undefined` if the `code` field is absent or outside the JSON-RPC reserved range.
+ */
+function getMcpErrorCode(error: unknown): number | undefined {
+    if (typeof error !== 'object' || error === null || !('code' in error)) return undefined;
+    const { code } = error as { code?: unknown };
+    if (typeof code === 'number' && code >= -32768 && code <= -32000) return code;
+    return undefined;
+}
+
+/**
+ * Logs HTTP or MCP errors at the appropriate level:
+ * - Client errors (HTTP < 500, or JSON-RPC client/transient codes) → softFail (no stack).
+ * - Server errors (HTTP >= 500, or JSON-RPC server codes) → exception (with stack).
+ * - Anything unclassifiable → error.
  *
  * @param error - The error object
  * @param message - The log message
  * @param data - Additional data to include in the log
  */
 export function logHttpError<T extends object>(error: unknown, message: string, data?: T): void {
     const statusCode = getHttpStatusCode(error);
-    const errorMessage = error instanceof Error ? error.message : String(error);
+    const rawErrorMessage = error instanceof Error ? error.message : String(error);
+    // Mezmo (logDNA) promotes log entries to error level when message/keys contain "error".
+    // Sanitize for softFail paths (see CONTRIBUTING.md § Logging → Mezmo promotion rule).
+    const softErrMessage = rawErrorMessage.replace(/ error:/gi, ' failure:');
 
     if (statusCode !== undefined && statusCode < 500) {
-        // Client errors (< 500) - log as softFail without stack trace
-        log.softFail(message, { errMessage: errorMessage, statusCode, ...data });
-    } else if (statusCode !== undefined && statusCode >= 500) {
-        // Server errors (>= 500) - log as exception with full error (includes stack trace)
+        // HTTP client errors (< 500) - softFail without stack trace
+        log.softFail(message, { errMessage: softErrMessage, statusCode, ...data });
+        return;
+    }
+    if (statusCode !== undefined && statusCode >= 500) {
+        // HTTP server errors (>= 500) - exception with full error (includes stack trace)
         const errorObj = error instanceof Error ? error : new Error(String(error));
         log.exception(errorObj, message, { statusCode, ...data });
-    } else {
-        // No status code available - log as error
-        log.error(message, { error, ...data });
+        return;
     }
+
+    const mcpErrorCode = getMcpErrorCode(error);
+    if (mcpErrorCode !== undefined) {
+        if (SOFT_MCP_ERROR_CODES.has(mcpErrorCode)) {
+            log.softFail(message, { errMessage: softErrMessage, mcpErrorCode, ...data });
+        } else {
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            log.exception(errorObj, message, { mcpErrorCode, ...data });
+        }
+        return;
+    }
+
+    // No status code available - log as error
+    log.error(message, { error, ...data });
 }
 
 const SKYFIRE_PAY_ID_KEY = 'skyfire-pay-id';