Struct HttpBuilder 

pub struct HttpBuilder { /* private fields */ }

The builder behind the server transport.

Every method is optional and every default is safe. The one decision this builder does not make for the caller is which address to bind, and it defaults that to loopback rather than to every interface.

Implementations

impl HttpBuilder

pub fn new(server: Server) -> Self

Serves server, on loopback unless told otherwise.

The defaults are the crate’s own strict ones rather than the permissive ones, so a builder that sets nothing is already safe: loopback, the newest handshake-capable revision, and a session id from the system entropy pool.

pub fn legacy_sse(self) -> Self

Also serves the 2024-11-05 HTTP+SSE transport, beside Streamable HTTP.

A client opens a stream with GET /sse, is told where to POST by the endpoint event, and speaks 2024-11-05 over the pair. The same tools, resources and prompts answer on both transports, and the authenticator, Origin policy and rate limit set on this builder apply to both. Use legacy_sse_at to move the paths.

pub fn legacy_sse_at( self, stream: impl Into<String>, message: impl Into<String>, ) -> Self

legacy_sse, on stream and message rather than /sse and /messages.

Both must be absolute paths with no query; serve refuses to start otherwise.

pub const fn addr(self, addr: SocketAddr) -> Self

The address to bind. Defaults to 127.0.0.1:3000.

A non-loopback address is permitted but not made safe: this server speaks plain HTTP, so whatever is in front of it has to terminate TLS for it to be exposed to a network rather than to a machine.

pub const fn version(self, version: ProtocolVersion) -> Self

The revision to gate pre-handshake sessions with.

pub fn config(self, config: ServerConfig) -> Self

The endpoint policy and framing limits.

pub fn ids(self, ids: Arc<dyn IdSource + Send + Sync>) -> Self

Where session ids come from.

Defaults to a counter from this crate’s own source. Supply RandomIds — behind the random-ids feature — for an id a peer cannot guess, which is the right choice anywhere a session id authorises anything.

pub fn with_authenticator( self, authenticator: Arc<dyn Authenticator + Send + Sync>, ) -> Self

Replaces the anonymous default with a real implementation.

Pair with with_policy; a wired authenticator under the default AuthPolicy::Public is the silent fail-open the router’s into_router refuses at mount time. The same contract applies here, surfaced one layer up: a deployment that sets this without with_policy will see the misconfiguration at serve rather than at the first request.

pub const fn with_policy(self, policy: AuthPolicy) -> Self

Replaces the default AuthPolicy::Public policy.

A deployment that wired an authenticator above must also set Require(scopes) here, or into_router will refuse to build the route table. See McpRouter::with_policy for the matching contract.

pub fn with_origin_policy(self, origin: OriginPolicy) -> Self

Replaces the default Origin allow-list.

The default is OriginPolicy::strict(None), which refuses every Origin header sent and allows a request that sent none — see OriginPolicy::check for why absent is not the same as foreign. A deployment serving a browser over a non-loopback address will need to widen this to the page’s origin.

pub fn with_rate_limiter(self, limiter: RateLimiter) -> Self

Replaces the per-subject request allowance.

Defaults to ServerConfig::rate_limit(), so a configuration that set one does not have to set it twice.

pub async fn bind(self) -> Result<(TcpListener, ServeReport), ServeError>

Binds the listener without serving it.

Split from serving because a caller terminating TLS itself needs the listener before anything is served on it, and because binding before accepting removes the window in which a connection is refused for a port this process is about to take.

Errors

ServeError::Bind when the address is taken or unusable.

pub async fn serve(self) -> Result<ServeReport, ServeError>

Binds and serves until the accept loop fails.

Errors

ServeError from building the route table, from binding, or from the accept loop itself. A protocol error is not one of those: a peer whose request this server cannot serve is answered on the wire rather than raised here.

pub async fn serve_on( self, listener: TcpListener, ) -> Result<ServeReport, ServeError>

Serves on a listener the caller already bound.

The other half of bind, and the shape a deployment with TLS in front needs: bind, wrap the listener in a TLS acceptor, and serve on whatever that acceptor produces. Binding inside serve would make this impossible, because there would be no moment at which the raw listener was in the caller’s hands.

Errors

ServeError::Routes when the route table cannot be built, and ServeError::Accept when the loop does.

Trait Implementations

impl Debug for HttpBuilder

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Prints what was configured and nothing else.

Handwritten for the same reason as HttpHandler’s: a derived Debug would walk the Server and the id source, and neither belongs in a log line. The address and the ceiling are the two facts worth having when a serve has gone wrong.