basalt / ai-mcp/src / HttpStartOptions
Interface: HttpStartOptions
Defined in: ai-mcp/src/server.ts:67
Extends
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).
Inherited from
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).
Inherited from
ServeHttpOptions.allowedOrigins
allowProduction?
> optional allowProduction?: boolean
Defined in: ai-mcp/src/session.ts:33
Start even when NODE_ENV is production. Default false: the bridge is dev-only and refuses to start there (AiMcpProductionError). The bin's --allow-production flag (or BASALT_AI_MCP_ALLOW_PRODUCTION=1) sets it.
Inherited from
AiMcpOptions.allowProduction
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
Inherited from
allowUnconfirmedApply?
> optional allowUnconfirmedApply?: boolean
Defined in: ai-mcp/src/session.ts:27
Let basalt_make apply WITHOUT a confirmation when the client cannot be asked (no elicitation support — e.g. over HTTP, or a stdio client that did not announce the capability). Default false: such an apply is refused (fail closed). The bin's --allow-unconfirmed-apply flag sets it.
Inherited from
AiMcpOptions.allowUnconfirmedApply
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>
Inherited from
createProvider?
> optional createProvider?: () => AIProvider
Defined in: ai-mcp/src/session.ts:20
How to build the AI provider. Defaults to reading the session env. Injected in tests with a mock provider — no network, no keys.
Returns
AIProvider
Inherited from
AiMcpOptions.createProvider
createReader?
> optional createReader?: (root) => ProjectReader
Defined in: ai-mcp/src/session.ts:15
How to build a project reader for a root. Defaults to the filesystem (nodeReader). Injected in tests with an in-memory reader — no disk needed.
Parameters
root
string
Returns
ProjectReader
Inherited from
AiMcpOptions.createReader
cwd?
> optional cwd?: string
Defined in: ai-mcp/src/session.ts:8
Workspace root the tools/resources default to. Defaults to process.cwd().
Inherited from
AiMcpOptions.cwd
env?
> optional env?: Record<string, string | undefined>
Defined in: ai-mcp/src/session.ts:10
Environment the provider config is read from. Defaults to process.env.
Inherited from
AiMcpOptions.env
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.
Inherited from
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).
Inherited from
path?
> optional path?: string
Defined in: mcp-core/src/http.ts:24
JSON-RPC endpoint path. Default /mcp.
Inherited from
port?
> optional port?: number
Defined in: mcp-core/src/http.ts:14
Port to listen on. 0 (default) picks an ephemeral port.
Inherited from
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
Inherited from
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.
Inherited from
token?
> optional token?: string
Defined in: ai-mcp/src/server.ts:73
Shared secret: every request must carry Authorization: Bearer <token>. Required to bind a non-loopback host (unless authorize/allowRequest is given) — the Host/Origin guard is not authentication.