Skip to content

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

@KlementMultiverse

Description

@KlementMultiverse

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


Contributed by Klement Gunndu

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions