streamable_http_client hangs indefinitely when server sends POST-only endpoints without SSE fallback #2232

Problem

When an MCP server implements only POST-based endpoints (no SSE support), the streamable_http_client in mcp/client/sse.py hangs indefinitely during connection setup. The client assumes SSE is available and blocks waiting for server-sent events that never arrive.

Root Cause

The sse_client() function attempts to establish an SSE connection via GET request. If the server only exposes POST endpoints (as seen with GitHub MCP and other stateless implementations), the GET request either:

1. Returns a 405 Method Not Allowed that goes unhandled
2. Hangs waiting for an SSE stream that the POST-only server never sends

The client lacks:

• Timeout detection for failed SSE handshake
• Fallback logic to detect POST-only servers
• Clear error messaging distinguishing "server error" from "transport mismatch"

Impact

Users cannot connect to valid MCP servers that use POST-only transport, forcing them to use alternative clients or work around the limitation. The hang is silent—no exception is raised, making debugging difficult.

Expected Behavior

One of:

1. Auto-detection: Client detects POST-only server and switches to stateless HTTP mode automatically
2. Explicit timeout: GET request to SSE endpoint times out within 5-10 seconds with a clear error: "Server does not support SSE transport. Use stateless HTTP mode instead."
3. Transport negotiation: Client includes Accept: application/json header in GET request; if server responds with 406 or 415, client falls back to POST

Reproduction Steps

1. Start an MCP server that only implements POST endpoints (e.g., github-mcp or simple-stateless-http example)
2. Connect via:

   async with sse_client("http://localhost:3000") as client:
       await client.initialize()

3. Observe: Connection hangs indefinitely; no timeout; no error message

References

• Related issues: feat: add async resources for FastMCP #157 (streamable_http_client hangs with GitHub MCP), Prevent stdio connection hang for missing server path. #401 (HTTP errors not handled properly)
• Related: mcp/client/sse.py lines 100-150 (SSE handshake logic)
• Similar pattern in TypeScript SDK: handles POST-only servers explicitly

Contributed by Klement Gunndu