basalt / mcp-core/src / ServeHttpOptions
Interface: ServeHttpOptions
Defined in: mcp-core/src/http.ts:12
Extended by
Properties
allowedHosts?
> optional allowedHosts?: string[]
Defined in: mcp-core/src/http.ts:31
Extra hostnames to accept in the Host header, beyond the loopback names (localhost, 127.0.0.1, ::1). Set this when you deliberately bind a non-loopback host (e.g. 0.0.0.0 for remote/CI). Compared case-insensitively against the hostname only (port is ignored).
allowedOrigins?
> optional allowedOrigins?: string[]
Defined in: mcp-core/src/http.ts:36
Extra origins to accept in the Origin header, beyond loopback origins. Compared case-insensitively against the full origin (scheme + host + port).
allowRequest?
> optional allowRequest?: (origin, host, req) => boolean
Defined in: mcp-core/src/http.ts:43
Full override of the request-guard. Receives the request's origin (or undefined when absent), host header and the raw request (headers, socket.remoteAddress); return true to allow. When set, it replaces the default loopback + allowedHosts/allowedOrigins checks.
Parameters
origin
string | undefined
host
string | undefined
req
IncomingMessage
Returns
boolean
authorize?
> optional authorize?: (req) => boolean | Promise<boolean>
Defined in: mcp-core/src/http.ts:49
Authenticate a request that passed the host/origin guard — e.g. compare a bearer token. Return false to answer 401. Required (or allowRequest) when binding a non-loopback host.
Parameters
req
IncomingMessage
Returns
boolean | Promise<boolean>
host?
> optional host?: string
Defined in: mcp-core/src/http.ts:22
Host to bind. Default 127.0.0.1 (loopback — a dev-only surface). Binding a non-loopback address (e.g. 0.0.0.0) is REFUSED unless authorize or allowRequest is also set: the Host/Origin guard is not authentication (any non-browser client can send Host: 127.0.0.1), so a network-reachable server needs a real check.
maxBodyBytes?
> optional maxBodyBytes?: number
Defined in: mcp-core/src/http.ts:54
Largest accepted request body, in bytes. A larger body is answered 413 and is never buffered. Default DEFAULT_MAX_BODY_BYTES (1 MiB).
path?
> optional path?: string
Defined in: mcp-core/src/http.ts:24
JSON-RPC endpoint path. Default /mcp.
port?
> optional port?: number
Defined in: mcp-core/src/http.ts:14
Port to listen on. 0 (default) picks an ephemeral port.
principal?
> optional principal?: (req) => string | Promise<string | undefined> | undefined
Defined in: mcp-core/src/http.ts:79
Who is calling, for binding sessions: a session is only usable by requests that resolve to the principal that opened it. Default: a hash of the Authorization header (so one bearer token cannot use another's session; without Authorization, every caller is the same principal and the unguessable id alone protects the session).
Parameters
req
IncomingMessage
Returns
string | Promise<string | undefined> | undefined
sessions?
> optional sessions?: boolean | McpSessionOptions
Defined in: mcp-core/src/http.ts:71
Streamable-HTTP sessions — opt-in (true, or { ttlMs, maxSessions }). A successful initialize then answers with an Mcp-Session-Id header; every later request must carry it (400 without it, 404 for an unknown, expired or foreign one — the client then re-initializes) and DELETE with it ends the session. All requests of a session share one cancellation scope, so a notifications/cancelled POSTed separately aborts the call it names — while another session, even one guessing the request id, never can.
Default false (stateless): each POST is its own session, no header is issued or required, and only a client disconnect cancels a call. The default stays stateless so existing header-less clients of a dev bridge keep working; the runtime /mcp route of @basaltkit/mcp turns sessions on by default.