MCP streamable HTTP transport with session-aware SSE delivery. More...

#include <http_transport.hpp>

Inheritance diagram for mcp::server::HttpTransport:

Public Member Functions
	HttpTransport (HttpTransportOptions options)
	Construct a transport with normalized HTTP options.

	~HttpTransport () override
	Destroy the transport and its underlying server state.

	HttpTransport (const HttpTransport &)=delete

HttpTransport &	operator= (const HttpTransport &)=delete

core::Result< core::Unit >	start (RequestHandler handler, NotificationHandler notification_handler={}) override
	Start the HTTP server and serve the configured MCP endpoint.

core::Result< protocol::JsonRpcResponse >	send_request (const protocol::JsonRpcRequest &request) override
	Queue a server-to-client request on the active SSE stream.

core::Result< protocol::JsonRpcResponse >	send_request_to_session (std::string_view session_id, const protocol::JsonRpcRequest &request) override
	Queue a server-to-client request for a specific HTTP session.

std::optional< protocol::ClientCapabilities >	client_capabilities () const override
	Return capabilities from the active initialized HTTP session.

std::optional< protocol::ClientCapabilities >	client_capabilities_for_session (std::string_view session_id) const override
	Return capabilities from a specific initialized HTTP session.

core::Result< core::Unit >	send_notification (const protocol::JsonRpcNotification &notification) override
	Queue an outbound notification for the active SSE stream.

core::Result< core::Unit >	send_notification_to_session (std::string_view session_id, const protocol::JsonRpcNotification &notification) override
	Queue an outbound notification for a specific HTTP session.

void	stop () noexcept override
	Stop the HTTP server and fail pending outbound requests.

void	disconnect_session_sse (std::string_view session_id)
	Request a server-initiated SSE stream disconnect for a session.

std::string_view	name () const noexcept override
	Return the diagnostic transport name "http".

void	wait_until_ready () override
	Blocks until the underlying HTTP server socket is bound.

Public Member Functions inherited from mcp::server::Transport
std::weak_ptr< void >	lifetime_token () const noexcept
	Weak lifetime token for SessionContext and ClientPeer guards.

Detailed Description

MCP streamable HTTP transport with session-aware SSE delivery.

HttpTransport accepts JSON-RPC messages over POST, exposes server-initiated notifications and requests over a GET text/event-stream, and terminates the session on DELETE. It owns the underlying HTTP server instance after start() begins.

The server transport is stateful. Every successful initialize request creates a distinct MCP session id returned in Mcp-Session-Id. Later POST, GET, and DELETE requests must present that id and the supported MCP-Protocol-Version header. Unknown or terminated sessions are rejected as stale sessions. DELETE removes the session, clears its replay and outbound queues, and fails pending server-to-client requests for that session.

Outbound queues, Last-Event-ID replay windows, client capabilities, pending server requests, and active SSE stream state are tracked per session. Session-bound ClientPeer instances created from SessionContext route through send_request_to_session() and send_notification_to_session(). The legacy send_request(), send_notification(), and client_capabilities() methods use a default session for single-session compatibility.

One live real-time SSE stream is accepted per session. A reconnect carrying Last-Event-ID may replay retained events while an old stream is closing. Legacy SSE-compatible behavior is limited to the text/event-stream delivery path; Streamable HTTP POST/GET/DELETE remains the default HTTP transport contract.

Request and notification handlers are called from the HTTP server's request handling threads. Outbound notifications and server-to-client requests are queued under an internal mutex; send_request() blocks until the client posts the matching response or the stream/session is stopped.

Constructor & Destructor Documentation

◆ HttpTransport()

mcp::server::HttpTransport::HttpTransport ( HttpTransportOptions options )

explicit

Construct a transport with normalized HTTP options.

Parameters

options Listen address, port, MCP path, and optional Origin policy.

Member Function Documentation

◆ client_capabilities()

std::optional< protocol::ClientCapabilities > mcp::server::HttpTransport::client_capabilities ( ) const

overridevirtual

Return capabilities from the active initialized HTTP session.

Reimplemented from mcp::server::Transport.

◆ client_capabilities_for_session()

std::optional< protocol::ClientCapabilities > mcp::server::HttpTransport::client_capabilities_for_session ( std::string_view session_id ) const

overridevirtual

Return capabilities from a specific initialized HTTP session.

Reimplemented from mcp::server::Transport.

◆ disconnect_session_sse()

void mcp::server::HttpTransport::disconnect_session_sse ( std::string_view session_id )

Request a server-initiated SSE stream disconnect for a session.

When enable_sse_polling is true, this signals the active SSE stream to close. The server sends a retry hint before closing. The client will automatically reconnect with Last-Event-ID per the SSE spec.

Parameters

session_id The session whose SSE stream should be disconnected.

◆ name()

std::string_view mcp::server::HttpTransport::name ( ) const

overridevirtualnoexcept

Return the diagnostic transport name "http".

Implements mcp::server::Transport.

◆ send_notification()

core::Result< core::Unit > mcp::server::HttpTransport::send_notification ( const protocol::JsonRpcNotification & notification )

overridevirtual

Queue an outbound notification for the active SSE stream.

Parameters

notification Notification to serialize.

Returns: core::Unit on success, or a core::Error for serialization failure or stopped transport state.

Implements mcp::server::Transport.

◆ send_notification_to_session()

core::Result< core::Unit > mcp::server::HttpTransport::send_notification_to_session	(	std::string_view	session_id,
		const protocol::JsonRpcNotification &	notification
	)

overridevirtual

Queue an outbound notification for a specific HTTP session.

Reimplemented from mcp::server::Transport.

◆ send_request()

core::Result< protocol::JsonRpcResponse > mcp::server::HttpTransport::send_request ( const protocol::JsonRpcRequest & request )

overridevirtual

Queue a server-to-client request on the active SSE stream.

Parameters

request Request to serialize and deliver.

Returns: The posted client response, or a core::Error if there is no active session, serialization fails, the stream closes, or the transport is stopped.

Reimplemented from mcp::server::Transport.

◆ send_request_to_session()

core::Result< protocol::JsonRpcResponse > mcp::server::HttpTransport::send_request_to_session	(	std::string_view	session_id,
		const protocol::JsonRpcRequest &	request
	)

overridevirtual

Queue a server-to-client request for a specific HTTP session.

Reimplemented from mcp::server::Transport.

◆ start()

core::Result< core::Unit > mcp::server::HttpTransport::start	(	RequestHandler	handler,
		NotificationHandler	notification_handler = `{}`
	)

overridevirtual

Start the HTTP server and serve the configured MCP endpoint.

Parameters

handler	Required request handler.
notification_handler	Optional notification handler.

Returns: core::Unit when the HTTP server exits, or a core::Error for invalid options, bind/listen failure, parse errors that cannot be reported to the client, or handler setup failures.

Note: This call blocks in the underlying HTTP server until stop() is called or the server stops listening.

Implements mcp::server::Transport.

◆ stop()

void mcp::server::HttpTransport::stop ( )

overridevirtualnoexcept

Stop the HTTP server and fail pending outbound requests.

Implements mcp::server::Transport.

◆ wait_until_ready()

void mcp::server::HttpTransport::wait_until_ready ( )

overridevirtual

Blocks until the underlying HTTP server socket is bound.

Reimplemented from mcp::server::Transport.

The documentation for this class was generated from the following file:

sdk/server/include/cxxmcp/server/http_transport.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HttpTransport()

Member Function Documentation

◆ client_capabilities()

◆ client_capabilities_for_session()

◆ disconnect_session_sse()

◆ name()

◆ send_notification()

◆ send_notification_to_session()

◆ send_request()

◆ send_request_to_session()

◆ start()

◆ stop()

◆ wait_until_ready()