Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(transforms): enforce wall-clock timeout and external callback limit in MontySandboxProvider and CodeMode (#6063)

Praising Harris Ratnam90f9077d3dbf
diff --git a/docs/servers/transforms/code-mode.mdx b/docs/servers/transforms/code-mode.mdx
index 117f7929b..70a121848 100644
--- a/docs/servers/transforms/code-mode.mdx
+++ b/docs/servers/transforms/code-mode.mdx
@@ -337,7 +337,7 @@ Time, memory, and GC limits are optional; omit a key to disable that limit. Recu
| `max_recursion_depth` | `int` | Maximum recursion depth |
| `gc_interval` | `int` | Garbage collection frequency |
-Duration limits exclude time spent waiting for host tools. The feed limit covers the entire code block; the turn limit resets after each host round trip.
+Duration limits exclude time spent waiting for host tools. The feed limit covers the entire code block; the turn limit resets after each host round trip. To bound the total time an `execute` call takes, including tool calls, use a [wall-clock limit](#wall-clock-limit).
Unsupported keys raise `ValueError` rather than being silently ignored. Replace `max_duration_secs` with `max_feed_duration_secs` in existing configurations. Monty no longer supports `max_allocations`; use `max_memory` to cap memory usage.
@@ -353,6 +353,16 @@ CodeMode(max_tool_calls=200) # raise the cap
CodeMode(max_tool_calls=None) # no cap
```
+### Wall-Clock Limit
+
+Sandbox duration limits stop counting while the code waits on `call_tool()`, so a slow or hanging backend tool can keep an `execute` call open indefinitely. Set `wall_clock_timeout_secs` to cap the total elapsed time of each `execute` call, sandbox and tool calls together. When the limit is reached, the sandbox and any in-flight tool calls are cancelled and `execute` raises a `ToolError`. It applies to any sandbox provider and defaults to `None` (no limit):
+
+```python
+from fastmcp.experimental.transforms.code_mode import CodeMode
+
+CodeMode(wall_clock_timeout_secs=60)
+```
+
### Custom Sandbox Providers
You can replace the default sandbox with any object implementing the `SandboxProvider` protocol. The `code` it receives is untrusted, LLM-generated Python: run it in an isolated sandbox, never with plain `exec()`.
diff --git a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
index af774e3bf..ddcc4de50 100644
--- a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
+++ b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py
@@ -633,11 +633,13 @@ class CodeMode(CatalogTransform):
execute_tool_name: str = "execute",
execute_description: str | None = None,
max_tool_calls: int | None = 50,
+ wall_clock_timeout_secs: float | None = None,
) -> None:
super().__init__()
self.execute_tool_name = execute_tool_name
self.execute_description = execute_description
self.max_tool_calls = max_tool_calls
+ self.wall_clock_timeout_secs = wall_clock_timeout_secs
self.sandbox_provider = sandbox_provider or MontySandboxProvider()
self._discovery_factories = (
@@ -748,10 +750,21 @@ class CodeMode(CatalogTransform):
)
return _unwrap_tool_result(result)
- return await transform.sandbox_provider.run(
+ # Sandbox duration limits exclude time spent awaiting host
+ # callbacks, so bound the whole execution on the wall clock.
+ timeout = transform.wall_clock_timeout_secs
+ run = transform.sandbox_provider.run(
code,
external_functions={"call_tool": call_tool},
)
+ if timeout is None:
+ return await run
+ try:
+ return await asyncio.wait_for(run, timeout)
+ except TimeoutError as exc:
+ raise ToolError(
+ f"Execution exceeded the wall-clock limit of {timeout} seconds."
+ ) from exc
return Tool.from_function(
fn=execute,
diff --git a/tests/experimental/transforms/test_code_mode.py b/tests/experimental/transforms/test_code_mode.py
index abbe2d8c5..68a4fe6f9 100644
--- a/tests/experimental/transforms/test_code_mode.py
+++ b/tests/experimental/transforms/test_code_mode.py
@@ -1008,6 +1008,51 @@ async def test_code_mode_max_tool_calls_none_is_unlimited() -> None:
assert _unwrap_result(result) == 60
+async def test_code_mode_wall_clock_timeout_raises_tool_error() -> None:
+ """A tool call outlasting the wall-clock limit fails the execute call."""
+ mcp = FastMCP("CodeMode Timeout")
+
+ @mcp.tool
+ async def slow_tool() -> str:
+ await asyncio.sleep(5)
+ return "done"
+
+ mcp.add_transform(
+ CodeMode(
+ sandbox_provider=_UnsafeTestSandboxProvider(),
+ wall_clock_timeout_secs=0.05,
+ )
+ )
+
+ code = "await call_tool('slow_tool', {})\nreturn 1"
+ with pytest.raises(ToolError, match="wall-clock limit of 0.05 seconds"):
+ await _run_tool(mcp, "execute", {"code": code})
+
+
+@requires_monty
+async def test_code_mode_wall_clock_timeout_bounds_monty_callbacks() -> None:
+ """Monty's duration limits skip callback time; the wall clock does not."""
+ mcp = FastMCP("CodeMode Monty Timeout")
+ callback_cancelled = asyncio.Event()
+
+ @mcp.tool
+ async def hang() -> str:
+ try:
+ await asyncio.sleep(5)
+ except asyncio.CancelledError:
+ callback_cancelled.set()
+ raise
+ return "done"
+
+ mcp.add_transform(CodeMode(wall_clock_timeout_secs=1))
+
+ code = "await call_tool('hang', {})\nreturn 1"
+ with pytest.raises(ToolError, match="wall-clock limit"):
+ await _run_tool(mcp, "execute", {"code": code})
+
+ assert callback_cancelled.is_set()
+
+
async def test_monty_provider_cancels_future_when_task_cancelled() -> None:
"""Cancelling the awaiting task must cancel the underlying sandbox future.