Skip to content

fix(mcp): treat 404 as 405 for streamable-http SSE GET #1080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nh2 wants to merge 1 commit into
base: main
Choose a base branch
from
+30 −0
Open

fix(mcp): treat 404 as 405 for streamable-http SSE GET #1080

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions src/services/mcp/McpHub.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,35 @@ const McpSettingsSchema = z.object({
mcpServers: z.record(ServerConfigSchema),
})

/**
* `fetch` wrapper for Streamable HTTP MCP transports that reports a `404` answer to a
* `GET` request as `405 Method Not Allowed`.
*
* The MCP SDK opens the optional server-to-client SSE stream with a `GET` request. Per the
* MCP spec a server that does not offer such a stream must answer `405`, which the SDK
* treats as "no SSE stream available" and silently ignores. Servers answering `404`
* instead make the SDK fail the whole connection with
* `Failed to open SSE stream: Not Found`, even though POST-based requests work fine, so
* the status is normalized here.
*
* Any other request method or status code is passed through untouched.
*
* See: https://github.com/modelcontextprotocol/typescript-sdk/issues/1150
*/
const streamableHttpFetch: typeof fetch = async (url, init) => {
const response = await fetch(url, init)

if (init?.method?.toUpperCase() === "GET" && response.status === 404) {
return new Response(response.body, {
status: 405,
statusText: "Method Not Allowed",
headers: response.headers,
})
}

return response
}

Comment on lines +155 to +183

@coderabbitai coderabbitai Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

sdk='https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.29.0/src/client/streamableHttp.ts'
spec='https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/docs/specification/2025-11-25/basic/transports.mdx'

curl -fsSL "$sdk" | sed -n '167,223p;602,613p'
curl -fsSL "$spec" | sed -n '119,194p'

Repository: Zoo-Code-Org/Zoo-Code

Length of output: 6673

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

echo "---- git files around McpHub ----"
git ls-files | rg '(^|/)McpHub\.ts$|package.json|pnpm-lock.yaml|package-lock.json|yarn.lock' || true

echo "---- McpHub relevant lines ----"
file="$(git ls-files | rg '(^|/)McpHub\.ts$' | head -n1)"
if [ -n "${file:-}" ]; then
  wc -l "$file"
  sed -n '130,195p;820,875p' "$file"
fi

echo "---- MCP SDK version references ----"
rg -n "typescipt-sdk|`@modelcontextprotocol/sdk`|modelcontextprotocol/typescript-sdk|StreamableHTTPClientTransport|streamableHttpFetch|SSE|Session-Id|mcp-session-id|Last-Event-ID|404|405" package.json pnpm-lock.yaml package-lock.json yarn.lock "$file" 2>/dev/null || true

echo "---- fetch wrapper usage text ----"
rg -n "streamableHttpFetch|fetchFn|StreamableHTTPClientTransport" "$file" . --glob '!node_modules' --glob '!dist' --glob '!build' || true

Repository: Zoo-Code-Org/Zoo-Code

Length of output: 11695

🌐 Web query:

MCP Streamable HTTP transport GET 404 MCP-Session-Id expired session 405

💡 Result:

The HTTP status codes 404 and 405 within the Model Context Protocol (MCP) Streamable HTTP transport have specific, distinct roles defined by the protocol specification [1][2]. HTTP 404 (Not Found) and Session Expiration When a server receives a request containing an MCP-Session-Id that it no longer recognizes—often because the session has expired or been terminated—it must return an HTTP 404 status code [3][1]. Upon receiving this 404, a compliant client is required to: 1. Clear the stale session ID [4][5]. 2. Initiate a new session by sending a fresh initialize request without any session ID attached [3][1]. Some client SDK implementations have historically struggled to handle this correctly, failing to clear the session ID before retrying, which leads to persistent 404 errors [4][5]. HTTP 405 (Method Not Allowed) The HTTP 405 status code is used to indicate that the requested HTTP method (such as GET or DELETE) is not supported at the targeted MCP endpoint [3][1]. - GET Requests: If a server does not offer a Server-Sent Events (SSE) stream at the MCP endpoint, it must return 405 for GET requests [3][1]. This is particularly common in stateless server configurations where no session exists to support server-initiated messages [6][7][8]. - DELETE Requests: If a server does not permit clients to explicitly terminate sessions, it may return 405 in response to a DELETE request [3][1]. In summary, 404 indicates a session-level state mismatch (the session is gone), while 405 indicates a transport-level capability mismatch (the method is not allowed) [3][1].

Citations:

🌐 Web query:

MCP 2025-11-25 transports Section session management 404 MCP-Session-Id

💡 Result:

Under the Model Context Protocol (MCP) specification dated 2025-11-25, session management for the Streamable HTTP transport was handled via the Mcp-Session-Id header [1][2][3]. The specification explicitly defined how servers and clients must handle session IDs, including the use of HTTP 404 Not Found to signal that a session is no longer valid [1][2][3]. Specifically, per the 2025-11-25 specification: - If a server terminates a session, it must respond to any subsequent requests using that session ID with HTTP 404 Not Found [1][3]. - Upon receiving an HTTP 404 response for a request containing an Mcp-Session-Id, a client is required to start a new session by sending a new InitializeRequest without a session ID [1][3][4]. - This behavior was intended to differentiate between invalid/expired sessions (404) and missing session IDs in requests that require them (which should trigger an HTTP 400 Bad Request) [5][6]. Important Context: As of July 2026, the Model Context Protocol has evolved away from this stateful, session-based architecture [7]. In the latest specification updates (post-2025-11-25), the protocol-level concept of sessions and the Mcp-Session-Id header have been removed (SEP-2567) to enable a completely stateless protocol [8][7]. Servers that need to maintain state across calls now use explicit handles passed as arguments within tool calls, rather than relying on transport-layer sessions [7].

Citations:

🌐 Web query:

MCP spec 2025-11-25 transports 404 GET Last-Event-ID resumed stream

💡 Result:

In the Model Context Protocol (MCP) specification version 2025-11-25, resumable SSE streams using the Last-Event-ID header were a supported feature of the Streamable HTTP transport [1][2]. The specification defined that if a client was disconnected, it should issue an HTTP GET request to the MCP endpoint, including the Last-Event-ID header [1][2]. The server was then permitted to use this ID to replay messages from the specific stream that was disconnected and resume the stream from that point [1][2]. Additionally, the server could proactively close connections (without terminating the stream) to save resources, relying on the client to reconnect using this mechanism [1][2]. However, it is important to note that this mechanism is no longer part of the current protocol as of later revisions (such as 2026-07-28) [3]. In these newer versions, resumable SSE streams via Last-Event-ID are explicitly not supported, and servers are instructed to ignore the Last-Event-ID header [3]. Regarding the HTTP 404 response mentioned in your query: in the 2025-11-25 specification, servers could terminate sessions at any time, after which they were required to respond to requests using that session ID with an HTTP 404 Not Found error [4][5]. When a client received this 404, it was required to initiate a new session by sending a new InitializeRequest [4][5]. In current versions of the specification, if a server does not implement a requested method, it must respond with 404 Not Found along with a specific JSON-RPC error code (-32601) to distinguish it from legacy 404 responses [3].

Citations:

Do not rewrite session-bound GET/404 responses as 405.

This wrapper normalizes every Streamable HTTP GET/404 before checking session context. A GET with MCP-Session-Id that returns 404 indicates an expired or terminated session, so the client must start a new session rather than treat it as “no SSE stream.” If the GET includes resumption context, 404 can also mean resumption failed. Scope the normalization to the initial optional SSE probe, or add session/resumption-aware recovery before rewriting the status.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/services/mcp/McpHub.ts` around lines 155 - 183, Restrict
streamableHttpFetch’s 404-to-405 conversion to the initial optional SSE probe
only. Preserve 404 responses for GET requests carrying MCP-Session-Id or
resumption context so the client can perform session expiration or resumption
recovery instead of treating them as unsupported SSE.

export class McpHub {
private providerRef: WeakRef<ClineProvider>
private disposables: vscode.Disposable[] = []
Expand Down Expand Up @@ -824,6 +853,7 @@ export class McpHub {
transport = new StreamableHTTPClientTransport(new URL(configInjected.url), {
authProvider,
requestInit: { headers: configInjected.headers },
fetch: streamableHttpFetch,
})

// Set up Streamable HTTP specific error handling
Expand Down
Loading