Support stateless mode for clients that don't preserve session IDs

[iknox]

Problem

Some MCP clients (e.g., OpenCode with type: "remote") do not preserve the mcp-session-id header across requests. The client correctly sends initialize, receives a session ID, but subsequent tools/list and tool call requests omit the header.

The current server rejects these with:

400 Bad Request: No valid session ID provided

Root Cause

@modelcontextprotocol/sdk v1.x requires sessionIdGenerator to be a function. Setting it to undefined throws a type error — stateless mode isn't available in v1.

Solution

The v2 SDK (@modelcontextprotocol/server@2.0.0-beta.4 + @modelcontextprotocol/node@2.0.0-beta.4) supports native stateless mode:

// v2: stateless — sessionIdGenerator: undefined disables session validation
const transport = new NodeStreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
});

This would accept any POST without an mcp-session-id header, solving the issue cleanly.

Migration Scope

The v2 SDK replaces the monolithic @modelcontextprotocol/sdk with three packages:

• @modelcontextprotocol/server — McpServer, types
• @modelcontextprotocol/node — NodeStreamableHTTPServerTransport
• @modelcontextprotocol/express — createMcpExpressApp

This touches ~16 files across src/ and __tests__/. The import paths change:

• @modelcontextprotocol/sdk/server/mcp.js → @modelcontextprotocol/server
• @modelcontextprotocol/sdk/server/streamableHttp.js → @modelcontextprotocol/node
• @modelcontextprotocol/sdk/server/stdio.js → @modelcontextprotocol/node
• @modelcontextprotocol/sdk/types.js → @modelcontextprotocol/server

Also requires zod as a peer dependency.

References

• v2 migration guide
• Stateless Express example
• v2.0.0-beta.4 release

[iknox]

That's a lot of LLM speak-- Obviously the sdk v 2.0 is still beta, but I wanted to get it on a radar as a future thing.

[ihor-sokoliuk]

Nice catch — the compatibility problem is valid: the current HTTP handler is stateful, so a client that drops mcp-session-id receives the reported 400 on its next request.

The proposed SDK v2 beta migration is not necessary for this fix, though. This repository already pins @modelcontextprotocol/sdk 1.29.0, and that v1 release supports stateless StreamableHTTPServerTransport with sessionIdGenerator: undefined. I also verified it with this project’s actual server factory: an initialize POST and a later tools/list POST both succeed independently without a session ID.

I’ve updated the action item to add an opt-in stateless HTTP mode while preserving stateful mode as the default. The intended implementation creates and cleans up a fresh server/transport per POST, retains the existing authorization, rate-limit, origin/host, and DNS-rebinding checks, and returns 405 for GET/DELETE because resumability and server-initiated SSE are unavailable in stateless mode.

I do not plan to move the production server to v2 solely for this change while v2 is still pre-release and v1 remains the production-recommended line. I’ll keep this issue open for the narrower v1-compatible implementation.

[ihor-sokoliuk]

Stateless HTTP support is now available in v1.14.0.

To try it:

1. Upgrade the MCP server:

   • npm/NPX: pin the client command arguments to ["-y", "mcp-searxng@1.14.0"].
   • Docker: docker pull isokoliuk/mcp-searxng:1.14.0 and use that image tag.

2. Keep your existing SEARXNG_URL and HTTP security settings, and add:

   MCP_HTTP_PORT=3000
   MCP_HTTP_STATELESS=true
   

3. Restart the MCP server and keep the remote client pointed at http://<host>:3000/mcp (or your existing HTTPS/reverse-proxy URL).

No SDK 2.0 upgrade is needed. In this mode, every POST /mcp is handled independently, incoming stale session IDs are ignored, and no response session ID is emitted. Stateful sessions remain the default when MCP_HTTP_STATELESS is not exactly true. Stateless mode is POST-only and does not provide cross-request subscriptions or resumability.

For an initial test, leave the new capacity and timeout settings at their defaults. Could you please try the original OpenCode type: "remote" flow—initialize, tools/list, then a tool call—and report whether it now works? If it does not, the OpenCode version, sanitized MCP configuration, returned HTTP status/body, and any server warning would be especially useful.

The complete behavior and optional limits are documented under HTTP Transport.