ProxyTool crashes on non-TextContent error responses

[strawgate]

When a proxied server returns an error with non-TextContent (e.g., ImageContent), ProxyTool.run() crashes with AttributeError.

The error path in proxy.py does:

if result.isError:
    raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)

cast() is a no-op at runtime — if content[0] is ImageContent or EmbeddedResource, accessing .text raises AttributeError.

Reproduction:

import mcp.types
result = mcp.types.CallToolResult(
    isError=True,
    content=[mcp.types.ImageContent(type="image", data="abc", mimeType="image/png")]
)
result.content[0].text  # AttributeError: 'ImageContent' object has no attribute 'text'

Fix: check isinstance(content, TextContent) before accessing .text, fall back to str(content) for other types.

[marvin-context-protocol]

Claude finished @strawgate's task in 1m 15s —— View job

---

Triage

• Read src/fastmcp/server/providers/proxy.py
• Confirm bug via reading code + MRE
• Find existing precedent for correct handling
• Draft action plan

---

tl;dr: Confirmed bug at src/fastmcp/server/providers/proxy.py:161. The cast() is a typing-only no-op, so when the backend returns an error with non-text content (e.g. ImageContent, EmbeddedResource) or with an empty content list, ProxyTool.run() raises AttributeError / IndexError instead of a useful ToolError. The fix is small and there is already a correctly-implemented precedent in the codebase to mirror.

Recommendation

Replace the cast(...).text call with a defensive isinstance-checked extraction that mirrors the existing client-side logic at src/fastmcp/client/mixins/tools.py:389-393. That code already handles exactly this case safely:

if result.content and isinstance(result.content[0], mcp.types.TextContent):
    msg = result.content[0].text
else:
    msg = f"Tool '{name}' returned an error"
raise ToolError(msg)

For the proxy path, apply the same guard but include the backend tool name in the fallback message so debugging a proxied call remains useful.

Findings

The offending line:

# src/fastmcp/server/providers/proxy.py:160-161
if result.isError:
    raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)

Two latent failure modes:

1. Non-text content — If result.content[0] is ImageContent / EmbeddedResource / AudioContent, .text raises AttributeError. typing.cast is a no-op at runtime, so it provides no protection. The reporter's MRE is accurate.
2. Empty content list — Servers are allowed to return isError=True with no content. result.content[0] raises IndexError.

Both cases surface as opaque AttributeError / IndexError instead of the intended ToolError, and they mask the real backend error.

The correct pattern already exists in this repo at src/fastmcp/client/mixins/tools.py:389-393. The proxy path was written independently and missed the same guard. Grepping for the cast(mcp.types.TextContent, ...).text pattern across src/ returns exactly one hit — the proxy — so this is a localized fix.

This occurrence is not new; git log -S shows the line predates recent commits (it just happens to show up under the current branch's HEAD).

Verification

Could not run the MRE directly — no uv/venv on this sandbox. The bug is mechanically obvious from reading the code: typing.cast performs no runtime narrowing, and mcp.types.ImageContent has no text attribute. The reporter's repro is minimal and self-evidently correct.

Detailed Action Plan

1. Edit src/fastmcp/server/providers/proxy.py around line 160-161. Replace:

   if result.isError:
       raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)

   with:

   if result.isError:
       if result.content and isinstance(result.content[0], mcp.types.TextContent):
           msg = result.content[0].text
       else:
           msg = f"Proxied tool {self._backend_name!r} returned an error"
       raise ToolError(msg)

   Remove the now-unused cast import if it isn't used elsewhere in the file (check top of file — it's likely only used here).

2. Add regression tests in tests/server/ (see existing test_proxy* files). Cover three cases against a FastMCPProxy wrapping a backend that returns isError=True with:

   • A single ImageContent (primary repro from the issue) → expect ToolError, not AttributeError.
   • An empty content list → expect ToolError, not IndexError.
   • A TextContent (existing happy path) → message is preserved verbatim (regression guard).

3. Run checks per CLAUDE.md:

   uv sync
   uv run pytest -n auto
   uv run prek run --all-files
   

4. Open a PR with a 1–2 paragraph body describing the cast() no-op footgun and the isinstance fix, linking this issue. This qualifies as a bug label.

No docs changes needed — this is internal error-path behavior.

Related Files

File	Relevance	Lines
src/fastmcp/server/providers/proxy.py	The buggy line — unsafe cast().text in ProxyTool.run() error path.	160-161
src/fastmcp/client/mixins/tools.py	Already-correct precedent: isinstance-checked extraction with a fallback message. Mirror this shape.	388-393

Related Webpages

Name	URL	Relevance
typing.cast docs	https://docs.python.org/3/library/typing.html#typing.cast	Confirms cast() is a runtime no-op — the core reason the current code fails.
MCP CallToolResult schema	https://modelcontextprotocol.io/specification/2025-06-18/server/tools	Specifies that content is a heterogeneous list (text / image / audio / resource), and isError can accompany any of them.

· branch: `claude/issue-3922-20260414-0406`

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.