Enable JSON responses on Streamable HTTP for Codex CLI compatibility

[jpr5]

Summary

A community user reported that Pathfinder's MCP server doesn't work with OpenAI Codex CLI — initialization fails with connection drops. Confirmed working with Claude Code.

Root cause: Codex CLI uses the rmcp Rust MCP SDK, which has open bugs (#5619, #11284) around parsing SSE-formatted responses from Streamable HTTP endpoints. Pathfinder was returning Content-Type: text/event-stream for all responses (including simple request/response like initialize and tools/list), which rmcp fails to parse — it closes the connection before reading the response data.

Fix: The MCP SDK's StreamableHTTPServerTransport has an enableJsonResponse option (default: false). When enabled, the server responds with Content-Type: application/json instead of SSE-wrapping for single-message exchanges. This is one line:

const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => preSid,
    enableJsonResponse: true,  // ← new
    ...
});

Spec compliance: Fully compliant. The MCP spec (2025-06-18) explicitly states: "If the input is a JSON-RPC request, the server MUST either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases." The server gets to choose.

Tradeoff: Loses the ability to send server-initiated notifications mid-request via SSE. Pathfinder's tools are all request/response — none stream intermediate results. The GET SSE endpoint still works for server-initiated messages.

No impact on Claude Code or any other spec-compliant client, since they're required to handle both formats.

Changes

• src/server.ts: Add enableJsonResponse: true to StreamableHTTPServerTransport constructor
• docs/clients/index.html: Add Known Concerns section documenting SSE parsing bugs in some MCP clients, our mitigation, and the mcp-remote stdio bridge workaround for any remaining edge cases
• Version bump to 1.13.1 (package.json, src/cli.ts, package-lock.json, CHANGELOG.md)

Test plan

• Started Pathfinder locally with breeze-docs fixture
• Verified /mcp POST returns Content-Type: application/json (previously returned text/event-stream)
• Verified response body is plain JSON-RPC ({"result":{"protocolVersion":"2025-06-18",...},"jsonrpc":"2.0","id":1}) — not SSE-wrapped (event: message\ndata: {...}\n\n)
• Ran codex exec against local Pathfinder — successfully initialized and discovered MCP tools (search_breeze_docs, submit_breeze_feedback)
• Claude Code connectivity unaffected (spec-compliant clients handle both formats)