Transport-neutral MCP HTTP engine.

Holds the protocol logic for both the simple HTTP transport and the Streamable HTTP transport (POST/GET/DELETE/OPTIONS, SSE, sessions, CORS, Origin validation, authentication, the OAuth protected-resource-metadata endpoint and async tool calls) WITHOUT any dependency on a concrete HTTP server.

A binding (the built-in barrel_mcp_http_listener h1/h2 server, or an external adapter such as Livery's) reads the request line and body, then calls handle/6 with:

• Method: the request method binary (<<"POST">> …).
• Path: the request target (query string allowed; it is stripped here).
• Headers: a [{binary(), binary()}] proplist. Lookups are case-insensitive.
• Body: the full request body (<<>> when none).
• Responder: a map of I/O closures (see below).
• Config: the engine configuration (see the config() type).

The Responder abstracts response delivery so the engine never touches a socket:

   #{reply        => fun((Status, Headers, Body) -> ok),
     stream_start => fun((Status, Headers) -> ok),
     stream_chunk => fun((iodata()) -> ok | {error, term()}),
     stream_end   => fun(() -> ok)}

Headers passed to the closures is a [{binary(), binary()}] proplist (lowercase names). A streaming (SSE) response is stream_start then repeated stream_chunk then stream_end.

handle/6 runs in the calling (per-request) process. For a long-lived GET SSE stream it blocks in a receive loop until the session is terminated or the binding signals a client disconnect by sending the calling process the message mcp_disconnect.

Sections, in file order

• Entry point and method dispatch: handle/6, route/7, dispatch/6 keyed on the engine mode and the verb.
• Simple transport: POST only, no sessions.
• Streamable POST: stream_post/4, the era fork in stream_post_request/6, batches, inbound responses.
• Modern requests: header and body agreement, stateless dispatch, SSE response streams, subscriptions/listen.
• Async tool calls: handle_async_tool_call/7 decides the tool-call mode for HTTP (inline, task, escalate, refuse) and waits for the worker; the legacy immediate-task path is handle_long_running_call/10.
• Session resolution: lookup_session/5, owned_session/2, version negotiation.
• GET and DELETE: the standalone stream with replay, and session termination.
• The 2024-11-05 HTTP+SSE pair.
• SSE, validation, authentication, CORS, Origin and bind helpers, the session manager bootstrap, plumbing.

Processes

handle/6 runs in the request process the listener spawned. A tool worker is spawned by the registry with this process (or a relay) as reply_to; a task collector, a relay and, on the legacy pair, a driver and a stream watcher are the other processes this module starts. The Server Internals guide lists them with who links or monitors whom.