modelcontextprotocol / modelcontextprotocol/typescript-sdk

StreamableHTTPClientTransport should handle 404 and 406 gracefully for GET SSE stream

Open Beginner friendly
#1,635 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug fix proposed P2 ready for work
Dominant language
TypeScript
Stars
13.4k
Forks
2.2k
Avg merge
3d 15h
Merged PRs (30d)
4

Description

Problem

The StreamableHTTPClientTransport._startOrAuthSse() method sends a GET request to open an SSE stream during initialization. Per the MCP spec, the server MAY respond with 405 Method Not Allowed if it doesn't support SSE streams, and the client correctly handles this.

However, many MCP servers return 404 Not Found or 406 Not Acceptable instead of 405 for this GET request:

  • 404: Server doesn't have a GET handler for the MCP endpoint (only POST)
  • 406: Server rejects Accept: text/event-stream header (e.g., requires both application/json and text/event-stream)

Both cases mean the same thing: the server does not offer an SSE stream at the GET endpoint. But the client treats them as fatal errors, preventing the connection even though POST-based communication would work fine.

Current Behavior

// packages/client/src/client/streamableHttp.ts, _startOrAuthSse()
if (response.status === 405) {
    return;  // Only 405 is handled gracefully
}
throw new SdkError(...);  // 404 and 406 throw, killing the connection

This causes errors like:

StreamableHTTPError: Streamable HTTP error: Failed to open SSE stream: Not Found

Affected Clients

This impacts any client consuming the SDK, including:

  • Gemini CLI (google-gemini/gemini-cli) — #5268, #2787
  • MCP Inspector#1150
  • LibreChat and other MCP consumers

Proposed Fix

Treat 404 and 406 the same as 405 — all indicate the server does not offer an SSE stream at the GET endpoint:

// 404: Server has no GET handler (only POST)
// 405: Server explicitly doesn't allow GET
// 406: Server rejects the Accept header for GET
if (response.status === 404 || response.status === 405 || response.status === 406) {
    return;
}

The client will then proceed with POST-based communication, which works correctly for these servers.

Reproduction

  1. Set up an MCP server that only supports POST (no GET SSE stream)
  2. Connect using StreamableHTTPClientTransport
  3. The GET request returns 404 → client throws and disconnects
  4. POST would have worked fine

Environment

  • @modelcontextprotocol/sdk: latest
  • Discovered while debugging Gemini CLI v0.32.1 connecting to a remote HTTP MCP server (ArmorCode)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in packages/client/src/client/streamableHttp.ts, specifically StreamableHTTPClientTransport._startOrAuthSse(), and trace how the GET response status is handled during initialization. Verify the behavior with a POST-only MCP server or a focused client test if available. Done means 404 and 406, like 405, allow POST-based communication to continue without a fatal error.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, networking
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.