How to handle errors in an MCP server

1// TypeScript — correct error handling
2server.registerTool("get-user", {
3  description: "Get user profile by ID",
4  inputSchema: {
5    userId: z.string().describe("User ID"),
6  },
7}, async ({ userId }) => {
8  const user = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
9
10  if (!user) {
11    return {
12      content: [{ type: "text", text: `Error: No user found with ID '${userId}'` }],
13      isError: true,
14    };
15  }
16
17  return {
18    content: [{ type: "text", text: JSON.stringify(user, null, 2) }],
19    isError: false,
20  };
21});

1// TypeScript
2server.registerTool("query-api", {
3  description: "Query an external API endpoint",
4  inputSchema: {
5    endpoint: z.string().url().describe("API endpoint URL"),
6    method: z.enum(["GET", "POST"]).default("GET").describe("HTTP method"),
7  },
8}, async ({ endpoint, method }) => {
9  try {
10    const response = await fetch(endpoint, { method });
11
12    if (!response.ok) {
13      return {
14        content: [{
15          type: "text",
16          text: `Error: API returned HTTP ${response.status} ${response.statusText}. Check the endpoint URL and try again.`,
17        }],
18        isError: true,
19      };
20    }
21
22    const data = await response.json();
23    return {
24      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
25    };
26  } catch (error) {
27    // Log full error for debugging
28    console.error("query-api error:", error);
29
30    return {
31      content: [{
32        type: "text",
33        text: `Error: Failed to reach ${endpoint}. ${(error as Error).message}`,
34      }],
35      isError: true,
36    };
37  }
38});

1// TypeScript — specific error mapping
2async function handleApiError(error: unknown, context: string): {
3  content: Array<{ type: "text"; text: string }>;
4  isError: true;
5} {
6  const err = error as Error & { code?: string; status?: number };
7
8  if (err.code === "ETIMEDOUT" || err.code === "ECONNREFUSED") {
9    return {
10      content: [{ type: "text", text: `Error: ${context} — service unreachable. The API may be down. Try again in a moment.` }],
11      isError: true,
12    };
13  }
14  if (err.status === 401 || err.status === 403) {
15    return {
16      content: [{ type: "text", text: `Error: ${context} — authentication failed. Check API credentials.` }],
17      isError: true,
18    };
19  }
20  if (err.status === 404) {
21    return {
22      content: [{ type: "text", text: `Error: ${context} — resource not found. Verify the ID or path is correct.` }],
23      isError: true,
24    };
25  }
26  if (err.status === 429) {
27    return {
28      content: [{ type: "text", text: `Error: ${context} — rate limited. Wait before retrying.` }],
29      isError: true,
30    };
31  }
32
33  return {
34    content: [{ type: "text", text: `Error: ${context} — ${err.message}` }],
35    isError: true,
36  };
37}

1# Python
2from mcp.server.fastmcp import FastMCP
3import httpx
4
5mcp = FastMCP("error-handling-server")
6
7@mcp.tool()
8async def fetch_data(url: str) -> str:
9    """Fetch data from a URL.
10
11    Args:
12        url: The URL to fetch data from
13    """
14    try:
15        async with httpx.AsyncClient(timeout=10.0) as client:
16            response = await client.get(url)
17            response.raise_for_status()
18            return response.text
19    except httpx.TimeoutException:
20        raise ValueError(f"Error: Request to {url} timed out after 10 seconds")
21    except httpx.HTTPStatusError as e:
22        raise ValueError(f"Error: HTTP {e.response.status_code} from {url}")
23    except httpx.ConnectError:
24        raise ValueError(f"Error: Could not connect to {url}")

1// TypeScript — JSON-RPC error codes reference
2// -32700  Parse error (invalid JSON)
3// -32600  Invalid request (missing required fields)
4// -32601  Method not found
5// -32602  Invalid params (schema validation failure)
6// -32603  Internal error
7
8// The SDK handles these automatically. For custom errors:
9import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
10
11// Inside a tool handler or custom method:
12throw new McpError(
13  ErrorCode.InvalidParams,
14  "The 'format' parameter must be 'json' or 'csv'"
15);