Repository navigation
fix(mcp): serve server/discover statelessly so 2026-07-28 is advertised (#170) - #171
Conversation
…ed (#170) ChatGPT connects via OAuth, then action discovery fails because /mcp answers server/discover with supportedVersions ending at 2025-11-25. The client asks for 2026-07-28 and does not fall back, so it stops. Cause is transport mode, not the SDK. go-sdk v1.8.0 knows 2026-07-28 (SEP-2575), but StreamableServerTransport.SupportsProtocolVersion only serves versions >= 2026-07-28 when the transport is stateless. Calnode passed nil options, i.e. stateful, so filterSupportedVersions dropped the modern version. Clients that negotiate down (MCP Inspector, MiniMax, plain SDK clients) were never affected. Calnode holds no MCP session state: every request is authenticated independently by RequireBearerToken + MCPCallerMiddleware, and no tool sends server->client requests or notifications. So stateless is a safe fit. Trade-off: GET and DELETE /mcp now return 405, as there is no session to stream or terminate. Verified live: the reporter's own diagnostic curl now returns supportedVersions [2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05]. Tests cover discovery advertising 2026-07-28 (and still listing the older versions), GET returning 405, and a full Streamable HTTP client session doing initialize + tools/list + tools/call over stateless.
There was a problem hiding this comment.
ℹ️ No critical issues — minor suggestions inline.
Reviewed changes
This run reviewed the full two-file diff at d837b09.
- Stateless MCP transport —
/mcpnow usesStreamableHTTPOptions{Stateless: true}, which lets go-sdk v1.8.0 advertise and serve protocol2026-07-28viaserver/discover;GET/DELETEnow return 405. - Discovery and session tests — new tests assert
2026-07-28plus all four legacy versions are advertised,GET /mcpis 405, and a real SDK client can list and call tools.
ℹ️ ARCHITECTURE.md §19 doesn't record the new transport mode
docs/ARCHITECTURE.md §24 asks for the matching section to be updated in the same PR as a behaviour change. §19 still describes /mcp only as mcp.NewStreamableHTTPHandler with "No SSE", so the stateless requirement (and the 405 trade-off it introduces) is invisible to anyone reading the architecture doc rather than the code.
Technical details
# Update ARCHITECTURE §19's Streamable HTTP bullet
## Affected sites
- docs/ARCHITECTURE.md:977-979 — describes the `/mcp` transport but not stateless mode or 2026-07-28
- docs/ARCHITECTURE.md:1309-1312 — §24 requires same-PR doc updates for behaviour changes
## Required outcome
- §19 records that `/mcp` is stateless (required for `2026-07-28` / `server/discover`), that `GET`/`DELETE` return 405, and why that is acceptable for Calnode.deepseek-v4.1-flash | 𝕏
| // uses it to back the HTTP server; the `calnode mcp` subcommand uses it to serve the | ||
| // MCP server over stdio. The returned drain func blocks until the background worker | ||
| // has finished its current poll cycle. | ||
| // newMCPStreamableHandler builds the Streamable HTTP transport for POST /mcp. |
There was a problem hiding this comment.
This doc comment is contiguous with the existing New/BuildHandler block above it, so go doc now attributes both of those descriptions to newMCPStreamableHandler and leaves BuildHandler undocumented. Adding a blank line before this comment restores the previous attribution; moving this helper below BuildHandler is cleaner.
| } | ||
|
|
||
| // Stateless must remain transparent to ordinary MCP clients: they connect, | ||
| // initialize (negotiating a version below 2026-07-28) and call tools over HTTP. |
There was a problem hiding this comment.
This parenthetical doesn't match what the test does now: with 2026-07-28 advertised, StreamableClientTransport completes Connect through server/discover and negotiates 2026-07-28 (confirmed by logging InitializeResult().ProtocolVersion), so initialize never runs. That means the legacy downgrade path the comment claims to cover is still untested. Either correct the comment or pass &mcp.ClientSessionOptions{ProtocolVersion: "2025-11-25"} to Connect so the initialize fallback is genuinely exercised.

Closes #170.
Root cause
Not ChatGPT being wrong, and not an SDK gap. go-sdk v1.8.0 knows protocol
2026-07-28(SEP-2575server/discover). ButStreamableServerTransport.SupportsProtocolVersiongates it:Calnode passed
niloptions toNewStreamableHTTPHandler, which means stateful, sofilterSupportedVersionsstripped the modern version from the discover response. That is exactly the list in your curl:2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.ChatGPT's connector flow asks for
2026-07-28and never retries with an older version, so discovery stops there. Clients that negotiate down — MCP Inspector, MiniMax, plain SDK clients — were never affected. That asymmetry is why this went unnoticed until a ChatGPT connector tried it.The fix
&mcp.StreamableHTTPOptions{Stateless: true}on the/mcptransport, extracted intonewMCPStreamableHandlerwith the reasoning documented at the call site.Calnode is a clean fit for stateless:
RequireBearerToken→MCPCallerMiddlewarebinds the caller before the MCP handler),One behaviour change to be aware of:
GETandDELETE /mcpnow return 405 instead of opening/terminating a session stream. Calnode never pushed notifications over that stream, and a normal client session (initialize → tools/list → tools/call) works unchanged. There is a test for that path specifically.If anyone does depend on session-resumable streams later, the SDK offers
MCPGODEBUG=allowsessionsinstateless=1as an escape hatch, but nothing here needs it.Verification
Your diagnostic curl, against a fresh local build:
2026-07-28is now first and every older version is still offered, so downgrade negotiation is intact.Tests added in
internal/server/mcp_discovery_test.go:TestMCPDiscoverAdvertisesProtocol20260728— the discover response includes2026-07-28and all four older versions. Fails on the stateful wiring.TestMCPStatelessRejectsNotificationStream—GET /mcpis 405.TestMCPStatelessServesNormalClientSession— a realStreamableClientTransportclient connects, initializes, lists tools and calls one over HTTP.go test ./...green.One honest limit: I cannot run the ChatGPT connector from here, so the final confirmation is your side — reconnect the connector and see whether discovery completes. Everything up to and including the response it consumes is verified.
🤖 Generated with Claude Code