Repository navigation
mcpx client: the deprecated HTTP+SSE transport, for remote servers that still speak it #1944
Description
Relocated from dezren39/darwin-nix#220 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).
Parent: #181
Summary
mcpx speaks stdio and Streamable HTTP. The 2024-11-05 HTTP+SSE transport (two endpoints, a persistent event stream) is neither served nor spoken, transport: sse in config is ignored, and there is no fallback from Streamable HTTP to it, which the backward-compatibility guidance in every later revision describes. The transport is deprecated and on a short removal clock (2026-07-28/deprecated.mdx:31), so this is worth doing only if a server someone uses still needs it; opencode v1 has the fallback.
Found while writing the comparison register (pkgs/mcpx/docs/compare/) and checked against the code at 05c78b2. Each row below links its register entry, which carries the value, effort, risk, the specification text and every source.
Register rows
| row | difference | mcpx @ 05c78b2 | effort |
|---|---|---|---|
| TR-10 | HTTP+SSE transport (2024-11-05) | ✗ — neither served nor spoken; transport: sse ignored |
M |
| TR-11 | Client fallback from Streamable HTTP to HTTP+SSE | ✗ — no fallback | M |
What to do
Decide first: implement the fallback, or reject transport: sse with a message naming the alternative (the declared-but-inert setting is the #177 bug either way).
Ease · Impact · Related
Ease M · Impact low · Related: #177
Acceptance criteria
- The decision is recorded on this issue first: implement HTTP+SSE support, or explicitly reject it — and if rejected,
transport: ssein config fails loudly (error or warning) instead of being silently ignored. - If implemented: the mcpx client falls back from Streamable HTTP to the 2024-11-05 HTTP+SSE transport (register TR-11), and mcpx speaks/serves that transport where the register requires it (TR-10).
- A regression test exercises the fallback against an SSE-only test server.
- Docs (
pkgs/mcpx/docs/) describe the supported transports and the config behavior.
Activity
developing-today commentedon Oct 28, 2026
CODE-869
dezren39 commentedon Oct 28, 2026
History carried over from dezren39/darwin-nix#220 (verbatim, oldest first):
@dezren39 · 2026-10-28T04:30:00Z
🤖 Intake review — fleet monitor, 2026-10-27 run
pkgs/mcpx/docs/compare/register/transports.md.05c78b2(2026-09-30). Re-verify each row against currentmainbefore fixing — a row may have moved since.7 remaining items
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Agent: queue worker (repo-worker-code), OpenChamber scheduled lane 02cafe76
Found via: queue claim (task 7790, triage)
Verdict: mostly done; re-scoped to one live docs item. Follow-up enqueued as task 8141.
Evidence (fresh, at
origin/main314fbbe, 2026-11-03):connectSSE(internal/pool/pool.go:904),LegacySSETransport, era fast path (pool.go:659-664), era write (pool.go:718-726,TransportHTTPSSEininternal/pool/eras.go:30).LegacyHTTPRefusedErrorrefusal path (pool.go:674-687), regression testTestHTTPSSEFallback(internal/pool/sse_test.go:118) against SSE-only doubleoldSSEServer(sse_test.go:20-30).docs/compare/register/transports.md:32-33still claim TR-10 "neither served nor spoken;transport: sseignored (feat(id): add terminal buffer capture interface #220)" and TR-11 "no fallback (feat(id): add terminal buffer capture interface #220)"; detail:259still cites pre-migration05c78b2lines./sse+/messagesserver routes ininternal/daemon,internal/api,internal/mcpserver;transport: sseis documented as an http-equivalent alias (docs/modes.md:80-87,internal/api/ops_settings.go:129).Decisions recorded here (see the 2026-10-29 re-scope):
small_fixtask 8141).dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — already implemented (task 8141)
already_done. The decision this issue asked for was overtaken by events: the fleet implemented the fallback, so the "if implemented" acceptance branch applies and is satisfied on current main.pkgs/mcpx/internal/mcpclient/sse.go—LegacySSETransportspeaks the 2024-11-05 HTTP+SSE transport (GET opens the stream, firstendpointevent names the POST URL; header comment cites both spec revisions and the backwards-compatibility procedure). TR-10's client half: done.LegacyHTTPRefusedErroron a 400/404/405 without a modern body; the pool then uses the legacy client and forces the legacy era — documented inpkgs/mcpx/docs/modes.md("Transport options") and in the/v1ops description (internal/api/ops_settings.go:129: "Streamable HTTP first, falling back to the legacy 2024-11-05 HTTP+SSE transport when an endpoint refuses it").TestHTTPSSETransport,TestALegacyServerIsReachedOnTheFirstTry,TestALegacyServerIsStillReachedWhenModernIsPreferred,TestLegacyHTTPStreamResumption, plus the legacy lifecycle/version-header suites —go test ./internal/mcpclient/ -run Legacy…green.transport: "sse"is no longer silently inert: its documented meaning (modes.md, ops_settings enumstdio|http|sse) is "names a URL server like http — the protocol era is negotiated per endpoint", which now matches the pool's actual behaviour.internal/conformance/requirements.jsonrecords "not-implemented-by-choice — mcpx does not serve HTTP+SSE", anddocs/in-name-only.mdtracks the residual docs wording.