Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Image/ImageContent serialization fails in stateless HTTP mode

Open
  • Is something wrong?
#2,376 3 comments 5 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python
Domain
api, backend

Research direction

Start with the minimal FastMCP reproduction using stateless HTTP and an Image result, then trace the tool-result serialization path for the streamable-HTTP transport. Compare it with the working text-only result and the ImageContent attempt. Done means Image and ImageContent tool results return successfully with base64 image data in stateless mode.

Written by the indexing model from the issue text.

Description

bug needs confirmation P2
Initial Checks
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

Example Code
Python & MCP Python SDK
MCP version: 1.26.0
Python: 3.12
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 16h
Merged PRs (30d)
25

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/python-sdk

All issues in modelcontextprotocol/python-sdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.