MCP server error handling

JSON-RPC error codes

The MCP protocol is built on JSON-RPC 2.0. Standard error codes:

MCP extends JSON-RPC with its own error codes in the positive range (1000–9999). These are defined in the @modelcontextprotocol/sdk package as the ErrorCode enum and map to the same JSON-RPC error structure. You rarely need these directly — the SDK uses them internally for protocol-level failures like ResourceNotFound (1004) or PromptNotFound (1003).

isError vs McpError — which to use

The single most important error handling decision in an MCP server:

// Correct: application error → isError: true
server.tool(
  'fetch_weather',
  'Get current weather for a city',
  { city: z.string() },
  async (args) => {
    let data: WeatherData;
    try {
      data = await weatherApi.get(args.city);
    } catch (err: any) {
      // API failure = application error; session continues
      return {
        isError: true,
        content: [{ type: 'text', text: `Could not fetch weather: ${err.message}` }],
      };
    }

    if (!data) {
      return {
        isError: true,
        content: [{ type: 'text', text: `No weather data found for city: ${args.city}` }],
      };
    }

    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
  }
);

// Rare: protocol-level error → McpError
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

server.resource(
  'config://{key}',
  'Read a server configuration value',
  async (uri) => {
    const key = uri.pathname.slice(1);
    // If the config store is completely unavailable, throw McpError
    // so the SDK returns a well-formed JSON-RPC error response
    if (!configStore.isAvailable()) {
      throw new McpError(ErrorCode.InternalError, 'Configuration store unavailable');
    }
    const value = configStore.get(key);
    if (value === undefined) {
      throw new McpError(ErrorCode.ResourceNotFound, `Config key not found: ${key}`);
    }
    return { contents: [{ uri: uri.href, text: value }] };
  }
);

Retry-safe vs non-retry-safe errors

When returning isError: true, include enough information in the error message for the AI client to decide whether to retry. A well-designed error message distinguishes transient failures (retry after delay) from permanent failures (do not retry):

// Structured error results with retry guidance
function transientError(message: string): { isError: true; content: ContentItem[] } {
  return {
    isError: true,
    content: [{ type: 'text', text: `${message} (transient — please retry in a few seconds)` }],
  };
}

function permanentError(message: string): { isError: true; content: ContentItem[] } {
  return {
    isError: true,
    content: [{ type: 'text', text: `${message} (permanent — do not retry without changing the request)` }],
  };
}

// In a tool handler:
if (err.status === 429) return transientError('Rate limit exceeded');
if (err.status === 503) return transientError('Upstream service temporarily unavailable');
if (err.status === 404) return permanentError(`Resource not found: ${args.id}`);
if (err.status === 403) return permanentError('Insufficient permissions for this resource');

AI clients that support tool-call retry logic (Claude, Gemini) will use the error message content to decide whether to retry automatically or surface the error to the user. Clear retry guidance in the error text is one of the most impactful usability improvements you can make to a production MCP server.

Global error handler and unhandled rejections

Always register a global uncaught exception handler and unhandled rejection handler. The SDK wraps exceptions thrown from tool handlers in -32603 Internal error responses, but exceptions thrown from outside a handler (event emitters, setTimeout callbacks, async code not awaited in a handler) are not caught by the SDK:

// Global safety net — these errors are bugs, not expected failures
process.on('uncaughtException', (err) => {
  console.error({ event: 'uncaught_exception', error: err.message, stack: err.stack });
  // Graceful shutdown — the server is in an unknown state
  process.exit(1);
});

process.on('unhandledRejection', (reason) => {
  console.error({ event: 'unhandled_rejection', reason: String(reason) });
  // Depending on severity: may want to exit, or just log and continue
  // If this fires frequently, a bug is swallowing promise chains
});

Configure AliveMCP webhook alerts so that a process crash (connection refused on the next probe) immediately fires an incident notification. The probe will detect the outage within 60 seconds of the crash — the mean time to detection (MTTD) from an uncaught exception is at most 60 seconds plus alert delivery time.

Structured error logging

Log every error at the right level with the fields needed to triage quickly:

// Error logging in tool handlers
server.tool('my_tool', 'Description', schema, async (args) => {
  try {
    const result = await doWork(args);
    console.info({ event: 'tool_success', tool: 'my_tool', duration_ms: Date.now() - start });
    return { content: [{ type: 'text', text: result }] };
  } catch (err: any) {
    const isTransient = err.status >= 500 || err.code === 'ECONNRESET';
    console.error({
      event: 'tool_error',
      tool: 'my_tool',
      error_code: err.status ?? err.code,
      transient: isTransient,
      // Do NOT log args — they may contain user PII
    });
    return {
      isError: true,
      content: [{ type: 'text', text: isTransient
        ? 'Temporary failure — please retry.'
        : `Operation failed: ${err.message}` }],
    };
  }
});

Alert thresholds to configure: (1) tool_error rate > 5% of tool_success events over a 5-minute window — indicates a degraded upstream or a bug introduced in a recent deploy; (2) any uncaught_exception event — should fire a P0 incident; (3) unhandled_rejection rate > 0 — indicates a code quality issue to address immediately.

Related questions

Further reading

• MCP server SDK — McpError, ErrorCode enum, and the initialize error surface
• MCP server logging — structured error event format and PII avoidance
• MCP server debugging — diagnosing error patterns by layer (transport, HTTP, protocol, tool)
• MCP server testing — error path tests for -32601, -32602, and isError results
• MCP server rate limiting — returning isError on rate limit exhaustion
• MCP server graceful shutdown — error handling during the drain window
• AliveMCP — uptime monitoring that surfaces protocol errors in the initialize exchange