fix: propagate McpError from tool handlers as JSON-RPC error#2772
Open
mengyunxie wants to merge 1 commit into
Open
fix: propagate McpError from tool handlers as JSON-RPC error#2772mengyunxie wants to merge 1 commit into
mengyunxie wants to merge 1 commit into
Conversation
a475afc to
60f8fc7
Compare
StantonMatt
reviewed
Jun 3, 2026
StantonMatt
left a comment
There was a problem hiding this comment.
Checked this against head 60f8fc7.
Focused local run passed:
uv run --frozen pytest tests/server/fastmcp/test_url_elicitation_error_throw.py tests/client/test_list_roots_callback.py tests/client/test_sampling_callback.py -q -> 8 passed
I also ran a small low-level Server.call_tool() probe because src/mcp/server/lowlevel/server.py changes separately from the FastMCP path. In that probe, McpError(ErrorData(code=-32000, message="server fault")) reached ClientSession.call_tool() as McpError, while a regular ValueError("regular failure") still returned CallToolResult(isError=True). That covers the low-level decorator behavior I would have wanted checked here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Context
When a tool handler raises
McpError, both the lowlevel server'scall_tooldecorator and FastMCP'sTool.run()catch it viaexcept Exceptionand wrap it asCallToolResult(isError=True). This loses the structured error code on the wire — clients cannot distinguish error types without parsing the message string.The existing
UrlElicitationRequiredError(a subclass ofMcpError) already had a re-raise bypass, but the parentMcpErrorclass did not. The v2McpServeronmainalready handles this correctly withexcept MCPError: raise.Fixes #2770
How Has This Been Tested?
test_mcp_error_in_tool_handler_propagates_as_jsonrpc_error— verifies McpError propagates as JSON-RPC error with code preservedtest_url_elicitation_error_thrown_from_tool— confirms UrlElicitationRequiredError still works (subclass of McpError)test_normal_exceptions_still_return_error_result— confirms regular exceptions still become isError:truetests/server/suite passes (503 tests)Breaking Changes
Servers that intentionally raise
McpErrorin tool handlers expecting it to be wrapped asisError:truewill now get a JSON-RPC error response instead. This is the correct behavior per MCP spec —McpErrorrepresents protocol-level errors, not tool execution failures.Types of changes
Checklist
Additional context
Two locations fixed:
src/mcp/server/lowlevel/server.py— thecall_tooldecorator handlersrc/mcp/server/fastmcp/tools/base.py— theTool.run()methodBoth now use
except McpError: raisewhich subsumes the previousexcept UrlElicitationRequiredError: raisesince it's a subclass.