Migrate MCP transport from SSE to Streamable HTTP (spec 2026-07-28) #1750

Summary

Current MCP transport implementation uses the deprecated HTTP+SSE transport (2024-11-05 era) via mcp SDK 1.x, pinned <2 because of the decorator API (@mcp_server.list_tools()/@mcp_server.call_tool()) removed in SDK 2.x. Migrate to Streamable HTTP per the latest spec (2026-07-28).

Current state

• src/codegraphcontext/api/mcp_sse.py: Server from mcp SDK 1.x, SseServerTransport("/api/v1/mcp/messages"), two endpoints (GET /api/v1/mcp/sse, POST /api/v1/mcp/messages), custom _SendTracker/_AlreadySentResponse shims to bridge SDK's raw ASGI writes with FastAPI.
• src/codegraphcontext/api/app.py: wires both routes behind require_api_key.
• src/codegraphcontext/server.py: separate hand-rolled stdio JSON-RPC loop (MCPServer._run_loop), duplicating tool-list/tool-call dispatch logic independently of the SSE path, advertising protocolVersion: 2025-03-26 manually.
• pyproject.toml: mcp>=1.0.0,<2 pin with a comment explaining the 2.x decorator API removal blocks the upgrade.

Target state

• Bump to mcp>=2,<3 (latest 2.2.0 already ships a _streamable_http_modern.py module purpose-built for spec 2026-07-28).
• Replace mcp_sse.py's SseServerTransport/shims with mcp.server.lowlevel.Server(on_list_tools=..., on_call_tool=...) and its streamable_http_app(streamable_http_path="/api/v1/mcp", host="127.0.0.1", ...), mounted once. The SDK's StreamableHTTPSessionManager auto-classifies each request by MCP-Protocol-Version header and routes legacy Streamable HTTP clients (2025-03-26 through 2025-11-25, session-based) and modern 2026-07-28 clients (per-request, no session) to the correct internal handler — no manual dual-endpoint hosting needed for anything from 2025-03-26 onward.
• Collapse the two existing routes (/api/v1/mcp/sse GET, /api/v1/mcp/messages POST) into the single mounted endpoint. Auth (require_api_key) needs rewiring onto the new mount (SDK's token_verifier/auth_server_provider params, or a wrapping FastAPI dependency/middleware).
• Add Origin header validation (spec MUST, DNS-rebinding protection) — SDK's streamable_http_app auto-enables this for localhost, needs confirming/extending for the app's actual host config.
• The oldest 2024-11-05 HTTP+SSE transport (standalone GET SSE stream + separate POST endpoint, pre-dating any session model) is NOT covered by the new SDK transport manager. Only keep the current literal /sse+/messages routes alive if a real client still needs that exact wire format; otherwise drop them.
• Unify stdio (server.py) and HTTP tool dispatch where practical — both converge on the same request shape under 2026-07-28 (no session, per-request metadata), removing today's duplicated tool-list/tool-call logic.
• Update/rewrite tests/unit/api/ for the new single-endpoint POST flow.

Non-goals

• No changes required to mcp.server.stdio-based transport semantics beyond what naturally falls out of shared dispatch cleanup (stdio isn't touched by the 2026-07-28 transport revision itself).