MCP server error handling: what to return when something goes wrong

When a caller sends { "repoUrl": "not-a-url" }, returning "repoUrl must be a valid GitHub URL starting with https://github.com/" is safe and helpful. The field name and constraint are part of your public API contract. There are no internals here to leak.

import { z } from "zod";

const GetIssueSchema = z.object({
  issueId: z.string()
    .regex(/^[A-Z][A-Z0-9]+-\d+$/, "issueId must match pattern PROJECT-123"),
  includeComments: z.boolean().optional().default(false),
});

server.tool("get_issue", GetIssueSchema, async (args) => {
  // Zod has already validated — args.issueId is clean
  const result = await fetchIssue(args.issueId, args.includeComments);
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
});

If you use Zod at the entry point, validation errors surface automatically with field-level messages. If you validate manually, return { isError: true, content: [{ type: "text", text: "issueId: must match pattern PROJECT-123" }] }. Never throw — throwing an unhandled error will propagate your framework's default error format, which usually includes a stack trace.

A common mistake is returning a 403-equivalent message for permission denial and a 404-equivalent message for missing resources. An attacker can then probe with IDs they're not authorized to see: if they get "no permission", the resource exists; if they get "not found", it doesn't. This is an enumeration vulnerability.

The safe pattern is to always return "not found or not accessible" for any resource the caller can't see, regardless of whether it exists or they lack permission. Your internal logs record the real reason.

async function getDocument(callerId: string, docId: string) {
  const doc = await db.documents.findById(docId);

  // Don't leak whether the doc exists:
  // BAD: if (!doc) throw new Error("Document not found");
  // BAD: if (!hasAccess(callerId, doc)) throw new Error("Permission denied");

  // GOOD: same message for both cases
  if (!doc || !hasAccess(callerId, doc)) {
    log.warn({ callerId, docId, reason: doc ? "unauthorized" : "not_found" });
    return toolError("Document not found or not accessible");
  }

  return doc;
}

For authentication errors (missing or invalid API key), use the same message regardless of whether the key was missing, malformed, or invalid. Different messages ("key missing" vs "key invalid") let attackers confirm they have a key format that exists in your system.

This is the most common source of HIGH findings in SkillAudit audits. A handler that catches a database error and returns error.message might expose something like:

// What the caller sees with raw error propagation:
{
  "error": "SQLITE_CONSTRAINT: UNIQUE constraint failed: users.email",
  "stack": "Error: SQLITE_CONSTRAINT...\n  at /app/node_modules/better-sqlite3/lib/...\n  at /app/src/handlers/create-user.ts:47:22"
}

This tells an attacker: SQLite is the database, the table name is users, the unique field is email, and the server is running Node.js with better-sqlite3 installed at that exact path. The stack trace is effectively a map of your server's internals.

The fix is a thin error abstraction layer. Write it once; use it everywhere:

// src/lib/tool-error.ts
export class ToolError extends Error {
  constructor(
    public readonly toolName: string,
    public readonly userMessage: string,
    public readonly cause?: unknown,
  ) {
    super(userMessage);
    this.name = "ToolError";
  }
}

export function toolError(toolName: string, userMessage: string, cause?: unknown) {
  return new ToolError(toolName, userMessage, cause);
}

// src/lib/handle-error.ts
import { log } from "./logger.js";

export function handleToolError(toolName: string, err: unknown): never {
  if (err instanceof ToolError) {
    // Already abstracted — log cause if present, return user message
    if (err.cause) {
      log.error({ toolName, err: err.cause }, "tool error with cause");
    }
    // Return structured MCP error response
    return {
      isError: true,
      content: [{ type: "text", text: err.userMessage }],
    } as never;
  }

  // Unexpected error — log everything, return nothing useful
  log.error({ toolName, err }, "unexpected tool error");
  return {
    isError: true,
    content: [{ type: "text", text: `${toolName}: an unexpected error occurred` }],
  } as never;
}

// Using the abstraction in a handler:
server.tool("search_documents", SearchSchema, async (args) => {
  try {
    const results = await db.search(args.query, args.limit);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  } catch (err) {
    if (err instanceof DatabaseError && err.code === "QUERY_TIMEOUT") {
      throw toolError("search_documents", "Search timed out — try a more specific query", err);
    }
    if (err instanceof DatabaseError) {
      throw toolError("search_documents", "Search temporarily unavailable", err);
    }
    throw err; // Re-throw unexpected errors for the top-level handler
  }
});

Notice the tiered approach: known database errors get an appropriate user-facing message; unknown errors are re-thrown for the top-level handler to catch and log. The real error (err) travels as cause in your structured logs — never in the response body.

MCP servers are long-running processes. A single tool invocation that throws an unhandled error will crash the server only if there is no top-level catch. In the @modelcontextprotocol/sdk, the server.tool callback is already wrapped by the SDK's transport layer — unhandled throws become JSON-RPC error responses rather than process crashes. But that default behavior still leaks the raw error message and stack trace to the caller.

The defensive pattern is a top-level wrapper around every handler that catches anything the inner code didn't handle:

// src/lib/safe-tool.ts
import { log } from "./logger.js";

export function safeTool<TInput, TOutput>(
  name: string,
  handler: (args: TInput) => Promise<TOutput>,
): (args: TInput) => Promise<TOutput> {
  return async (args: TInput) => {
    try {
      return await handler(args);
    } catch (err) {
      if (err instanceof ToolError) {
        log.warn({ tool: name, msg: err.userMessage, cause: err.cause });
        return {
          isError: true,
          content: [{ type: "text", text: err.userMessage }],
        } as unknown as TOutput;
      }
      // Truly unexpected — log with full context, return opaque message
      log.error({ tool: name, err }, "unhandled tool error");
      return {
        isError: true,
        content: [{ type: "text", text: `${name}: internal error` }],
      } as unknown as TOutput;
    }
  };
}

// Usage:
server.tool(
  "get_issue",
  GetIssueSchema,
  safeTool("get_issue", async (args) => {
    // handler code here
  }),
);

With this wrapper, every tool has a guaranteed last line of defense. Unexpected panics (null dereference, failed assertion, unhandled promise rejection) all resolve to "tool_name: internal error" in the caller's response, while the full error with stack trace lands in your structured logs for debugging.