Federated tool errors from the anyio/httpx transport family surface as an empty "Tool invocation failed: " (str(root_cause) is ''); ExceptionGroup-wrapped timeouts bypass the typed timeout lanes #6592

🐞 Bug Summary

Federated tools/call failures in the anyio/httpx transport family reach the caller as the bare string Tool invocation failed: — an empty detail — because invoke_tool's outer handler builds the caller-facing message as error_message = str(root_cause) and str() of the whole transport family is ''. A caller cannot tell a read timeout from a closed stream from a broken resource. The exception class is logged server-side but never reaches the message.

A second, related gap: a read timeout raised inside the MCP SDK's TaskGroup arrives as an ExceptionGroup, so it misses the per-transport except (asyncio.TimeoutError, httpx.TimeoutException) lanes (which produce the nice typed ToolTimeoutError / Tool invocation timed out after {effective_timeout}s), hits the per-transport except BaseException (which logs type(root_cause).__name__ and re-raises the group unchanged), and lands in the outer handler above — where it stringifies to ''.

🧩 Affected Component

• mcpgateway - API
• mcpgateway - UI (admin panel)
• mcpgateway.wrapper - stdio wrapper
• Federation or Transports
• CLI, Makefiles, or shell scripts
• Container setup (Docker/Podman/Compose)
• Other (explain below)

🔁 Steps to Reproduce

A. The str() proof — inside the published image's own venv (v1.0.8):

docker run --rm --entrypoint /app/.venv/bin/python3 ghcr.io/ibm/mcp-context-forge:v1.0.8 -c "
import anyio, httpx
print([repr(str(e())) for e in (anyio.ClosedResourceError, anyio.EndOfStream, anyio.BrokenResourceError, anyio.WouldBlock)])
print(repr(str(httpx.ReadTimeout(''))))"
# ["''", "''", "''", "''"]
# ''

(anyio 4.14.2, httpx 0.28.1, Python 3.12.13 in that image.)

B. Live, through the gateway (v1.0.8): register a streamable-HTTP MCP backend whose tool runs longer than tool_timeout (default 60 s) and call it via POST /servers/{id}/mcp tools/call. Observed: HTTP 200 after ~65 s with

{"result":{"content":[{"type":"text","text":"Tool invocation failed: "}],"isError":true}}

The server log for the same call carries error_type = the real class; the caller gets nothing.

C. Where it happens (mcpgateway/services/tool_service.py):

• v1.0.8 — outer except BaseException as e: of invoke_tool at :6716; error_message = str(root_cause) at :6723; emitted at :6740 (post-invoke ToolResult) and :6780 (raise ToolInvocationError(f"Tool invocation failed: {error_message}")).
• main@1321848 (checked 2026-09-03) — same construction, now at :7029; still no fallback. The bare except (asyncio.TimeoutError, httpx.TimeoutException): lanes are at :5895, :6359, :6546, :6825 and still do not see an ExceptionGroup-wrapped timeout.

🤔 Expected Behavior

The caller-facing message should never be empty. Two small changes at the one construction site would do it (this is what we ship as a build-time patch on our pinned image):

error_message = str(root_cause) or f"{type(root_cause).__module__}.{type(root_cause).__qualname__}"
if isinstance(root_cause, (asyncio.TimeoutError, httpx.TimeoutException)):
    error_message = f"Tool invocation timed out after {effective_timeout}s ({type(root_cause).__module__}.{type(root_cause).__qualname__})"

• str(root_cause) or <class> is byte-identical for every exception whose str() is already non-empty (e.g. httpx.HTTPStatusError for a 503), so nothing that works today changes.
• The timeout branch reuses the wording the per-transport lanes already emit, so callers key on one vocabulary regardless of whether the timeout arrived group-wrapped. With this in place the live call in (B) returns Tool invocation failed: Tool invocation timed out after 60s (builtins.TimeoutError).

(The nested-group recursion while isinstance(root_cause, BaseExceptionGroup) and root_cause.exceptions: already unwraps to the leaf — thank you — so the leaf is the right thing to name.)

📓 Logs / Error Output

Caller-facing (v1.0.8, unmodified image), read-timeout case:

Tool invocation failed: 

Same call after the change above:

Tool invocation failed: Tool invocation timed out after 60s (builtins.TimeoutError)

🧠 Environment Info

🧩 Additional Context (optional)

The empty-str() family is a property of anyio/httpx, not of the gateway — but the gateway is the only place that can add the class before the message leaves. We currently carry this as a one-anchor exact-match patch applied at image build; happy to open a PR if the shape above is acceptable.