Skip to content

fix(mcp): serve server/discover statelessly so 2026-07-28 is advertised (#170) - #171

Merged
shockalotti merged 1 commit into
mainfrom
fix/mcp-stateless-discovery
Oct 26, 2026
Merged

shockalotti merged 1 commit into
mainfrom
fix/mcp-stateless-discovery

Conversation

@shockalotti

Copy link
Copy Markdown
Contributor

Closes #170.

Root cause

Not ChatGPT being wrong, and not an SDK gap. go-sdk v1.8.0 knows protocol 2026-07-28 (SEP-2575 server/discover). But StreamableServerTransport.SupportsProtocolVersion gates it:

if version >= protocolVersion20260728 {
    return t.Stateless && slices.Contains(supportedProtocolVersions, version)
}

Calnode passed nil options to NewStreamableHTTPHandler, which means stateful, so filterSupportedVersions stripped 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-28 and 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 /mcp transport, extracted into newMCPStreamableHandler with the reasoning documented at the call site.

Calnode is a clean fit for stateless:

  • every request is authenticated on its own (RequireBearerToken → MCPCallerMiddleware binds the caller before the MCP handler),
  • no tool sends server→client requests or notifications,
  • nothing reads session state.

One behaviour change to be aware of: GET and DELETE /mcp now 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=1 as an escape hatch, but nothing here needs it.

Verification

Your diagnostic curl, against a fresh local build:

"supportedVersions": ["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]

2026-07-28 is now first and every older version is still offered, so downgrade negotiation is intact.

Tests added in internal/server/mcp_discovery_test.go:

  1. TestMCPDiscoverAdvertisesProtocol20260728 — the discover response includes 2026-07-28 and all four older versions. Fails on the stateful wiring.
  2. TestMCPStatelessRejectsNotificationStream — GET /mcp is 405.
  3. TestMCPStatelessServesNormalClientSession — a real StreamableClientTransport client 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

…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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No critical issues — minor suggestions inline.

Reviewed changes

This run reviewed the full two-file diff at d837b09.

  • Stateless MCP transport — /mcp now uses StreamableHTTPOptions{Stateless: true}, which lets go-sdk v1.8.0 advertise and serve protocol 2026-07-28 via server/discover; GET/DELETE now return 405.
  • Discovery and session tests — new tests assert 2026-07-28 plus all four legacy versions are advertised, GET /mcp is 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.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using deepseek-v4.1-flash | 𝕏

Comment thread internal/server/server.go
// 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@shockalotti
shockalotti merged commit e0a942f into main Oct 26, 2026
10 checks passed
@shockalotti
shockalotti deleted the fix/mcp-stateless-discovery branch October 26, 2026 04:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ChatGPT OAuth succeeds, but MCP discovery fails after server/discover using protocol 2026-07-28

1 participant