[v1.x] Server-side outputSchema validation blocks tool error reporting (isError: true)

[kimsehwan96]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

When a tool handler returns unstructured content for an error case, the low-level server's call_tool decorator validates the output against outputSchema before checking if the response is an error.

This prevents tools with outputSchema from reporting errors via isError: true, as the validation fails with "outputSchema defined but no structured output returned", replacing the original error message.

This was already fixed in the TypeScript SDK via modelcontextprotocol/typescript-sdk#654 / PR #655 (2025-06-24), but the equivalent fix has not been applied to the Python SDK v1.x branch.

The issue is in src/mcp/server/lowlevel/server.py, the call_tool decorator handler:

1. Line ~560: outputSchema validation runs unconditionally — should skip when the result is an error
2. Line ~575: isError=False is hardcoded — there is no path for the handler to signal an error through unstructured content while outputSchema is defined

Example Code

from mcp.server.lowlevel import Server
from mcp import types

server = Server("test")

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    # Tool has outputSchema but needs to return an error
    # This gets blocked by outputSchema validation
    return [types.TextContent(type="text", text="Resource not found")]

Python & MCP Python SDK

- Python: 3.11 / 3.12
- MCP SDK: v1.26.0+ (v1.x branch)

[mcp-claude]

bug confirmed on both main and v1.x. when a tool with an inferred output_schema returns CallToolResult(is_error=True), the SDK's convert_result() calls model_validate(None) unconditionally, raising a pydantic error that replaces the intended error message.

workaround: tools can raise an exception (caught as ToolError by the framework) instead of returning CallToolResult(is_error=True).

fix (one-line change, same on both branches):

-            if self.output_schema is not None:
+            if self.output_schema is not None and not result.is_error:

on main: src/mcp/server/mcpserver/utilities/func_metadata.py:106
on v1.x: src/mcp/server/fastmcp/utilities/func_metadata.py:115

needs a backport PR to v1.x after main is merged.

repro + output + code path

repro script (repro.py):

import asyncio
from mcp.server.mcpserver import MCPServer
from mcp.types import CallToolResult, TextContent

async def main():
    app = MCPServer("test-server")

    @app.tool()
    async def divide(a: float, b: float) -> float:
        """Divide a by b."""
        if b == 0:
            return CallToolResult(
                content=[TextContent(type="text", text="Division by zero")],
                is_error=True,
            )
        return a / b

    from unittest.mock import MagicMock
    mock_ctx = MagicMock()

    result = await app._tool_manager.call_tool(
        "divide", {"a": 10.0, "b": 0.0}, mock_ctx, convert_result=True
    )
    print(result)

asyncio.run(main())

command + output (before fix):

$ uv run python repro.py
EXCEPTION (bug reproduced): ToolError: Error executing tool divide: 1 validation error for divideOutput
  Input should be a valid dictionary or instance of divideOutput [type=model_type, input_value=None, input_type=NoneType]

command + output (after fix):

$ uv run python repro.py
meta=None content=[TextContent(type='text', text='Division by zero', ...)] structured_content=None is_error=True

code path:

1. MCPServer._handle_call_tool → self.call_tool(...) → _tool_manager.call_tool(..., convert_result=True)
2. Tool.run() (tools/base.py:103) calls the fn, gets back CallToolResult(is_error=True, structured_content=None)
3. fn_metadata.convert_result(result) is called (func_metadata.py:105)
4. Line 105: isinstance(result, CallToolResult) → True
5. Line 106: if self.output_schema is not None: → True (schema was inferred from -> float)
6. Line 108: self.output_model.model_validate(result.structured_content) → model_validate(None) → pydantic ValidationError
7. Exception propagates up through Tool.run()'s except Exception at base.py:118, re-raised as ToolError
8. _handle_call_tool catches generic exceptions and returns CallToolResult(is_error=True, content=[str(ToolError)]) — which now contains the pydantic error, not "Division by zero"

suggested fix

# src/mcp/server/mcpserver/utilities/func_metadata.py
-            if self.output_schema is not None:
+            if self.output_schema is not None and not result.is_error:

same change needed in src/mcp/server/fastmcp/utilities/func_metadata.py for the v1.x backport.

test to verify: test_tool_call_result_annotated_is_error_skips_validation — confirms that convert_result() on a CallToolResult(is_error=True) with a typed output schema returns the result unchanged without raising a pydantic validation error.