0004. Serve stdio, streamable HTTP and SSE from one command line¶
Status: Accepted; supersedes 0002
Date: 2026-09-19
Deciders: maintainer
Context¶
ADR 0002 kept the server on stdio: a client spawns the process, nothing
listens. That still fits a developer’s laptop. It does not fit a shared
deployment, a gateway that fans one server out to many agents, or an
auditor such as scout that speaks HTTP. The MCP specification now has two
current revisions on the HTTP binding, 2025-11-25 (an initialize
handshake and a session header) and 2026-07-28 (stateless, per-request
_meta, server/discover), and clients on either must be served. The
older HTTP+SSE transport (2024-11-05) is still what some hosts expect.
Options considered¶
Stay on stdio and leave remote use to a wrapper process.
Add HTTP behind a bespoke module per server, each with its own flags.
One shared module, copied verbatim into every server of the suite, that maps the same three flags onto the SDK’s transports.
Decision¶
Option 3. <server> runs stdio; <server> --transport streamable-http
listens on --host/--port at /mcp and speaks both current protocol
revisions on that one endpoint, streaming responses as server-sent
events and offering the server-to-client stream on GET; <server> --transport sse serves the older HTTP+SSE transport at /sse and
/messages/. The module binds loopback unless told otherwise and adds
no authentication of its own: a routable deployment sits behind a
gateway the operator trusts. Servers that already carry authenticated
HTTP keep it as additional flags on the same command line.
Consequences¶
main() delegates to _cli.serve, which with _transports.run is the
same pair of files in every server, so the suite is started, documented and tested the same
way. Each server is verified over streamable HTTP with scout in both
protocol eras and over SSE with the SDK client before release; the
conformance workflow lists tools over every transport. The stdio
end-to-end test stays as it was.