Image/ImageContent serialization fails in stateless HTTP mode

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

Description

When using FastMCP with stateless_http=True (required by Claude.ai remote MCP), returning Image or ImageContent from a @mcp.tool() function results in serialization errors. Text-only tool results work fine in the same configuration.

Environment

• mcp version: 1.26.0 (also tested with >=1.8.0 unpinned)
• Python: 3.12
• Transport: streamable-http
• Deployment: Railway (remote, accessed by Claude.ai)
• Client: Claude.ai (requires stateless_http=True)

Reproduction

Minimal server:

from mcp.server.fastmcp import FastMCP, Image

mcp = FastMCP(
    "test",
    host="0.0.0.0",
    port=8000,
    stateless_http=True,
    json_response=True,
)

@mcp.tool()
def text_tool() -> str:
    """Works fine"""
    return "hello"

@mcp.tool()
def image_tool() -> Image:
    """Fails with serialization error"""
    # 1x1 red PNG
    data = bytes.fromhex(
        "89504e470d0a1a0a0000000d49484452000000010000000108020000009001"
        "2e00000000c4948444154789c6260f8cf00000000020001e221bc330000000049454e44ae426082"
    )
    return Image(data=data, format="png")

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

What happens

Attempt 1: Image class + stateless_http=True + json_response=True

Unable to serialize unknown type: <class 'mcp.server.fastmcp.utilities.types.Image'>

Attempt 2: Image class + stateless_http=True + json_response=False

Same serialization error.

Attempt 3: ImageContent from mcp.types + stateless_http=True

{"error": "Error occurred during tool execution"}

Server returns 200 OK but client receives generic error.

Attempt 4: Image class + stateless_http=False (stateful mode)

POST /mcp HTTP/1.1" 400 Bad Request

Claude.ai rejects stateful mode entirely.

Expected behavior

Image and ImageContent should serialize correctly in stateless_http=True mode, since:

1. The MCP spec defines ImageContent as a valid tool result content type
2. ToolResultContent.content accepts ContentBlock lists which include image content
3. The official SDK docs show @mcp.tool() returning Image as a supported pattern
4. The protocol's Streamable HTTP transport has no text-only restriction — it returns either application/json or text/event-stream, both capable of carrying base64-encoded image data

Context

This blocks any MCP server deployed for Claude.ai from returning images via tool results. The only workaround is returning image URLs as text, which doesn't work for authenticated/signed URLs (e.g., Notion S3 hosted images that require download proxying).

Related

• Python SDK Image example: https://github.com/modelcontextprotocol/python-sdk#primitives
• MCP spec tool results: https://spec.modelcontextprotocol.io/specification/server/tools/

Example Code

Python & MCP Python SDK

MCP version: 1.26.0
Python: 3.12

先使用無狀態 HTTP 和 Image 結果開始最小化的 FastMCP 重現，然後追蹤 streamable-HTTP 傳輸的工具結果序列化路徑。將其與正常運作的純文字結果以及 ImageContent 嘗試進行比較。當 Image 和 ImageContent 工具結果在無狀態模式下能夠攜帶 base64 圖像資料成功返回時，即視為完成。