QMD on WSL : After first (successful) connection to MCP the next connections from Claude Code fail.

[kenaroik]

Hi all!

I run QMD in Windows WSL2. Indexing worked. I start the MCP as daemon with qmd mcp --http --port 1234 --daemon

After that, the first connection to MCP from Windows-level Claude Code works. But starting with the second connection request it fails. In the same Claude Code session I can use /mcp to "disconnect" and then try "reconnect". But even this fails.

Any ideas?

[kleddbot]

We hit the same issue from macOS (Docker container → host QMD daemon over HTTP MCP, v1.0.7). The sessionIdGenerator fix that shipped in v1.0.7 resolved the "stateless transport cannot be reused" crash from #163, but the HTTP daemon is still effectively single-session: one WebStandardStreamableHTTPServerTransport instance is created at startup and connected once via mcpServer.connect(transport). When a client disconnects or restarts, no new client can successfully initialize — the transport rejects it with "Server already initialized."

This makes the daemon unsuitable for reconnect, crash recovery, or multi-client scenarios without a full daemon restart.

Full analysis: root cause, error surface, and workaround

Root cause

In src/mcp.ts, startMcpHttpServer() creates a single transport and connects it once:

const transport = new WebStandardStreamableHTTPServerTransport({
  sessionIdGenerator: () => randomUUID(),
  enableJsonResponse: true,
});
await mcpServer.connect(transport);

Once a client initializes, the transport's internal _initialized flag is set to true. Any subsequent initialize request from a new client is rejected. There's no way to reset it without restarting the daemon.

MCP session error strings

We mapped 4 distinct error strings from the MCP SDK that surface in different scenarios:

Error	When it occurs
"Server already initialized"	New client sends initialize but transport already has an active session
"Server not initialized"	Request arrives but transport has no active session for that ID
"Session not found"	Request includes a session ID the transport doesn't recognize
"Invalid session"	Older/alternative wording for session ID mismatch

Two failure modes

Mode 1 — Daemon restarts, client keeps running:
Client's next call fails with a session error. Creating a fresh Client + StreamableHTTPClientTransport and calling connect() succeeds because the new daemon has no active session. First retry recovers transparently.

Mode 2 — Client restarts, daemon keeps running:
New client sends initialize → rejected ("Server already initialized"). Retry with a fresh transport also fails — the daemon's singleton transport is locked. Session is permanently stale until daemon restarts.

Client-side workaround: recovery poller

We built a background poller that handles Mode 2. When a session error persists after one retry, the client marks itself dead and starts polling every 10 seconds:

private startRecovery(): void {
  if (this.recoveryInterval) return;
  this.recoveryInterval = setInterval(async () => {
    const transport = new StreamableHTTPClientTransport(
      new URL(`${this.baseUrl}/mcp`)
    );
    const testClient = new Client({ name: "recovery", version: "1.0.0" });
    try {
      await testClient.connect(transport);
      // Daemon was restarted — fresh session available
      this.client = testClient;
      this.dead = false;
      this.stopRecovery();
      console.log("auto-recovered — daemon has fresh session");
    } catch {
      await testClient.close().catch(() => {});
      await transport.close().catch(() => {});
    }
  }, 10_000);
}

Both modes verified end-to-end with production logs:

# Mode 1: transparent retry
qmd: status session error after 24ms — auto-retrying with fresh connection
qmd: connected to MCP daemon
qmd: status completed in 23ms

# Mode 2: poller recovery after daemon restart
qmd: status session error after 16ms — auto-retrying with fresh connection
qmd: status session error persists after retry (4ms) — starting background recovery
# ... daemon restarted ...
qmd: auto-recovered — daemon has fresh session
qmd: status completed in 32ms

Suggested fix direction

Create a new transport per session instead of one at startup. The MCP SDK's Streamable HTTP examples use a Map<sessionId, transport> pattern:

const sessions = new Map<string, WebStandardStreamableHTTPServerTransport>();

// On each POST /mcp:
const sessionId = req.headers.get("mcp-session-id");
if (isInitialize) {
  const transport = new WebStandardStreamableHTTPServerTransport({ ... });
  await mcpServer.connect(transport);
  sessions.set(transport.sessionId, transport);
} else {
  const transport = sessions.get(sessionId);
  // route to existing session
}

This would allow multiple clients, support reconnect after crashes, and align with the MCP Streamable HTTP spec.

Related: #163 (original stateless crash, fixed by sessionIdGenerator), #166 (community PR for #163, unmerged), #140 (transport crash on query/vsearch — possibly same transport fragility).