barrel_mcp_http_stream (barrel_mcp v3.0.1)

View Source

MCP Streamable HTTP Transport (protocol 2025-03-26 through 2026-07-28).

Implements the MCP Streamable HTTP transport for Claude Code integration on the built-in h1/h2 server (barrel_mcp_http_listener). This transport uses:

  • POST for client requests with JSON or SSE streaming responses.
  • GET for server-to-client notification streams (SSE).
  • DELETE for session termination.
  • OPTIONS for CORS preflight.

The protocol logic lives in barrel_mcp_http_engine; this module only wires the user options to the engine and starts the listener.

Summary

Functions

start(Opts)

Start the Streamable HTTP server.

stop()

Stop the Streamable HTTP server.

Functions

start(Opts)

-spec start(Opts) -> {ok, pid()} | {error, term()}
               when
                   Opts ::
                       #{port => pos_integer(),
                         ip => inet:ip_address(),
                         auth => map(),
                         session_enabled => boolean(),
                         ssl => map(),
                         allowed_origins => [binary()] | any,
                         allow_missing_origin => boolean(),
                         subscription_keepalive_ms => pos_integer(),
                         sse_path => binary(),
                         sse_message_path => binary(),
                         max_connections => pos_integer()}.

Start the Streamable HTTP server.

Security defaults

The server binds to 127.0.0.1 by default. Public binds (any non-loopback IP) require an explicit allowed_origins to prevent DNS-rebinding and CORS-style attacks. The Origin header is validated on every request; mismatches get HTTP 403.

Options

  • port: TCP port (default 9090).
  • ip: bind address (default {127,0,0,1}).
  • auth: authentication provider config.
  • session_enabled: true (default) to use Mcp-Session-Id sessions.
  • ssl: TLS options (certfile, keyfile, optional cacertfile). A TLS bind serves HTTP/1.1 and HTTP/2 on the same port via ALPN.
  • allowed_origins: [binary()] | any.
  • allow_missing_origin: accept requests with no Origin header. Defaults to true on loopback, false otherwise.

  • subscription_keepalive_ms: how often a quiet subscriptions/listen stream emits an SSE comment so intermediaries do not drop it. Defaults to 15000.

    It doubles as the upper bound on how long a subscriber that went away lingers: nothing reads the socket while a stream is held open, so a client's disconnect surfaces on the next write. Raise it and dropped subscribers are reaped later.
  • sse_path and sse_message_path: serve the deprecated 2024-11-05 HTTP+SSE transport on these two routes as well, for clients that predate Streamable HTTP. Both must be given; neither is served otherwise, because a GET on one of them and a Streamable GET are indistinguishable.

stop()

-spec stop() -> ok | {error, not_found}.

Stop the Streamable HTTP server.