MCP Server Errors

MCP Server error instrumentation ensures that all errors occurring within the Model Context Protocol (MCP) server are captured and reported to Sentry, without ever interfering with the operation of the MCP service itself.

  • Comprehensive context: Errors are always associated with the active Sentry span, so you get full context (method, tool, arguments, etc.) in Sentry.
  • Categorized errors: Errors are tagged by type (e.g., validation, timeout, tool_execution, resource_operation, prompt_execution, transport, etc.) for easy filtering and analysis in Sentry.
  • Handler wrapping: All MCP server handlers (tool, resource, prompt) are wrapped to ensure errors are captured and correlated with the correct request span.
  • Span status tracking: When errors occur, the active span status is automatically set to error for better trace correlation.

The core utility is an error capture function:

Copied
import { getClient } from '../../currentScopes';
import { captureException } from '../../exports';
import { SPAN_STATUS_ERROR } from '../../tracing';
import { getActiveSpan } from '../../utils/spanUtils';
import type { McpErrorType } from './types';

export function captureError(error: Error, errorType?: McpErrorType, extraData?: Record<string, unknown>): void {
  try {
    const client = getClient();
    if (!client) return;

    const activeSpan = getActiveSpan();
    if (activeSpan?.isRecording()) {
      activeSpan.setStatus({
        code: SPAN_STATUS_ERROR,
        message: 'internal_error',
      });
    }

    captureException(error, {
      mechanism: {
        type: 'mcp_server',
        handled: false,
        data: {
          error_type: errorType || 'handler_execution',
          ...extraData,
        },
      },
    });
  } catch {
    // Silently ignore capture errors so it never affects MCP operation
  }
}
  • Never throws an exception: All error capture is wrapped in a try/catch and will never throw an exception.
  • Mechanism-based categorization: Error metadata is attached using the mechanism object.
  • Flexible context: Additional context can be passed via extraData and will be included in the mechanism data.

All MCP server method handlers (tool, resource, prompt) are wrapped to:

  • Correlate handler execution with the correct Sentry span (using request/session data)
  • Capture both synchronous and asynchronous errors
  • Categorize errors by handler type and error nature
  • Set span status to error for failed operations

Errors are categorized using the mechanism's data field according to the handler and type of error:

  • Tool handler errors:
    • validation (e.g., protocol/validation errors)
    • timeout (e.g., server timeouts)
    • tool_execution (all other tool errors)
  • Resource handler errors:
    • resource_operation
  • Prompt handler errors:
    • prompt_execution
  • Transport errors:
    • transport
  • Protocol errors:
    • protocol

The mechanism approach ensures that error classification information is available in the Sentry UI for debugging and analysis.

Note: this mechanism data is not indexed so it is not searchable.

All errors are captured within the context of the active Sentry span, so you can:

  • See which MCP method, tool, or resource caused the error
  • View all arguments and context for the failed request
  • Correlate errors with traces and performance data

The MCP transport layer is also instrumented to:

  • Create spans for incoming/outgoing messages
  • Capture errors in transport event handlers (e.g., onerror)
  • Correlate protocol errors with the correct request/response
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").