MCP server error codes

JSON-RPC 2.0 standard error codes

These five codes are defined by the JSON-RPC 2.0 specification and used by the MCP SDK. When any of these appear, the client receives a JSON object with an error field instead of a result.

MCP-specific error codes

The JSON-RPC spec reserves the range -32099 to -32000 for implementation-defined server errors. The MCP SDK uses some values in this range for MCP-specific protocol failures.

Note: the exact codes used by the MCP SDK may change between SDK versions. Check your SDK version's source for the current ErrorCode enum values.

The two-tier error model

MCP's error model has two distinct tiers. Understanding which tier applies to a given failure determines how to handle it.

How to produce each error type

Tool-level isError: true (correct for most failures)

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'get_user') {
    const parsed = GetUserSchema.safeParse(request.params.arguments);

    // Validation failure → isError: true, LLM can retry
    if (!parsed.success) {
      return {
        content: [{ type: 'text', text: `Invalid arguments: ${parsed.error.message}` }],
        isError: true,
      };
    }

    const user = await db.getUser(parsed.data.userId);

    // Not-found → isError: true, LLM can use a different ID
    if (!user) {
      return {
        content: [{ type: 'text', text: `User ${parsed.data.userId} not found.` }],
        isError: true,
      };
    }

    return { content: [{ type: 'text', text: JSON.stringify(user) }] };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

Protocol error -32603 (from unhandled throw)

// This throw produces a -32603 Internal error
// The LLM client cannot read the message
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'get_user') {
    const user = await db.getUser(request.params.arguments?.userId);
    // If db.getUser throws (connection error, etc.) the exception propagates
    // → JSON-RPC -32603, logged as protocol error, LLM cannot recover
    return { content: [{ type: 'text', text: JSON.stringify(user) }] };
  }
});

The corrected version wraps the database call in a try/catch and returns isError: true for expected failures (connection unavailable, query error), while letting truly unexpected failures propagate as protocol errors.

How MCP Inspector displays error codes

MCP Inspector displays protocol errors and tool errors differently. Knowing which you're looking at is essential for debugging.

Error handling in upstream service calls

MCP tool handlers frequently call external APIs, databases, or internal microservices. These calls can fail for reasons outside the tool's control. The correct pattern is to catch these failures and return isError: true with a message describing the upstream failure, so the LLM can decide whether to retry, use a different tool, or report the issue.

case 'send_email': {
  const parsed = SendEmailSchema.safeParse(request.params.arguments);
  if (!parsed.success) return validationError(parsed.error);

  try {
    await emailClient.send({
      to: parsed.data.to,
      subject: parsed.data.subject,
      body: parsed.data.body,
    });
    return { content: [{ type: 'text', text: 'Email sent successfully.' }] };
  } catch (err) {
    const message = err instanceof Error ? err.message : 'Unknown error';

    // Categorise by retry-safety:
    if (message.includes('rate limit')) {
      return {
        content: [{ type: 'text', text: `Email rate limit reached. Try again in 60 seconds.` }],
        isError: true,
      };
    }
    if (message.includes('invalid recipient')) {
      return {
        content: [{ type: 'text', text: `Invalid email address: ${parsed.data.to}` }],
        isError: true,
      };
    }
    // Unexpected failure — still return isError so LLM can report it
    return {
      content: [{ type: 'text', text: `Email service error: ${message}` }],
      isError: true,
    };
  }
}

See MCP server error handling for the full decision tree on when to use each error path and retry-safe vs non-retry-safe classification.

Logging error codes in production

In production, log every error with its type (protocol vs tool-level), the tool name, and enough context to diagnose without a full stack trace. Structured logging makes this queryable.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const toolName = request.params.name;
  const startMs = Date.now();

  try {
    const result = await dispatchTool(request);

    // Log tool errors as warnings (LLM can recover)
    if (result.isError) {
      logger.warn('tool_error', {
        tool: toolName,
        durationMs: Date.now() - startMs,
        message: (result.content[0] as { text: string }).text,
      });
    }

    return result;
  } catch (err) {
    // Log protocol errors as errors (cannot recover)
    logger.error('tool_exception', {
      tool: toolName,
      durationMs: Date.now() - startMs,
      error: err instanceof Error ? err.message : String(err),
      stack: err instanceof Error ? err.stack : undefined,
    });
    throw;  // re-throw to produce -32603
  }
});

Tracking the ratio of isError: true responses to successful responses by tool name reveals which tools have the highest LLM validation failure rates — a signal that either the tool's inputSchema descriptions need improvement or the LLM needs different system-prompt guidance.

Related questions

Further reading

• MCP server error handling — complete decision tree for isError vs throw
• MCP Inspector — how to read protocol logs and distinguish error types
• MCP server debugging — tracing errors back through the protocol
• MCP server logging — structured logging for tool errors and protocol events
• MCP server structured logging — queryable production error logs
• MCP server input validation — turn validation failures into isError responses
• MCP server unit testing — testing error code paths with InMemoryTransport
• MCP server retry logic — retry-safe vs non-retry-safe error classification
• AliveMCP — monitor protocol-level health of your deployed MCP server