MCP "Session not found" (HTTP 404): How to Fix It (Claude Code, VS Code, Python and TypeScript Servers)

"Session not found" means the server no longer knows the Mcp-Session-Id your client sent. The session expired, the server restarted, or a load balancer sent you to a different instance. The fastest fix on the client side is to reconnect, which starts a new session. On the server side, either route each session to the same instance or run the server stateless. The 2026-07-28 MCP spec removed sessions entirely, so this error only appears on connections that use the 2025-era Streamable HTTP behavior.

Checked against: the Python SDK troubleshooting page, the 2025-11-25 transports page and the 2026-07-28 Streamable HTTP page on 2 November 2026 (Python SDK mcp 2.3.0). eSEOspace did not run these steps.

What this error means

The 2025-11-25 transports page let a Streamable HTTP server assign a session ID in an MCP-Session-Id header at initialization. The client then sends that header on every request. It also says: "The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found." When a client gets that 404, "it MUST start a new session by sending a new InitializeRequest without a session ID attached."

So the error is the spec working as designed. The real question is why the session disappeared.

The Python SDK troubleshooting page lists the causes: the server restarted, you were routed to a different instance, or the session expired because nothing was in flight for session_idle_timeout (30 minutes by default). It adds: "Sessions live in that one process's memory." The SDK source also rejects a session if the request uses a different credential than the one that created it, and it responds "exactly as if the session did not exist."

The 2026-07-28 changelog removed protocol-level sessions and the Mcp-Session-Id header. A modern-only server that receives the header should ignore it, according to the Streamable HTTP page. Read our stateless protocol explainer for why.

Quick fix

1. Reconnect the client. In Claude Code, open /mcp and reconnect the server. In your own code, close the client and open a new one.
2. Check for a recent deploy or restart. A burst of these errors right after a deploy is normal, per the Python SDK docs.
3. Count your server instances. If you run more than one worker or container, either enable sticky sessions on the load balancer or switch to stateless mode.
4. Check the idle timeout. If clients go quiet for long periods, raise session_idle_timeout or let clients reconnect.
5. Plan the move to 2026-07-28. Modern clients and servers have no sessions to lose.

Fix by client / OS

Claude Code

Claude Code's MCP docs say it reconnects a remote server that drops mid-session. You can also reconnect manually from /mcp. Claude Code's v2 client runtime asks HTTP servers whether they support revision 2026-07-28 and uses it with those that do, which avoids sessions with modern servers. If you pinned the older runtime with MCP_SDK_GENERATION=v1 or MCP_PROTOCOL_NEGOTIATION=legacy, every server uses the older handshake.

VS Code

Run MCP: List Servers, pick the server and restart it, as described in VS Code's manage and troubleshoot page. Use Show Output to see whether a 404 came back.

Python server (official SDK)

You have two documented fixes for multi-worker setups: sticky routing, or stateless_http=True. Stateless mode creates a fresh transport per request with no session tracking. If you need sessions for older clients, keep one process per session or route by session ID. The matching server log line is Rejected request with unknown or expired session ID: <id>, logged at INFO, so raise your log level to see it.

TypeScript server (official SDK v2)

The v2 createMcpHandler serves 2025-era clients statelessly by default, according to the SDK's legacy clients page. Under that default a legacy GET or DELETE answers 405. To keep an existing sessionful deployment, the page shows routing with isLegacyRequest in front of a strict handler.

Your own client code

Catch the error and reconnect instead of retrying inside the dead session. The Python SDK docs put it plainly: leave the async with Client(...) block and enter a new one.

Where to find the logs

• Claude Code: /mcp shows status; run claude --debug-file /tmp/claude-debug.log for detail.
• VS Code: MCP: List Servers > Show Output.
• Python server: INFO-level Rejected request with unknown or expired session ID, preceded by Session <id> idle timeout when it expired.
• Load balancer: compare which backend served the opening request and which served the failing one.

If it still fails

• 404 on every second request. Your proxy may strip the Mcp-Session-Id header, or a browser client cannot read it. Browsers need Access-Control-Expose-Headers: Mcp-Session-Id; see MCP CORS errors.
• 404 after token refresh. The Python SDK binds a session to the credential that created it. A new identity needs a new session.
• Serverless hosting. Each invocation may be a new process, so in-memory sessions cannot survive. Run stateless.
• Unsure which error code you got. Paste it into our MCP error code lookup. Our Streamable HTTP reference shows how the transport changed.

Next step

If your remote MCP server runs on several instances and still uses 2025-era sessions, eSEOspace's MCP readiness audit checks transport, spec version and scaling setup. Related: protocol version mismatch errors.

Frequently asked questions