MCPServer handlers should raise exceptions, not return error objects

Bắt đầu với _handle_call_tool() trong src/mcp/server/mcpserver/server.py và _handle_request() trong src/mcp/server/lowlevel/server.py, so sánh các luồng xử lý exception và cách xây dựng response của chúng. Công việc hoàn tất khi các handler cấp cao có thể báo hiệu lỗi bằng cách raise, các handler cấp thấp có thể trả về ErrorData một cách tường minh, và các exception chưa được xử lý ở bất kỳ tầng nào cũng tạo ra các lỗi JSON-RPC đúng định dạng mà không làm lộ thông tin nội bộ.

Problem

The current error handling across the two server layers is inconsistent and confusing for users. As noted by Marcelo, the experience should be more like Starlette's raise HTTPException pattern.

Current behavior

MCPServer (high-level) tool handlers:

• Raising any exception → caught by Tool.run(), re-wrapped as ToolError, then caught by _handle_call_tool() → CallToolResult(isError=True) (a JSON-RPC success response)
• Raising MCPError → re-raised past _handle_call_tool() → becomes a JSON-RPC error response
• Returning CallToolResult(isError=True) directly → also works
• Resource/prompt handlers have no try/except at the MCPServer layer — exceptions propagate to the low-level server

Low-level server handlers:

• _handle_request() catches MCPError → sends its .error as a JSON-RPC error
• Any other Exception → ErrorData(code=0, message=str(err)) → JSON-RPC error with non-standard code

Users need to understand the difference between ToolError, MCPError, CallToolResult(isError=True), and plain exceptions — each produces different behavior depending on which layer catches it.

Desired behavior

1. MCPServer users should raise exceptions to signal errors — the framework converts them to the appropriate protocol response. No need to construct and return error result objects.
2. Low-level server users should return ErrorData explicitly when they want to control the JSON-RPC error response, since they operate at the protocol level.
3. Unhandled exceptions at either layer should be caught gracefully by the framework and returned as a well-formed JSON-RPC error, without leaking internal details to the client.

Related issues

• #1742 — Introduce typed error classes with metadata (covers error taxonomy but not the raise-vs-return layering)
• #698 — Tool.run should not reveal exception value to the client (security concern with current behavior)
• #396 — Inconsistent Exception Handling in @app.call_tool (older, narrower scope)
• #1788 — Extensible pattern for protocol flow-control exceptions

_{AI Disclaimer}