René's URL Explorer Experiment


Title: Structured tool output: `-> bytes` return crashes with a generic error on non-UTF-8 payloads instead of returning the advertised base64/binary string · Issue #3554 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Structured tool output: `-> bytes` return crashes with a generic error on non-UTF-8 payloads instead of returning the advertised base64/binary string · Issue #3554 · modelcontextprotocol/python-sdk

X Title: Structured tool output: `-> bytes` return crashes with a generic error on non-UTF-8 payloads instead of returning the advertised base64/binary string · Issue #3554 · modelcontextprotocol/python-sdk

Description: Initial Checks I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1) I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before openi...

Open Graph Description: Initial Checks I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1) I confirm that I searched for my issue in https://github.com/modelcontex...

X Description: Initial Checks I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1) I confirm that I searched for my issue in https://github.com/mod...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3554

X: @github

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Structured tool output: `-> bytes` return crashes with a generic error on non-UTF-8 payloads instead of returning the advertised base64/binary string","articleBody":"### Initial Checks\n\n- [X] I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)\n- [X] I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue\n\n### Release line\n\n2.x (current stable)\n\n### Description\n\nA tool annotated `-> bytes` publishes `output_schema: {\"result\": {\"type\": \"string\", \"format\": \"binary\"}}`, but when the tool returns actual binary data (PNG magic bytes, a zip, a PDF - anything that is not valid UTF-8) the call fails inside `convert_result` with `PydanticSerializationError`. The client only receives `is_error: true` with the generic text `Error executing tool \u003cname>` and the data is lost. UTF-8-decodable bytes do not raise, but come back as a raw string (`{\"result\": \"hello\"}`) rather than any base64 encoding.\n\nObserved output (Python 3.13.15, mcp 2.2.0, macOS, run at the v2.2.0 tag):\n\n```\nadvertised output_schema: {'properties': {'result': {'format': 'binary', 'title': 'Result', 'type': 'string'}}, 'required': ['result'], 'type': 'object', 'title': 'read_thumbnailOutput'}\nis_error: True\ncontent: [TextContent(type='text', text='Error executing tool read_thumbnail', annotations=None, meta=None)]\nstructured: None\n[server] PydanticSerializationError: Error serializing to JSON: invalid utf-8 sequence of 1 bytes from index 0 — at func_metadata.py:653 in _convert_to_content, via convert_result:209\nUTF-8-decodable bytes b'hello' -> structured_content={'result': 'hello'} (raw string, not base64)\n```\n\nA `bytes` field inside an output model (e.g. `class Thumb(BaseModel): data: bytes`) hits the same crash, with the same advertised `format: binary` schema for that field.\n\n**Expected:** `bytes` is documented as a supported structured-output return type (docstring at `src/mcp/server/mcpserver/utilities/func_metadata.py:304` - \"Primitive types (str, int, float, bool, bytes, None) - wrapped in a model with a 'result' field\"; also `docs/servers/structured-output.md`: \"Every scalar gets the same wrapper: `str`, `int`, `float`, `bool`, `bytes`, `None`\"), and `tests/server/mcpserver/test_func_metadata.py` asserts the published `{\"type\": \"string\", \"format\": \"binary\"}` schema. So a `-> bytes` tool should deliver its payload to the client, encoded so it survives JSON - the way every other `bytes` path in this package already does: `server.py:475` uses `base64.b64encode(item.content).decode()` for `BlobResourceContents`, and `Image.to_image_content()` / `Audio.to_audio_content()` in `utilities/types.py` base64-encode their data. It should not raise on the first non-UTF-8 byte and swallow the payload behind a generic error.\n\n**Root cause:** `src/mcp/server/mcpserver/utilities/func_metadata.py:653` - `_convert_to_content` (reached from `convert_result`, func_metadata.py:209) serializes a non-str result with `pydantic_core.to_json(result, fallback=str, ...)`, which JSON-encodes `bytes` by UTF-8-decoding them; the `fallback` only applies to unknown types, so non-UTF-8 bytes raise `PydanticSerializationError`.\n\nIf it's useful I'm happy to describe or implement the approach (base64-encode `bytes` in `_convert_to_content` and the structured dump, following `Image`/`Audio`) - happy to be assigned.\n\nRelated: the open PRs touching `func_metadata.py` (#3119, #3118, #2939) cover argument forwarding, schema generation and `Annotated` metadata, not this; the base64 issues I found (#2376, #3123) are about the `Image` content path only.\n\nAI disclosure: this issue was prepared with AI assistance; the reproduction above was run and its output verified by me on the v2.2.0 tag.\n\n### Example Code\n\n```python\nimport asyncio\nimport sys\n\nsys.path.insert(0, \"src\")\nsys.path.insert(0, \".\")\n\nfrom mcp import MCPError\nfrom mcp.server.mcpserver import MCPServer\nfrom tests.interaction._connect import connect_in_memory\n\nPNG_MAGIC = b\"\\x89PNG\\r\\n\\x1a\\n\"  # every real PNG starts with this (invalid UTF-8)\n\n\nasync def main() -> None:\n    mcp = MCPServer(\"files\")\n\n    @mcp.tool()\n    def read_thumbnail(name: str) -> bytes:\n        \"\"\"Return a thumbnail's raw bytes.\"\"\"\n        return PNG_MAGIC + b\"\\x00\\x00\"\n\n    async with connect_in_memory(mcp) as client:\n        tools = await client.list_tools()\n        print(\"advertised output_schema:\", tools.tools[0].output_schema)\n        try:\n            result = await client.call_tool(\"read_thumbnail\", {\"name\": \"x.png\"})\n            print(\"OK:\", result.content)\n        except MCPError as e:\n            print(\"FAILED:\", e.error.code, e.error.message)\n\n\nasyncio.run(main())\n```\n\n### Python & MCP Python SDK\n\n```\nmcp (python-sdk): 2.2.0 (tag v2.2.0 = commit 9972c21, main)\nPython: 3.13.15\nOS: macOS (Darwin)\n```\n","author":{"url":"https://github.com/BlueX888","@type":"Person","name":"BlueX888"},"datePublished":"2026-09-21T01:45:22Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3554"}

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format)
route-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:07e70ddd-5961-8d3b-5320-2c3903f90d9c
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idD12E:21E3E7:9E0F63:D2828F:6B00E694
html-safe-nonced249e00a705b4ae79bbe906a7e3c5f9fd0d5520cfe91f49db64a5388744aeda2
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMTJFOjIxRTNFNzo5RTBGNjM6RDI4MjhGOjZCMDBFNjk0IiwidmlzaXRvcl9pZCI6IjU1MTQwNTU3NjI4OTQxODYxMzIiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmacb3cf29bebb79bab77604caeeaf6250791dfcdd4779838bad53ec447a7a7dc729
hovercard-subject-tagissue:5521834891
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3554/issue_layout
twitter:imagehttps://opengraph.githubassets.com/a7c40307ab215920d0d4532da9dc7ec8d314642baf5eca64625963a22e668cf4/modelcontextprotocol/python-sdk/issues/3554
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/a7c40307ab215920d0d4532da9dc7ec8d314642baf5eca64625963a22e668cf4/modelcontextprotocol/python-sdk/issues/3554
og:image:altInitial Checks I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1) I confirm that I searched for my issue in https://github.com/modelcontex...
og:image:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernameBlueX888
hostnamegithub.com
expected-hostnamegithub.com
None27088b6977484d0d3321d9a11c907c6d6637b315cfa359ef7952dbf6292f9b14
turbo-cache-controlno-preview
go-importgithub.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git
octolytics-dimension-user_id182288589
octolytics-dimension-user_loginmodelcontextprotocol
octolytics-dimension-repository_id862584018
octolytics-dimension-repository_nwomodelcontextprotocol/python-sdk
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id862584018
octolytics-dimension-repository_network_root_nwomodelcontextprotocol/python-sdk
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release624179fb8b88d26ba5bba08894eb60a1c5a1d93d
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/modelcontextprotocol/python-sdk/issues/3554#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2F3554
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2F3554
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=modelcontextprotocol%2Fpython-sdk
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3554
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3554
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3554
modelcontextprotocolhttps://github.com/modelcontextprotocol
python-sdkhttps://github.com/modelcontextprotocol/python-sdk
Codehttps://github.com/modelcontextprotocol/python-sdk
Issues308 (308)https://github.com/modelcontextprotocol/python-sdk/issues
Pull requests112 (112)https://github.com/modelcontextprotocol/python-sdk/pulls
Actionshttps://github.com/modelcontextprotocol/python-sdk/actions
Projectshttps://github.com/modelcontextprotocol/python-sdk/projects
Security and quality12 (12)https://github.com/modelcontextprotocol/python-sdk/security
Insightshttps://github.com/modelcontextprotocol/python-sdk/insights
https://github.com/modelcontextprotocol/python-sdk
New issuehttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3554
New issuehttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3554
Structured tool output: -> bytes return crashes with a generic error on non-UTF-8 payloads instead of returning the advertised base64/binary stringhttps://github.com/modelcontextprotocol/python-sdk/issues/3554#top
bugSomething isn't workinghttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22bug%22
v1Affects the v1.x maintenance linehttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v1%22
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
https://github.com/BlueX888
BlueX888https://github.com/BlueX888
on Sep 21, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#issue-5521834891
https://github.com/modelcontextprotocol/python-sdk/issueshttps://github.com/modelcontextprotocol/python-sdk/issues
#3119https://github.com/modelcontextprotocol/python-sdk/pull/3119
#3118https://github.com/modelcontextprotocol/python-sdk/pull/3118
#2939https://github.com/modelcontextprotocol/python-sdk/pull/2939
#2376https://github.com/modelcontextprotocol/python-sdk/issues/2376
#3123https://github.com/modelcontextprotocol/python-sdk/issues/3123
claudehttps://github.com/apps/claude
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
v1Affects the v1.x maintenance linehttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v1%22
on Sep 21, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#event-31500900713
https://github.com/hui455
hui455https://github.com/hui455
on Sep 21, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#issuecomment-5755528320
6affe5chttps://github.com/modelcontextprotocol/python-sdk/commit/6affe5c0d3588fd1705713b3703dc68015cfe3eb
https://github.com/siye566
siye566https://github.com/siye566
on Sep 21, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#issuecomment-5755775825
6affe5chttps://github.com/modelcontextprotocol/python-sdk/commit/6affe5c0d3588fd1705713b3703dc68015cfe3eb
https://github.com/siye566
siye566https://github.com/siye566
on Sep 22, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#issuecomment-5771011870
#3555https://github.com/modelcontextprotocol/python-sdk/pull/3555
#3554https://github.com/modelcontextprotocol/python-sdk/issues/3554
@siye566https://github.com/siye566
claudehttps://github.com/apps/claude
bugSomething isn't workinghttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22bug%22
on Oct 8, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3554#event-32781164043
Sign up for freehttps://github.com/signup?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3554
Sign in to commenthttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3554
bugSomething isn't workinghttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22bug%22
v1Affects the v1.x maintenance linehttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v1%22
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.