René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Bug: stdio transport fails to handle Content-Length header format from MCP clients","articleBody":"# Bug: stdio transport fails to handle Content-Length header format from MCP clients\n\n## Description\n\nThe `stdio_server` transport in `mcp/server/stdio.py` reads stdin line-by-line and attempts to parse each line as JSON. This works for NDJSON (newline-delimited JSON) format but **fails completely** when MCP clients send messages using the `Content-Length` header format.\n\nSeveral popular MCP clients (including those built on the TypeScript SDK `@modelcontextprotocol/sdk`) send stdio messages with `Content-Length` headers, following the pattern established by LSP (Language Server Protocol). This causes a compatibility gap where Python SDK-based servers cannot be initialized by these clients.\n\n## Steps to Reproduce\n\n1. Create a minimal MCP server using the Python SDK:\n```python\nfrom mcp.server.fastmcp import FastMCP\nmcp = FastMCP(\"test-server\")\nmcp.run(transport=\"stdio\")\n```\n\n2. Send an MCP `initialize` request using Content-Length header format (as used by TypeScript SDK-based clients):\n```\nContent-Length: 157\\r\\n\\r\\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}\n```\n\n3. Observe the server response.\n\n## Expected Behavior\n\nThe server should either:\n- (a) Properly parse the `Content-Length` header and read the specified number of bytes as the message body, **OR**\n- (b) Gracefully skip non-JSON lines (like `Content-Length` headers) and process valid JSON messages\n\n## Actual Behavior\n\nThe server reads the input line-by-line via `async for line in stdin:` and tries to parse each line as JSON:\n\n```python\n# mcp/server/stdio.py, line 60-68\nasync def stdin_reader():\n    async with read_stream_writer:\n        async for line in stdin:\n            try:\n                message = types.JSONRPCMessage.model_validate_json(line)\n            except Exception as exc:\n                await read_stream_writer.send(exc)\n                continue\n```\n\nWhen receiving `Content-Length` header format:\n\n1. Line `Content-Length: 157` → JSON parse error → exception sent to stream → **error notification emitted**\n2. Empty line `` → JSON parse error → exception sent to stream → **error notification emitted**\n3. JSON body without trailing newline → **never read** (stdin reader blocks waiting for `\\n`)\n\nThe server outputs two error notifications:\n```json\n{\"method\":\"notifications/message\",\"params\":{\"level\":\"error\",\"logger\":\"mcp.server.exception_handler\",\"data\":\"Internal Server Error\"},\"jsonrpc\":\"2.0\"}\n{\"method\":\"notifications/message\",\"params\":{\"level\":\"error\",\"logger\":\"mcp.server.exception_handler\",\"data\":\"Internal Server Error\"},\"jsonrpc\":\"2.0\"}\n```\n\nAnd the actual `initialize` response is **never sent**, causing the client to timeout with:\n```\nfailed to initialize MCP client: transport error: context deadline exceeded\n```\n\n## Verification\n\nI verified this with a Node.js test script that spawns the Python MCP server and sends messages in both formats:\n\n| Format | Result |\n|--------|--------|\n| NDJSON (raw JSON + `\\n`) | ? Success - correct `initialize` response |\n| Content-Length header + body (no trailing `\\n`) | ? Failed - 2 error notifications, no response (body never read) |\n| Content-Length header + body + `\\n` | ?? Partial - 2 error notifications + correct response (error notifications may confuse client) |\n\n## Environment\n\n- **mcp package version**: 1.27.0 (latest)\n- **Python version**: 3.14\n- **OS**: Windows 11\n- **MCP client**: Qoder IDE (uses TypeScript SDK)\n\n## Suggested Fix\n\nThe `stdin_reader` in `mcp/server/stdio.py` should be updated to handle both formats:\n\n**Option A: Skip non-JSON lines silently**\nInstead of sending parse exceptions to the stream, silently skip lines that don't parse as valid JSON-RPC messages. This would allow Content-Length header lines and empty lines to be ignored while processing the actual JSON body.\n\n```python\nasync def stdin_reader():\n    async with read_stream_writer:\n        async for line in stdin:\n            stripped = line.strip()\n            if not stripped:\n                continue  # Skip empty lines\n            try:\n                message = types.JSONRPCMessage.model_validate_json(stripped)\n            except Exception:\n                continue  # Skip non-JSON lines (e.g., Content-Length headers)\n            session_message = SessionMessage(message)\n            await read_stream_writer.send(session_message)\n```\n\n**Option B: Full Content-Length header support**\nImplement proper Content-Length header parsing (read header, extract length, read body of that length), falling back to NDJSON for backward compatibility.\n\n## Additional Context\n\n- The MCP specification (2025-03-26) states stdio messages are \"delimited by newlines\" (NDJSON format).\n- However, the TypeScript SDK (`@modelcontextprotocol/sdk`) uses `Content-Length` headers for stdio transport, creating a real-world compatibility gap.\n- Other projects (e.g., [Switchboard](https://github.com/George55562/Switchboard)) have documented this issue and implemented dual-format support: \"Looks ahead to detect Content-Length headers, Falls back to line-delimited parsing if no header found, Skips non-JSON lines.\"\n- This affects any Python SDK-based MCP server when used with clients that send Content-Length headers (Qoder, and potentially others built on the TypeScript SDK).\n","author":{"url":"https://github.com/weishigao","@type":"Person","name":"weishigao"},"datePublished":"2026-05-06T11:11:34.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/2546/python-sdk/issues/2546"}