@orkestrel/mcp 0.0.8 → 0.0.10

package/dist/src/server/index.d.cts

@@ -6,10 +6,15 @@ import { EmitterInterface } from '@orkestrel/emitter';
 import { IncomingMessage } from 'node:http';
 import { JSONRPCMessage } from '../core/index.ts';
 import { JSONRPCMessage as JSONRPCMessage_2 } from '../../core/index.ts';
+import { JSONRPCRequest } from '../core/index.ts';
+import { JSONRPCResponse } from '../core/index.ts';
+import { MCPEra } from '../core/index.ts';
 import { MCPServerInterface } from '../core/index.ts';
 import { MCPTransportInterface } from '../core/index.ts';
+import { MCPVersion } from '../core/index.ts';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
+import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
 import { StreamInterface } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
@@ -29,6 +34,22 @@ import { UpgradeHandler } from '@orkestrel/server';
  */
 export declare function acceptsEventStream(request: Request): boolean;
 
+/**
+ * Whether an HTTP request satisfies the endpoint's origin gate.
+ *
+ * @remarks
+ * Validation is enabled by default. A request without `Origin` is allowed. A canonical origin
+ * whose host is the `localhost` or `[::1]` literal, or belongs to the `127.0.0.0/8` literal
+ * range, is allowed without configuration; every other present origin must occur exactly in
+ * the caller-supplied list. Invalid and opaque (`null`) origins are denied. `enabled: false`
+ * delegates validation to an upstream layer and allows the request through this gate.
+ *
+ * @param request - The fetch-standard request to validate
+ * @param options - Shared origin validation and delegation options
+ * @returns `true` when the request may reach MCP dispatch
+ */
+export declare function allowsOrigin(request: Request, options?: MCPOriginOptions): boolean;
+
 /**
  * Bridge a message-channel {@link ClientTransportInterface} (the shape the stdio and
  * WebSocket SERVER transports already implement) into the environment-agnostic
@@ -86,9 +107,9 @@ export declare function bridgeMessageTransport(transport: ClientTransportInterfa
  * correlation. Add `options.headers` (e.g. an `Authorization` bearer) to reach a guarded
  * server. `start` / `close` hold no connection; against a STATEFUL server it captures the
  * `mcp-session-id` from `initialize` and echoes it on later requests. It also captures
- * the initialize result's `protocolVersion` and sends `mcp-protocol-version` on every
- * subsequent request, so the same `MCPClient` passes the session and 2025-06-18
- * protocol gates without caller wiring.
+ * the initialize result's `protocolVersion` and sends `mcp-protocol-version` alone on each
+ * subsequent legacy request. Modern requests derive protocol and method headers directly
+ * from the message, plus a name header only for `tools/call`.
  *
  * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
  *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
@@ -113,12 +134,20 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * Create the Streamable-HTTP POST handler used by `createMCPRoutes`.
  *
  * @remarks
- * A present `mcp-protocol-version` header must name a supported revision; an
- * unsupported value returns an HTTP `400` JSON-RPC invalid-request error without
- * dispatching. An absent header is accepted for the initialize/bootstrap request.
- *
+ * Modern requests require matching protocol/method headers and a matching name header only
+ * for `tools/call`; mismatch returns HTTP `400` + `-32020`. Headerless `initialize` is
+ * accepted, while every other headerless request needs a live legacy session to supply its
+ * pinned version. A present origin must occur in `origin.origins` unless validation is
+ * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
+ * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
+ * signal with response-body cancellation and supplies the result to every dispatched modern
+ * handler through `MCPDispatchOptions.signal`. After every transport validation and immediately
+ * before dispatch, the optional synchronous `caller` extractor reads front-middleware state; a
+ * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
+ *
+ * @typeParam TState - The consumer's opaque per-request route state type
  * @param mcp - The transport-agnostic MCP server to dispatch through
- * @param streaming - Whether an event-stream response may be negotiated
+ * @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
  * @returns A request handler for the stateless MCP POST route
  *
  * @example
@@ -127,15 +156,15 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * import { createMCPPostHandler } from '@orkestrel/mcp/server'
  * import { createToolManager } from '@orkestrel/tool'
  *
- * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
- * const handler = createMCPPostHandler(mcp, true)
+ * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
+ * const handler = createMCPPostHandler(mcp, { streaming: true })
  * await handler(new Request('http://localhost/mcp', {
  * 	method: 'POST',
  * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
  * }))
  * ```
  */
-export declare function createMCPPostHandler(mcp: MCPServerInterface, streaming: boolean): (request: Request) => Promise<Response>;
+export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
 
 /**
  * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
@@ -152,12 +181,11 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, streaming:
  * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
  *   JSON-RPC REQUEST — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
  *   error / `-32600` Invalid Request, id `null`).
- * - A present `mcp-protocol-version` header is validated before dispatch: a supported
- *   value proceeds, while an unsupported value returns HTTP `400` with a JSON-RPC
- *   `-32600` body. An absent value proceeds for initialize/bootstrap compatibility.
- * - A **dispatch** result — a success OR an IN-BAND JSON-RPC error from `mcp.dispatch`
- *   (e.g. `-32601` method-not-found) — is an HTTP `200` carrying the JSON-RPC response
- *   envelope (the error is in-band per JSON-RPC, NOT an HTTP error).
+ * - Modern protocol/method/name headers are validated against the body; a mismatch is
+ *   HTTP `400` + `-32020`. Headerless initialize is accepted, a live legacy session supplies
+ *   its pinned revision, and every other headerless request is rejected.
+ * - Legacy dispatch errors stay IN-BAND at HTTP `200`; modern errors map to `400` for
+ *   `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise.
  * - A **notification** (a request with no `id`, which `dispatch` resolves to
  *   `undefined`) is a `202 Accepted` with no body.
  *
@@ -172,13 +200,15 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, streaming:
  * validates the `mcp-session-id`, and serves the resumable `GET {path}` + `DELETE {path}`,
  * leaving this route to dispatch the validated `POST`.
  *
- * This is MECHANISM, not policy: compose auth / CORS / rate-limiting (and the session
- * middleware) IN FRONT as ordinary middleware — the transport route adds none.
+ * This is MECHANISM, not policy: compose auth / rate-limiting (and the session middleware)
+ * IN FRONT as ordinary middleware; the optional `origin` group carries the deployment's shared
+ * allowlist or explicitly delegates validation to an upstream layer.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
- *   (default `true`); see {@link HTTPTransportOptions}
+ *   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
+ *   {@link HTTPTransportOptions}
  * @returns The {@link RouteInput}s to register with the router
  *
  * @example
@@ -186,11 +216,11 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, streaming:
  * import { createMCPServer, createToolManager } from '@src/core'
  * import { createMCPRoutes } from '@src/server'
  *
- * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
  * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -204,12 +234,17 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterfac
  * `path` (default {@link DEFAULT_MCP_PATH}); a request to any other path passes straight
  * through (`next()`).
  *
+ * A modern-shaped POST also passes straight through via `next()`, ignoring any session id.
+ * The remaining behavior is the legacy session layer:
+ *
  * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
  *   can re-read it via a freshly-built forwarded `Request`). Resolves a session via {@link
  *   readSessionHeader}: a VALID id touches the entry and sets `context.state.session`; an
  *   ABSENT / unknown id whose (guarded) body parses to an `initialize` request ({@link
  *   isInitializeRequest}) MINTS a fresh {@link MCPSession} (`crypto.randomUUID()`, `capacity`)
- *   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). It then
+ *   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). The
+ *   minted entry pins the negotiated legacy revision, which is supplied to a later headerless
+ *   live-session request. It then
  *   FORWARDS a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
  *   already-consumed original — so the route re-reads the same body, and stamps the response
  *   with {@link MCP_SESSION_HEADER}.
@@ -217,8 +252,8 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterfac
  *   an invalid / unknown id is the same `404`. A valid session opens the resumable
  *   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
  *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
- *   attaching the stream for live pushes, then attaches; a client disconnect (`request.signal`)
- *   detaches it. Long-lived — never `end()`ed here.
+ *   attaching the stream for live pushes, then attaches; cancellation of the streamed response
+ *   body composes with `request.signal` and detaches it. Long-lived — never `end()`ed here.
  * - **`DELETE {path}`.** Resolves the session; a valid id deletes it from the store and answers
  *   `204`; an invalid / unknown id is the same `404`.
  *
@@ -232,7 +267,8 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterfac
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}), `ttl` (idle-session
  *   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `capacity`
  *   (the folded per-session replay-log bound), and `clock` (the deterministic epoch-ms clock;
- *   defaults to `Date.now`); see {@link MCPSessionOptions}
+ *   defaults to `Date.now`), plus the shared `origin` validation options; see
+ *   {@link MCPSessionOptions}
  * @returns A {@link MiddlewareHandler} that mints / validates sessions + serves the resumable
  *   `GET` / `DELETE`
  *
@@ -241,13 +277,22 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterfac
  * import { createMCPServer, createToolManager } from '@src/core'
  * import { createMCPRoutes, createMCPSession } from '@src/server'
  *
- * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
  * router.use(createMCPSession({ ttl: 60_000 })) // stateful: mint + validate + resumable GET / DELETE
  * router.add(createMCPRoutes(mcp)) // the route stays session-agnostic
  * ```
  */
 export declare function createMCPSession<TState extends MCPSessionState>(options?: MCPSessionOptions): MiddlewareHandler<TState>;
 
+/**
+ * Create a readable stream from its pull and cancellation behaviours.
+ *
+ * @param pull - The behaviour that supplies the stream's next chunk
+ * @param cancel - The behaviour that releases the stream after consumer cancellation
+ * @returns A readable stream backed by the supplied behaviours
+ */
+export declare function createReadableStream<T>(pull: (controller: ReadableStreamDefaultController<T>) => void | PromiseLike<void>, cancel: (reason?: unknown) => void | PromiseLike<void>): ReadableStream<T>;
+
 /**
  * Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
  * — a {@link ClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
@@ -307,7 +352,7 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * import { createMCPServer, createToolManager } from '@src/core'
  * import { createStdioServer } from '@src/server'
  *
- * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
  * createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
  * ```
  */
@@ -390,7 +435,7 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * import { createMCPServer, createToolManager } from '@src/core'
  * import { createWebSocketServer } from '@src/server'
  *
- * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
  * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
  * ```
  */
@@ -410,6 +455,16 @@ export declare function createWebSocketServer(mcp: MCPServerInterface, options?:
  */
 export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
 
+/**
+ * The default interval in milliseconds between SSE keepalive comments on held-open MCP
+ * responses.
+ *
+ * @remarks
+ * Fifteen seconds is infrequent enough to avoid chatty idle connections while bounding dead
+ * client detection and staying comfortably inside common intermediary idle windows.
+ */
+export declare const DEFAULT_MCP_KEEPALIVE_INTERVAL = 15000;
+
 /** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
 export declare const DEFAULT_MCP_PATH = "/mcp";
 
@@ -513,16 +568,17 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   readEventStream}) — the inverse of the server's `openStream` seam, so the wire
  *   round-trips. A `202`
  *   Accepted (a notification) carries no body and emits nothing.
- * - **Session and protocol echo.** `start()` is a no-op (a
+ * - **Session and protocol headers.** `start()` is a no-op (a
  *   request/response transport opens no long-lived connection). The
  *   `mcp-session-id` response header, when a STATEFUL server sends one (on
  *   `initialize`), is captured into `session` and then ECHOED as the
  *   `mcp-session-id` request header on every SUBSEQUENT request — so an
  *   `MCPClient` passes a stateful server's session validation. The
  *   initialize result's `protocolVersion` is likewise captured, but only
- *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` on
- *   every subsequent request, as required by the 2025-06-18 Streamable-HTTP
- *   transport. Before initialize returns, neither captured header is sent.
+ *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
+ *   subsequent legacy requests. Modern requests instead derive protocol and method
+ *   headers from the message, plus the name header only for `tools/call`.
+ *   Before initialize returns, neither captured legacy header is sent.
  *   `close()` clears the captured protocol so a reconnect's `initialize`
  *   POST is headerless; the captured `session` persists across `close()`.
  * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
@@ -575,28 +631,79 @@ export declare interface HTTPClientTransportOptions {
 }
 
 /**
- * Options for `createMCPRoutes` — the path the transport is mounted at and whether an SSE
- * response is allowed. `createMCPRoutes` is STATELESS; sessions are a separate middleware
- * ({@link import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ * Options shared by the MCP Streamable-HTTP POST handler and route factory.
  *
  * @remarks
- * - `path` — the request path the single `POST` route answers; defaults to
- *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this
- *   path get the spine's automatic `405` unless a {@link
- *   import('./middlewares.js').createMCPSession} middleware (which owns the same `path`) is
- *   mounted IN FRONT to serve them.
  * - `streaming` — when `true` (the DEFAULT) the transport MAY answer with a
  *   Server-Sent-Events response (one `data:` event carrying the JSON-RPC reply, then
  *   the stream ends) whenever the client's `Accept` header includes
  *   `text/event-stream`; when `false` it always answers with a plain JSON body. Either
  *   mode carries the SAME JSON-RPC response envelope — the choice is purely the wire
  *   framing the Streamable-HTTP spec lets the client negotiate.
+ * - `origin` — the shared origin-validation options passed to both the route and session
+ *   enforcement sites. Validation is enabled by default: requests without `Origin` pass,
+ *   canonical loopback-literal origins pass, and every other present `Origin` must occur
+ *   exactly in `origin.origins`. Set `origin.enabled` to `false` only when validation is
+ *   delegated upstream; `origins` is ignored in that mode. Both enforcement sites must receive
+ *   the same value.
+ * - `keepalive` — the SSE liveness options for held-open responses. `interval` defaults to
+ *   {@link import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}. Keepalives never apply
+ *   to unary responses.
+ * - `caller` — the synchronous extractor for consumer-asserted caller context already resolved
+ *   by front middleware. It runs only for a validated request that will dispatch. Returning
+ *   `undefined` omits caller context; a throw propagates.
  */
-export declare interface HTTPTransportOptions {
-    readonly path?: string;
+export declare interface HTTPHandlerOptions<TState = unknown> {
     readonly streaming?: boolean;
+    /** Must match the session layer's value; `origins` is ignored when `enabled` is `false`. */
+    readonly origin?: MCPOriginOptions;
+    readonly keepalive?: MCPKeepaliveOptions;
+    readonly caller?: MCPCallerHandler<TState>;
+}
+
+/**
+ * Options for `createMCPRoutes` — the mount path plus the shared POST-handler options.
+ * `createMCPRoutes` is STATELESS; sessions are a separate middleware ({@link
+ * import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ *
+ * @remarks
+ * `path` is the request path the single `POST` route answers; it defaults to {@link
+ * import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this path get
+ * the spine's automatic `405` unless a {@link import('./middlewares.js').createMCPSession}
+ * middleware owning the same path is mounted in front. The remaining options are inherited
+ * from {@link HTTPHandlerOptions}.
+ */
+export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHandlerOptions<TState> {
+    readonly path?: string;
 }
 
+/**
+ * Infer the legacy revision an `initialize` request negotiates.
+ *
+ * @remarks
+ * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
+ * request selects the newest supported legacy revision, matching the core initialize result.
+ *
+ * @param request - The legacy initialize request
+ * @returns The negotiated legacy protocol revision
+ */
+export declare function inferLegacyVersion(request: JSONRPCRequest): MCPVersion;
+
+/**
+ * Infer the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
+ *
+ * @remarks
+ * Notifications are accepted with `202`. Legacy response envelopes retain uniform `200`
+ * status semantics, including in-band errors. Modern header/capability/version/parameter
+ * failures map to `400`, method-not-found maps to `404`, and every other modern result maps
+ * to `200`.
+ *
+ * @param response - The dispatch response, or `undefined` for a notification
+ * @param era - The structurally selected request era
+ * @returns The HTTP response status
+ */
+export declare function inferStatus(response: JSONRPCResponse | undefined, era: MCPEra): number;
+
 /**
  * The result of folding one more chunk of raw stdio bytes into a newline-framed
  * buffer — every COMPLETE line extracted (newline-terminated in the wire bytes) plus
@@ -611,6 +718,27 @@ export declare interface LineExtraction {
     readonly remainder: string;
 }
 
+/**
+ * Whether a modern HTTP request's required standard headers match its JSON-RPC body.
+ *
+ * @remarks
+ * Requires `MCP-Protocol-Version` to equal the reserved `_meta` version and `Mcp-Method`
+ * to equal `method`. `Mcp-Name` is required only for `tools/call`, where it must equal
+ * `params.name`; discovery and listing requests need no name because none is derivable.
+ * Legacy requests return `false` because this predicate models the modern contract only.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param message - The parsed JSON-RPC request body
+ * @returns `true` only when every method-applicable modern header matches
+ */
+export declare function matchesModernHeaders(request: Request, message: JSONRPCRequest): boolean;
+
+/** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
+export declare const MCP_METHOD_HEADER = "mcp-method";
+
+/** The modern Streamable-HTTP request header carrying a named method's target. */
+export declare const MCP_NAME_HEADER = "mcp-name";
+
 /**
  * The Streamable-HTTP transport header carrying the negotiated MCP protocol version
  * on every post-initialize client request.
@@ -643,6 +771,52 @@ export declare const MCP_SESSION_HEADER = "mcp-session-id";
  */
 export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 
+/**
+ * Synchronously extract consumer-asserted caller context from an HTTP request after the
+ * transport has validated it for dispatch.
+ *
+ * @remarks
+ * Authentication belongs to middleware composed in front of the MCP route. This handler only
+ * reads what that middleware already resolved. Returning `undefined` supplies no caller; a
+ * throw propagates as a route-handler throw. The result remains `unknown` because this package
+ * cannot verify caller identity.
+ *
+ * @typeParam TState - The consumer's opaque per-request route state type
+ * @param request - The validated Fetch request that will dispatch
+ * @param context - The router context, or `undefined` for direct handler invocation
+ * @returns Consumer-asserted caller context, or `undefined` for no caller
+ */
+export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
+
+/**
+ * Shared SSE keepalive options for held-open HTTP responses.
+ *
+ * @remarks
+ * - `interval` — milliseconds between SSE comment frames. Defaults to {@link
+ *   import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}. Each comment keeps an idle
+ *   connection live through intermediaries and bounds how long a dead client can remain
+ *   unobserved by the HTTP writer.
+ */
+export declare interface MCPKeepaliveOptions {
+    readonly interval?: number;
+}
+
+/**
+ * Shared options for the protocol-required HTTP `Origin` validation at the route and session
+ * enforcement sites.
+ *
+ * @remarks
+ * - `enabled` — whether this package validates `Origin`; defaults to `true`. Set `false` only
+ *   when an upstream layer performs the validation for the deployment.
+ * - `origins` — the exact serialized non-loopback origins accepted when an `Origin` header is
+ *   present. Omission still accepts requests without `Origin` and canonical loopback-literal
+ *   origins (`localhost`, `[::1]`, and `127.0.0.0/8`).
+ */
+export declare interface MCPOriginOptions {
+    readonly enabled?: boolean;
+    readonly origins?: readonly string[];
+}
+
 /**
  * One MCP transport session — the per-session entity a {@link
  * import('./middlewares.js').createMCPSession} middleware owns, keyed by its `id`, carrying the
@@ -718,10 +892,14 @@ export declare class MCPSession implements MCPSessionInterface {
  * - `session` — the live {@link MCPSession} entity the store keys by session id.
  * - `touched` — the epoch-ms instant of the last access; the entry is replaced on every
  *   resolved request so the middleware's lazy sweep can evict an idle entry past `ttl`.
+ * - `version` — the legacy revision negotiated by the session's initialize request, used
+ *   when a later live-session request legitimately omits its protocol header.
  */
 export declare interface MCPSessionEntry {
     readonly session: MCPSession;
     readonly touched: number;
+    /** The legacy revision negotiated when this session was minted. */
+    readonly version: MCPVersion;
 }
 
 /**
@@ -775,12 +953,22 @@ export declare interface MCPSessionInterface {
  *   uses directly for its own session-touch / TTL-sweep bookkeeping; defaults to `Date.now`. The
  *   deterministic clock a TTL test advances explicitly instead of racing a real idle window
  *   against wall-clock (AGENTS §16). Production never sets it.
+ * - `origin` — the same shared origin-validation options supplied to `createMCPRoutes`.
+ *   Validation is enabled by default, accepts canonical loopback-literal origins, and rejects
+ *   every other present origin outside its exact list before any session is minted. Set
+ *   `origin.enabled` to `false` only when validation is delegated upstream; `origins` is ignored
+ *   in that mode. Both enforcement sites must receive the same value.
+ * - `keepalive` — the SSE liveness options for the held-open resumable response. `interval`
+ *   defaults to {@link import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}.
  */
 export declare interface MCPSessionOptions {
     readonly path?: string;
     readonly ttl?: number;
     readonly capacity?: number;
     readonly clock?: () => number;
+    /** Must match the route layer's value; `origins` is ignored when `enabled` is `false`. */
+    readonly origin?: MCPOriginOptions;
+    readonly keepalive?: MCPKeepaliveOptions;
 }
 
 /**
@@ -857,7 +1045,7 @@ export declare function readSessionHeader(request: Request): string | undefined;
  * JSON-RPC error body.
  *
  * @remarks
- * Returns `Response.json(jsonRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
+ * Returns `Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
  * { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
  * JSON-RPC error BODY with a `null` id) but at the session-not-found status. Shared by
  * every {@link import('./middlewares.js').createMCPSession} validation site — the
@@ -869,6 +1057,15 @@ export declare function readSessionHeader(request: Request): string | undefined;
  */
 export declare function rejectUnknownSession(): Response;
 
+/** The `X-Accel-Buffering` value that disables reverse-proxy buffering. */
+export declare const SSE_BUFFERING_DISABLED = "no";
+
+/** The reverse-proxy response header controlling buffering of an SSE response. */
+export declare const SSE_BUFFERING_HEADER = "x-accel-buffering";
+
+/** The comment text written by the held-open MCP response keepalive. */
+export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
+
 /**
  * The stdio CLIENT transport for the Model Context Protocol — a
  * {@link ClientTransportInterface} that drives a CHILD PROCESS MCP server over