---
title: "Errors"
url: https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors/
---

# 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**.

## [Goals and Philosophy](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#goals-and-philosophy)

* **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.

## [Safe Error Capture](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#safe-error-capture)

The core utility is an error capture function:

```ts
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.

## [Handler Wrapping for Error Capture](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#handler-wrapping-for-error-capture)

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

### [Error Categorization](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#error-categorization)

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.

## [Span Correlation](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#span-correlation)

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

## [Transport Layer Error Instrumentation](https://develop.sentry.dev/sdk/foundations/client/integrations/mcp/errors.md#transport-layer-error-instrumentation)

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