MCP tool errors lose ErrorData and become HTTP 500 with traceback

[M4n5ter]

Problem

When calling MCP tools through the runtime HTTP API, tool failures are surfaced as a generic HTTP 500 string, and the original MCP ErrorData (especially data) is lost. The error message also includes a full traceback, which is noisy for end users.

This makes it hard for adapters like sandbox_tool_adapter to display the real error cause (e.g., invalid patch: The last line of the patch must be '*** End Patch').

Examples (actual outputs)

Initial error (only HTTP error string):

[{"type": "text", "text": "500 Server Error: Internal Server Error for url: http://localhost:49156/fastapi/mcp/call_tool"}]

After adding custom handling on the client side, we can see more detail, but it is still wrapped in a 500 error + traceback and ErrorData.data is lost:

[{"type": "text", "text": "MCP tool call failed: apply_patch\nstatus=500\nendpoint=http://10.10.2.200:49156/fastapi/mcp/call_tool\ndetail:\ninvalid patch: Traceback (most recent call last):\n  File \"/agentscope_runtime/routers/mcp.py\", line 162, in call_tool\n    result = await server.call_tool(tool_name, arguments)\n             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  File \"/agentscope_runtime/routers/mcp_utils.py\", line 158, in call_tool\n    result = await self.session.call_tool(tool_name, arguments)\n             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  File \"/agentscope_runtime/venv/lib/python3.11/site-packages/mcp/client/session.py\", line 277, in call_tool\n    return await self.send_request(\n           ^^^^^^^^^^^^^^^^^^^^^^^^\n  File \"/agentscope_runtime/venv/lib/python3.11/site-packages/mcp/shared/session.py\", line 294, in send_request\n    raise McpError(response_or_error.error)\nmcp.shared.exceptions.McpError: invalid patch\n"}]

Current workaround in our stack (not ideal; just shows we are forced to flatten the error ourselves):

[{"type": "text", "text": "{\"code\":\"INVALID_PARAMS\",\"data\":{\"error\":\"invalid patch: The last line of the patch must be '*** End Patch'\"},\"message\":\"invalid patch\"}"}]

Expected behavior

For MCP tool errors, preserve the original ErrorData (code/message/data) and avoid wrapping it into an HTTP 500 + traceback. Ideally, the runtime should return a normal CallToolResult with isError=true and put the structured error into structuredContent, so client adapters can display meaningful error details without custom hacks.

Suspected locations

• src/agentscope_runtime/sandbox/box/shared/routers/mcp.py catches all exceptions and raises HTTPException with detail=traceback, which discards ErrorData.data.
• src/agentscope_runtime/sandbox/client/http_client.py returns only str(e) on non-2xx responses, so the response body is lost even if it contains error details.

Question

Is the intended design to surface tool failures via CallToolResult.isError=true rather than raising HTTP 500? If so, I can prepare a PR to:

1. Convert McpError to CallToolResult in the runtime router, preserving code/message/data.
2. Improve the HTTP client to parse error responses when non-2xx.

Would this be acceptable to maintainers?

[M4n5ter]

Here is the minimal Python-side workaround we use to capture the real error body (no business code), because the default client only returns str(e) on non-2xx:

import requests

def call_mcp_tool_raw(base_url: str, tool_name: str, arguments: dict):
    resp = requests.post(
        f"{base_url}/mcp/call_tool",
        json={"tool_name": tool_name, "arguments": arguments},
        timeout=10,
    )
    if resp.ok:
        return resp.json()

    # capture error body (detail/error/json/text) instead of only str(e)
    try:
        body = resp.json()
    except Exception:
        body = resp.text
    return {
        "isError": True,
        "content": [{"type": "text", "text": f"HTTP {resp.status_code}: {body}"}],
    }

This bypasses the default SandboxHttpClient.call_tool error handling so we can see the runtime response detail, but it still carries the full traceback and loses ErrorData.data. Ideally the runtime should return a normal CallToolResult with isError=true and structured error data instead of raising HTTP 500.

[M4n5ter]

Would you share your preferred direction for fixing this? I see three possible approaches, each with different tradeoffs:

1. Client-only: Improve SandboxHttpClient.call_tool to parse non-2xx bodies and surface detail/error. Low risk but still leaves 500 + traceback and can’t reliably preserve ErrorData.data.
2. Runtime router: Catch McpError in /mcp/call_tool and return a normal CallToolResult with isError=true + structured error (code/message/data). Cleaner UX, avoids traceback noise, preserves data.
3. Lower-level runtime: Handle McpError inside the MCP session utils (e.g., in mcp_utils), returning CallToolResult earlier. More invasive but might be most semantically correct.

[rayrayraykk]

Great suggestions, I prefer handle in mcp_utils . And when Internal Server Error happens, we might rewrite the error message in sandbox sdk.

2026-01-08 Updated
I am working on this feature, possibly coming in days.