Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(mcp): report SDK errors to MCP clients instead of a generic message

Maohao4c5b3dc90738
diff --git a/sdks/mcp/sandbox/python/src/opensandbox_mcp/server.py b/sdks/mcp/sandbox/python/src/opensandbox_mcp/server.py
index 5a0e52ef9..f94838b25 100644
--- a/sdks/mcp/sandbox/python/src/opensandbox_mcp/server.py
+++ b/sdks/mcp/sandbox/python/src/opensandbox_mcp/server.py
@@ -15,6 +15,7 @@
from __future__ import annotations
import asyncio
+import functools
from dataclasses import dataclass, field
from datetime import timedelta
@@ -22,6 +23,7 @@ from mcp.server.mcpserver import Context, MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from opensandbox import Sandbox, SandboxManager
from opensandbox.config import ConnectionConfig
+from opensandbox.exceptions import SandboxException
from opensandbox.models.execd import Execution, RunCommandOpts
from opensandbox.models.filesystem import (
ContentReplaceEntry,
@@ -123,7 +125,18 @@ def register_tools(
def decorator(func):
if name_prefix:
func.__name__ = f"{name_prefix}{func.__name__}"
- return mcp.tool()(func)
+
+ # MCP 2.x reports any exception other than ToolError as a bare
+ # "Error executing tool"; SDK errors (not found, auth, ...) are
+ # expected outcomes the client needs to see.
+ @functools.wraps(func)
+ async def call(*args, **kwargs):
+ try:
+ return await func(*args, **kwargs)
+ except SandboxException as exc:
+ raise ToolError(str(exc)) from exc
+
+ return mcp.tool()(call)
return decorator
diff --git a/sdks/mcp/sandbox/python/tests/test_mcp2_protocol.py b/sdks/mcp/sandbox/python/tests/test_mcp2_protocol.py
index 26406546a..1a2ec717a 100644
--- a/sdks/mcp/sandbox/python/tests/test_mcp2_protocol.py
+++ b/sdks/mcp/sandbox/python/tests/test_mcp2_protocol.py
@@ -25,6 +25,7 @@ from mcp import types
from mcp.client.session import ClientSession
from mcp.shared.memory import create_client_server_memory_streams
from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERSION
+from opensandbox.exceptions import SandboxApiException
from opensandbox_mcp.server import create_server
@@ -126,6 +127,26 @@ async def test_mcp2_expected_tool_errors_keep_actionable_message() -> None:
)
+async def test_mcp2_sandbox_errors_keep_actionable_message(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ class _MissingSandboxManager(_FakeManager):
+ async def kill_sandbox(self, sandbox_id: str) -> None:
+ raise SandboxApiException(f"Sandbox {sandbox_id} not found", status_code=404)
+
+ monkeypatch.setattr("opensandbox_mcp.server.SandboxManager", _MissingSandboxManager)
+
+ async with _client_session() as mcp_session:
+ await mcp_session.initialize()
+ result = await mcp_session.call_tool(
+ "sandbox_kill", {"sandbox_id": "sbx-missing"}
+ )
+
+ assert isinstance(result, types.CallToolResult)
+ assert result.is_error is True
+ assert "Sandbox sbx-missing not found" in _text_content(result)
+
+
async def test_mcp2_unknown_tool_is_an_error_result() -> None:
async with _client_session() as mcp_session:
await mcp_session.initialize()