Published Updated

MCP Python SDK can turn an HTTP image into corrupted text

A valid PNG loses its original bytes when HttpResource decodes it as text, while the same image returned through BinaryResource is preserved.

An image should survive the handoff

A research figure must retain its original bytes when an application retrieves it. In a check of the MCP Python SDK’s HTTP resource helper, a valid PNG image instead arrived as text containing replacement characters. The read reported success and kept the image/png label, but the original image could no longer be recovered from that text.

Tasuku Kobayashi submitted MCP Python SDK issue #3843 on November 9, 2026. Contributor media-ctrl has since posted a matching reproduction on the released SDK. The issue remains open; maintainer confirmation, an agreed repair and a merged fix remain pending.

One image, two resource paths

The reproducer serves a valid 69-byte, one-pixel RGB PNG from a local HTTP endpoint with a successful 200 response and Content-Type: image/png. It then reads the resource through the public Client(server).read_resource() API. No SDK patch or transport mock is used.

Resource pathClient receivesData check
BinaryResource, same PNGBlobResourceContentsBase64 decoding restores all 69 bytes
HttpResource, PNGTextResourceContentsReplacement characters; UTF-8 re-encoding produces 95 bytes and does not restore the image
HttpResource, UTF-8 JSON with Japanese textTextResourceContentsAll 31 bytes preserved

The PNG’s chunk checksums and decompressed pixel data were independently checked. The binary control separates this result from an error in MCP’s base64 encoding; the JSON control shows that the failure is not shared by all HTTP resources.

The result reproduces with the released mcp 2.3.0 and mcp-types 2.3.0, using httpx2 2.16.0, Pydantic 2.14.3 and AnyIO 4.16.0. It also reproduces on main at 77001c9 with its frozen dependencies. Both runs used CPython 3.12.14 on Linux x86_64.

A contributor reproduces the failure and identifies a compatibility check

In a November 9 comment, media-ctrl reports reproducing the same result on mcp 2.3.0 using a loopback HTTP server and the public client: the binary control preserves all 69 bytes, while the HTTP image becomes text that re-encodes to 95 bytes. This is a contributor-reported reproduction, not a maintainer acceptance or a new local execution by Licklider.

Another contributor has offered to prepare a repair. The follow-up points out that the repair must preserve text delivery for JSON as well as preserve the PNG bytes. Python return type determines the downstream text/blob content class, so returning bytes for every HTTP resource would change working JSON clients. MIME precedence, charset and missing-header behavior remain design decisions for upstream agreement.

At this check, the issue has no assignee or help-wanted label, no maintainer comment, and no matching repair PR was found by searches for the issue number and HTTP binary-resource behavior. Current source still returnsresponse.text. These comments advance the report's evidence and repair discussion without adding an adopted fix.

Preserve binary data, or refuse it clearly

HttpResource.read() returns response.text unconditionally after checking the HTTP status. That converts the body to Unicode before the MCP layer chooses text or binary content. Labeling the resource as an image does not undo the conversion.

The report asks for preservation of the binary bytes, or an explicit refusal if this helper is intended only for text. The documentation introduces HttpResource as a ready-made resource class, but does not directly promise binary HTTP support. The observed successful, lossy conversion is the finding; a particular repair remains an upstream design decision.

This was an SDK integration investigation, not a reported SciGround production incident or a measurement of how often users encounter the path. The public issue contains the complete runnable example, output and environments.