MCP Connection Errors Explained: 404 on SSE, 406, and Sessions
A breakdown of common Model Context Protocol (MCP) Streamable HTTP connection errors including 404 on /sse, 406 Not Acceptable, and 400s session issues from Tanod's guide.
Stock photo for illustration only, not from the actual event
- Most MCP connection errors stem from incorrect URLs or missing headers.
- Streamable HTTP uses a single URL, replacing the older HTTP+SSE design.
- POST requests must explicitly include Accept and Content-Type JSON headers.
- Stateful servers require the Mcp-Session-Id header after initialization.
Developing applications with the Model Context Protocol (MCP) often exposes connection hurdles on the server side. A technical guide by Tanod details the most frequent pitfalls encountered when working with the Streamable HTTP protocol, which utilizes a single URL for JSON-RPC payloads and an optional GET stream. Most failures originate from clients communicating with outdated endpoints or supplying improperly formatted header fields.
Under the legacy HTTP+SSE transport specification dated 2004-11-05, clients opened a GET request to an SSE URL to discover a secondary endpoint designated for POST operations. However, the Streamable HTTP specification introduced on 2025-03-26 consolidated both into a unified URL. Clients or connection bridges that continue appending /sse will receive an immediate 404 error from any compliant server, just as appending redundant paths like /mcp causes routing failures.
Transitioning from HTTP+SSE to Streamable HTTP simplifies the architectural footprint of MCP deployments and streamlines connection handling. Nevertheless, updating client implementations to adhere strictly to the new specification is crucial to avoiding failures during this transitional phase.
The standard remedy is utilizing the endpoint URL exactly as published. For stdio-only clients, running a remote bridge such as npx mcp-remote with the --transport http-only flag prevents fallback behaviors to SSE. Tanod's production servers exclusively implement Streamable HTTP, meaning primary endpoints like https://tanod.dev/mcp and focused routes such as https://tanod.dev/mcp/docs are operational, whereas nested suffixes like /mcp/docs/sse return 404 status codes.
Stock photo for illustration only, not from the actual event
Regarding 406 Not Acceptable responses, these typically occur when POST payloads omit the required Accept: application/json, text/event-stream header. Servers may respond with a single JSON body or an SSE stream, and standard HTTP libraries sending default wildcard accepts will often be rejected. Additionally, requests must explicitly declare Content-Type: application/json to prevent parsing errors caused by form-encoded bodies or plain text scripts.
Session-related 400 errors emerge in stateful architectures that require an initial initialize request. Successful initialization returns an Mcp-Session-Id header, which the client must append to every subsequent call. Invoking tool listings prior to initialization or dropping the tracking header triggers client error responses. When a server restarts, active sessions expire, yielding a 404 Session not found response that mandates a fresh initialization handshake.
"Most connection failures we see in our own server log are a client talking to a different address than the one it was given, or sending the wrong headers."
Tanod
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment