feat(mcp-server): tool result handling and error capturing

- Introduced new attributes for tool result content count and error status.
- Updated attribute extraction functions to utilize new constants for better maintainability.
- Added error capturing utilities to handle tool execution errors and transport errors gracefully.

Author: betegon

packages/core/src/integrations/mcp-server/attributeExtraction.ts

@@ -11,6 +11,8 @@ import {
   MCP_RESOURCE_URI_ATTRIBUTE,
   MCP_SESSION_ID_ATTRIBUTE,
   MCP_TOOL_NAME_ATTRIBUTE,
+  MCP_TOOL_RESULT_CONTENT_COUNT_ATTRIBUTE,
+  MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE,
   MCP_TRANSPORT_ATTRIBUTE,
   NETWORK_PROTOCOL_VERSION_ATTRIBUTE,
   NETWORK_TRANSPORT_ATTRIBUTE,
@@ -263,7 +265,7 @@ export function buildTypeSpecificAttributes(
 /** Get metadata about tool result content array */
 function getContentMetadata(content: unknown[]): Record<string, string | number> {
   return {
-    'mcp.tool.result.content_count': content.length,
+    [MCP_TOOL_RESULT_CONTENT_COUNT_ATTRIBUTE]: content.length,
   };
 }
 
@@ -350,7 +352,7 @@ export function extractToolResultAttributes(result: unknown): Record<string, str
   const resultObj = result as Record<string, unknown>;
 
   if (typeof resultObj.isError === 'boolean') {
-    attributes['mcp.tool.result.is_error'] = resultObj.isError;
+    attributes[MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE] = resultObj.isError;
   }
 
   if (Array.isArray(resultObj.content)) {

packages/core/src/integrations/mcp-server/attributes.ts

@@ -55,6 +55,25 @@ export const MCP_RESOURCE_URI_ATTRIBUTE = 'mcp.resource.uri';
  */
 export const MCP_PROMPT_NAME_ATTRIBUTE = 'mcp.prompt.name';
 
+// =============================================================================
+// TOOL RESULT ATTRIBUTES
+// =============================================================================
+
+/**
+ * Whether a tool execution resulted in an error
+ */
+export const MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE = 'mcp.tool.result.is_error';
+
+/**
+ * Number of content items in the tool result
+ */
+export const MCP_TOOL_RESULT_CONTENT_COUNT_ATTRIBUTE = 'mcp.tool.result.content_count';
+
+/**
+ * Serialized content of the tool result
+ */
+export const MCP_TOOL_RESULT_CONTENT_ATTRIBUTE = 'mcp.tool.result.content';
+
 // =============================================================================
 // NETWORK ATTRIBUTES (OpenTelemetry Standard)
 // =============================================================================

packages/core/src/integrations/mcp-server/correlation.ts

@@ -6,6 +6,8 @@
 import { getClient } from '../../currentScopes';
 import { withActiveSpan } from '../../tracing';
 import type { Span } from '../../types-hoist/span';
+import { MCP_TOOL_RESULT_CONTENT_ATTRIBUTE, MCP_TOOL_RESULT_CONTENT_COUNT_ATTRIBUTE, MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE } from './attributes';
+import { captureError } from './errorCapture';
 import { filterMcpPiiFromSpanData } from './piiFiltering';
 import type { RequestId, SessionId } from './types';
 
@@ -78,21 +80,22 @@ export function completeSpanWithResults(requestId: RequestId, result: unknown):
 
       spanWithMethods.setAttributes(toolAttributes);
 
-      // Set span status based on tool result
-      if (toolAttributes['mcp.tool.result.is_error']) {
+      const isToolError = rawToolAttributes[MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE] === true;
+      
+      if (isToolError) {
         spanWithMethods.setStatus({
           code: 2, // ERROR
           message: 'Tool execution failed',
         });
+
+        captureError(new Error('Tool returned error result'), 'tool_execution');
       }
     }
 
-    // Complete the span
     if (spanWithMethods.end) {
       spanWithMethods.end();
     }
 
-    // Clean up correlation
     requestIdToSpanMap.delete(requestId);
   }
 }
@@ -130,17 +133,15 @@ function extractToolResultAttributes(result: unknown): Record<string, string | n
   if (typeof result === 'object' && result !== null) {
     const resultObj = result as Record<string, unknown>;
 
-    // Check if this is an error result
     if (typeof resultObj.isError === 'boolean') {
-      attributes['mcp.tool.result.is_error'] = resultObj.isError;
+      attributes[MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE] = resultObj.isError;
     }
 
-    // Store content as-is (serialized)
     if (Array.isArray(resultObj.content)) {
-      attributes['mcp.tool.result.content_count'] = resultObj.content.length;
+      attributes[MCP_TOOL_RESULT_CONTENT_COUNT_ATTRIBUTE] = resultObj.content.length;
 
       const serializedContent = JSON.stringify(resultObj.content);
-      attributes['mcp.tool.result.content'] =
+      attributes[MCP_TOOL_RESULT_CONTENT_ATTRIBUTE] =
         serializedContent.length > 5000 ? `${serializedContent.substring(0, 4997)}...` : serializedContent;
     }
   }

packages/core/src/integrations/mcp-server/errorCapture.ts

@@ -0,0 +1,29 @@
+/**
+ * Safe error capture utilities for MCP server instrumentation
+ * Ensures Sentry error reporting never interferes with MCP service operation
+ */
+
+import { getClient } from '../../currentScopes';
+import { captureException } from '../../exports';
+
+/**
+ * Safely captures an error to Sentry without affecting MCP service operation
+ * The active span already contains all MCP context (method, tool, arguments, etc.)
+ * Sentry automatically associates the error with the active span
+ */
+export function captureError(error: Error, errorType?: string): void {
+  try {
+    const client = getClient();
+    if (!client) {
+      return
+    }
+
+    captureException(error, {
+      tags: {
+        mcp_error_type: errorType || 'handler_execution',
+      },
+    });
+  } catch {
+    // Silently ignore capture errors - never affect MCP operation
+  }
+}

packages/core/src/integrations/mcp-server/handlers.ts

@@ -7,6 +7,7 @@ import { DEBUG_BUILD } from '../../debug-build';
 import { logger } from '../../utils/logger';
 import { fill } from '../../utils/object';
 import { associateContextWithRequestSpan } from './correlation';
+import { captureError } from './errorCapture';
 import type { HandlerExtraData, MCPHandler, MCPServerInstance } from './types';
 
 /**
@@ -21,22 +22,22 @@ function wrapMethodHandler(serverInstance: MCPServerInstance, methodName: keyof
         return (originalMethod as (...args: unknown[]) => unknown).call(this, name, ...args);
       }
 
-      const wrappedHandler = createWrappedHandler(handler as MCPHandler);
+      const wrappedHandler = createWrappedHandler(handler as MCPHandler, methodName, name);
       return (originalMethod as (...args: unknown[]) => unknown).call(this, name, ...args.slice(0, -1), wrappedHandler);
     };
   });
 }
 
 /**
- * Creates a wrapped handler with span correlation
+ * Creates a wrapped handler with span correlation and error capture
  */
-function createWrappedHandler(originalHandler: MCPHandler) {
+function createWrappedHandler(originalHandler: MCPHandler, methodName: keyof MCPServerInstance, handlerName: string) {
   return function (this: unknown, ...handlerArgs: unknown[]): unknown {
     try {
       const extraHandlerData = findExtraHandlerData(handlerArgs);
 
       return associateContextWithRequestSpan(extraHandlerData, () => {
-        return originalHandler.apply(this, handlerArgs);
+        return createErrorCapturingHandler(originalHandler, methodName, handlerName, handlerArgs, extraHandlerData);
       });
     } catch (error) {
       DEBUG_BUILD && logger.warn('MCP handler wrapping failed:', error);
@@ -45,6 +46,75 @@ function createWrappedHandler(originalHandler: MCPHandler) {
   };
 }
 
+/**
+ * Creates a handler that captures execution errors for Sentry
+ */
+function createErrorCapturingHandler(
+  originalHandler: MCPHandler,
+  methodName: keyof MCPServerInstance,
+  handlerName: string,
+  handlerArgs: unknown[],
+  extraHandlerData?: HandlerExtraData,
+): unknown {
+  try {
+    const result = originalHandler.apply(originalHandler, handlerArgs);
+
+    // Handle both sync and async handlers
+    if (result && typeof result === 'object' && 'then' in result) {
+      // Async handler - wrap with error capture
+      return (result as Promise<unknown>).catch((error: Error) => {
+        captureHandlerError(error, methodName, handlerName, handlerArgs, extraHandlerData);
+        throw error; // Re-throw to maintain MCP error handling behavior
+      });
+    }
+
+    // Sync handler - return result as-is
+    return result;
+  } catch (error) {
+    // Sync handler threw an error - capture it
+    captureHandlerError(error as Error, methodName, handlerName, handlerArgs, extraHandlerData);
+    throw error; // Re-throw to maintain MCP error handling behavior
+  }
+}
+
+/**
+ * Captures handler execution errors based on handler type
+ */
+function captureHandlerError(
+  error: Error,
+  methodName: keyof MCPServerInstance,
+  _handlerName: string,
+  _handlerArgs: unknown[],
+  _extraHandlerData?: HandlerExtraData,
+): void {
+  try {
+    if (methodName === 'tool') {
+      // Check if this is a validation/protocol error
+      if (
+        error.name === 'ProtocolValidationError' ||
+        error.message.includes('validation') ||
+        error.message.includes('protocol')
+      ) {
+        captureError(error, 'validation');
+      } else if (
+        error.name === 'ServerTimeoutError' ||
+        error.message.includes('timed out') ||
+        error.message.includes('timeout')
+      ) {
+        captureError(error, 'timeout');
+      } else {
+        captureError(error, 'tool_execution');
+      }
+    } else if (methodName === 'resource') {
+      captureError(error, 'resource_operation');
+    } else if (methodName === 'prompt') {
+      captureError(error, 'prompt_execution');
+    }
+  } catch (captureErr) {
+    // silently ignore capture errors to not affect MCP operation
+  }
+}
+
 /**
  * Extracts request/session data from handler arguments
  */

packages/core/src/integrations/mcp-server/index.ts

@@ -1,6 +1,6 @@
 import { fill } from '../../utils/object';
 import { wrapAllMCPHandlers } from './handlers';
-import { wrapTransportOnClose, wrapTransportOnMessage, wrapTransportSend } from './transport';
+import { wrapTransportError, wrapTransportOnClose, wrapTransportOnMessage, wrapTransportSend } from './transport';
 import type { MCPServerInstance, MCPTransport } from './types';
 import { validateMcpServerInstance } from './validation';
 
@@ -34,6 +34,7 @@ export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S):
       wrapTransportOnMessage(transport);
       wrapTransportSend(transport);
       wrapTransportOnClose(transport);
+      wrapTransportError(transport);
 
       return result;
     };

packages/core/src/integrations/mcp-server/piiFiltering.ts

@@ -3,13 +3,15 @@
  * Removes sensitive data when sendDefaultPii is false
  */
 
+import { MCP_TOOL_RESULT_CONTENT_ATTRIBUTE } from './attributes';
+
 /** PII attributes that should be removed when sendDefaultPii is false */
 const PII_ATTRIBUTES = new Set([
   'client.address',
   'client.port',
   'mcp.logging.message',
   'mcp.resource.uri',
-  'mcp.tool.result.content',
+  MCP_TOOL_RESULT_CONTENT_ATTRIBUTE,
 ]);
 
 /**

packages/core/src/integrations/mcp-server/transport.ts

@@ -7,6 +7,7 @@ import { getIsolationScope, withIsolationScope } from '../../currentScopes';
 import { startInactiveSpan, withActiveSpan } from '../../tracing';
 import { fill } from '../../utils/object';
 import { cleanupAllPendingSpans, completeSpanWithResults, storeSpanForRequest } from './correlation';
+import { captureError } from './errorCapture';
 import { buildMcpServerSpanConfig, createMcpNotificationSpan, createMcpOutgoingNotificationSpan } from './spans';
 import type { ExtraHandlerData, MCPTransport } from './types';
 import { isJsonRpcNotification, isJsonRpcRequest, isJsonRpcResponse } from './validation';
@@ -65,12 +66,14 @@ export function wrapTransportSend(transport: MCPTransport): void {
           });
         }
 
-        // Handle responses - enrich spans with tool results
         if (isJsonRpcResponse(message)) {
           const messageTyped = message as { id: string | number; result?: unknown; error?: unknown };
 
           if (messageTyped.id !== null && messageTyped.id !== undefined) {
-            // Complete span with tool results
+            if (messageTyped.error) {
+              captureJsonRpcErrorResponse(messageTyped.error, messageTyped.id, this);
+            }
+
             completeSpanWithResults(messageTyped.id, messageTyped.result);
           }
         }
@@ -88,11 +91,58 @@ export function wrapTransportOnClose(transport: MCPTransport): void {
   if (transport.onclose) {
     fill(transport, 'onclose', originalOnClose => {
       return function (this: MCPTransport, ...args: unknown[]) {
-        // Clean up any pending spans on transport close
         cleanupAllPendingSpans();
 
         return (originalOnClose as (...args: unknown[]) => unknown).call(this, ...args);
       };
     });
   }
 }
+
+/**
+ * Wraps transport error handlers to capture connection errors
+ */
+export function wrapTransportError(transport: MCPTransport): void {
+  // All MCP transports have an onerror method as part of the standard interface
+  if (transport.onerror) {
+    fill(transport, 'onerror', (originalOnError: (error: Error) => void) => {
+      return function (this: MCPTransport, error: Error) {
+        captureTransportError(error, this);
+        return originalOnError.call(this, error);
+      };
+    });
+  }
+}
+
+/**
+ * Captures JSON-RPC error responses
+ */
+function captureJsonRpcErrorResponse(
+  errorResponse: unknown,
+  _requestId: string | number,
+  _transport: MCPTransport,
+): void {
+  try {
+    if (errorResponse && typeof errorResponse === 'object' && 'code' in errorResponse && 'message' in errorResponse) {
+      const jsonRpcError = errorResponse as { code: number; message: string; data?: unknown };
+
+      const error = new Error(jsonRpcError.message);
+      error.name = `JsonRpcError_${jsonRpcError.code}`;
+
+      captureError(error, 'protocol');
+    }
+  } catch {
+    // Silently ignore capture errors
+  }
+}
+
+/**
+ * Captures transport connection errors
+ */
+function captureTransportError(error: Error, _transport: MCPTransport): void {
+  try {
+    captureError(error, 'transport');
+  } catch {
+    // Silently ignore capture errors
+  }
+}