mcpose 2.1.1 → 3.1.0

package/src/core.ts

@@ -0,0 +1,2129 @@
+/** MCP proxy core: wires server→upstream through middleware pipelines. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { randomUUID } from 'node:crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  type ListToolsRequest,
+  type ListToolsResult,
+  ListToolsRequestSchema,
+  PromptListChangedNotificationSchema,
+  ReadResourceRequestSchema,
+  ResourceListChangedNotificationSchema,
+  ToolListChangedNotificationSchema,
+  type CallToolRequest,
+  type CallToolRequestParams,
+  type CallToolResult,
+  type CompatibilityCallToolResult,
+  type ContentBlock,
+  type GetPromptRequest,
+  type GetPromptResult,
+  type TextContent,
+  type ReadResourceRequest,
+  type ReadResourceResult,
+  type ServerCapabilities,
+  type Tool,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { pipe, isPassThroughObserver, type Middleware } from './middleware.js';
+import type { HiddenToolPredicate } from './hiddenTools.js';
+import type { BackendClient } from './backendClient.js';
+import {
+  createProxyContext,
+  type ProxyContext,
+  type ProxyIdentity,
+} from './proxyContext.js';
+import type { Identity } from './identity.js';
+import type {
+  BackendDegradedTelemetryEvent,
+  TelemetryEvent,
+  ToolCallTelemetryEvent,
+} from './telemetry.js';
+import {
+  listAcrossMesh,
+  namespaceName,
+  namespaceUri,
+  normalizeBackends,
+  routeNamespaced,
+  routeResourceUri,
+  type Backends,
+  type MeshEntry,
+} from './mesh.js';
+import {
+  attachDelegationMeta,
+  detectDelegationLoop,
+  readInboundDelegation,
+} from './delegation.js';
+import { createInMemoryEventStore, scopeEventStore } from './eventStore.js';
+import {
+  initializeParamsOf,
+  replayInitialize,
+  type SessionRegistry,
+} from './sessionRegistry.js';
+import type { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isRejectionReason, rejectionMcpError } from './rejection.js';
+import type { RejectionReason } from './rejection.js';
+import { VERSION } from './version.js';
+
+/**
+ * Middleware for tool calls.
+ * Uses `CompatibilityCallToolResult` to cover legacy `{ toolResult }` shape
+ * (protocol 2024-10-07). Narrow with `hasToolContent()` before accessing `.content`.
+ */
+export type ToolMiddleware = Middleware<
+  CallToolRequest,
+  CompatibilityCallToolResult
+>;
+
+/** Middleware for resource reads. */
+export type ResourceMiddleware = Middleware<
+  ReadResourceRequest,
+  ReadResourceResult
+>;
+
+/** Middleware for prompt fetches (`prompts/get`). */
+export type PromptMiddleware = Middleware<GetPromptRequest, GetPromptResult>;
+
+/** Middleware for tool-list responses. */
+export type ListToolsMiddleware = Middleware<ListToolsRequest, ListToolsResult>;
+
+/**
+ * The result channels of a `CallToolResult` — everything a redaction or
+ * transform middleware must account for:
+ *
+ * 1. `content` blocks (text, image, audio, resource link, embedded
+ *    resource), each carrying its own block-level `_meta`,
+ * 2. `structuredContent`, the machine-readable mirror of the content,
+ * 3. result-level `_meta`,
+ * 4. `isError`,
+ * 5. unknown extra keys via the index signature.
+ *
+ * Redaction that maps only `.content` misses 2, 3, and the non-text
+ * members of 1. Use {@link mapToolResult} to cover every payload channel
+ * by construction; channel 3 is stripped at the proxy boundary by default
+ * via `ProxyOptions.stripResultMeta` (ADR-0009).
+ *
+ * This guard narrows `CompatibilityCallToolResult` to `CallToolResult`
+ * (has `.content` array). Both union members carry `[x: string]: unknown`,
+ * so this avoids unsafe casts.
+ *
+ * A guard, not an assertion: the union's two members are both objects, but a
+ * pipeline result is not the union. The legacy shape has no `.content`, and a
+ * handler that produced nothing at all (a local tool with a missing `return`,
+ * or a middleware that dropped the result) produces a nullish one, which has
+ * none either. Both answer `false` here. Throwing instead replaced whatever
+ * the pipeline produced with `TypeError: Cannot read properties of undefined
+ * (reading 'content')` — inside `mapToolResult`, and inside the `tools/call`
+ * handler's telemetry read of `result.isError`.
+ */
+export function hasToolContent(
+  r: CompatibilityCallToolResult,
+): r is CallToolResult {
+  return (
+    r !== null &&
+    typeof r === 'object' &&
+    Array.isArray((r as { content?: unknown }).content)
+  );
+}
+
+/**
+ * Handlers for {@link mapToolResult}, one per payload channel. All three
+ * are required, so forgetting a channel is a compile error rather than a
+ * silent leak.
+ */
+export interface ToolResultHandlers {
+  /** Maps a text content block. Return `null` to drop the block. */
+  onText: (block: TextContent) => ContentBlock | null;
+  /**
+   * Maps a non-text content block (image, audio, resource link, embedded
+   * resource). Return `null` to drop the block.
+   */
+  onOther: (block: Exclude<ContentBlock, TextContent>) => ContentBlock | null;
+  /**
+   * Maps `structuredContent`. Called only when the field is present.
+   * Return `undefined` to remove the field entirely.
+   */
+  onStructured: (
+    structured: Record<string, unknown>,
+  ) => Record<string, unknown> | undefined;
+}
+
+/**
+ * Maps every payload channel of a tool result through the given handlers.
+ *
+ * The legacy `{ toolResult }` shape (protocol 2024-10-07) is returned
+ * untouched. `isError`, result-level `_meta`, and unknown extra keys are
+ * preserved by spread — result-level `_meta` needs no handler because the
+ * proxy strips it by default (`stripResultMeta`, ADR-0009); with
+ * `stripResultMeta: false` forwarding it is the consumer's explicit choice.
+ */
+export function mapToolResult(
+  result: CompatibilityCallToolResult,
+  handlers: ToolResultHandlers,
+): CompatibilityCallToolResult {
+  if (!hasToolContent(result)) return result;
+  const content = result.content
+    .map((block) =>
+      block.type === 'text' ? handlers.onText(block) : handlers.onOther(block),
+    )
+    .filter((block): block is ContentBlock => block !== null);
+  const structured =
+    result.structuredContent === undefined
+      ? undefined
+      : handlers.onStructured(result.structuredContent);
+  const { structuredContent: _dropped, ...rest } = result;
+  return {
+    ...rest,
+    content,
+    ...(structured === undefined ? {} : { structuredContent: structured }),
+  };
+}
+
+/** HTTP transport options for {@link startHttpProxy}. */
+export interface HttpProxyOptions {
+  /** Default: 3000 */
+  port?: number;
+  /**
+   * Bind address. Default: `'127.0.0.1'` (loopback).
+   *
+   * Binding a non-loopback address (e.g. `'0.0.0.0'`) exposes an
+   * unauthenticated MCP proxy holding an authenticated upstream session to
+   * the network, so it is a deliberate opt-in; doing so without
+   * {@link resolveIdentity} reports a startup warning through {@link onError}.
+   */
+  host?: string;
+  /** Default: '/mcp' */
+  path?: string;
+  /**
+   * Called for every incoming request before MCP handling. Return false to
+   * block (caller writes its own response). Throw to get a 401, with the error
+   * reported through {@link onError}.
+   */
+  onRequest?: (
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ) => boolean | Promise<boolean>;
+  /**
+   * Called on unhandled errors instead of console.error, and on every auth
+   * hook that throws: the request still fails closed, and the operator still
+   * sees why. If this hook itself throws or returns a rejected promise, the
+   * failure is contained and changes nothing the caller sees.
+   */
+  onError?: (err: unknown) => unknown;
+  /**
+   * Maximum request body size in bytes. Excess POST bodies return 413.
+   * Default: 4 MB. Set to `Infinity` to opt out of the cap.
+   *
+   * `0` is a valid value and means "reject every POST body", so it is not the
+   * opt-out. The two shapes that are mistakes rather than choices throw at
+   * startup: a negative number returns 413 for every POST, and `NaN`, which is
+   * what `Number(process.env.MAX_BODY_BYTES)` returns for an unset key,
+   * compares false against every body size and so gates nothing at all.
+   */
+  maxBodyBytes?: number;
+  /**
+   * Maximum number of concurrent MCP sessions. Excess requests return 503.
+   * Default: 1000. Set to `Infinity` to opt out of the cap.
+   *
+   * `0` is a valid value and means "reject every session", so it is not the
+   * opt-out.
+   */
+  maxSessions?: number;
+  /**
+   * Session TTL in milliseconds. Sessions are closed after this duration,
+   * which fires {@link onSessionClosed}. Default: 30 minutes. Finite values
+   * must not exceed Node's maximum timer delay of 2,147,483,647 ms. Set to
+   * `Infinity` to opt out of the TTL.
+   */
+  sessionTtlMs?: number;
+  /**
+   * Resolves caller identity from the initial session request.
+   * Called once per new session; the result is stamped on every
+   * {@link ProxyContext} within that session.
+   *
+   * Supply a JWT extractor, mTLS cert reader, API-key lookup, or any async
+   * function returning an {@link Identity}. Errors thrown here abort the
+   * session with a 401 and are reported through {@link onError}.
+   *
+   * @example
+   * resolveIdentity: extractJwtIdentity({ jwksUri: '...' })
+   */
+  resolveIdentity?: (req: http.IncomingMessage) => Identity | Promise<Identity>;
+  /**
+   * TLS options for mutual TLS (mTLS). When provided, the proxy listens on
+   * HTTPS and requires client certificates signed by the supplied CA.
+   *
+   * @example
+   * tlsOptions: {
+   *   key: fs.readFileSync('server.key'),
+   *   cert: fs.readFileSync('server.crt'),
+   *   ca: fs.readFileSync('trusted-ca.crt'),
+   *   requestCert: true,
+   *   rejectUnauthorized: true,
+   * }
+   */
+  tlsOptions?: https.ServerOptions;
+  /**
+   * Event store for SSE reconnect replay. Defaults to an in-memory store
+   * (suitable for single-instance deployments). For multi-instance / HA
+   * deployments, supply a Redis or Postgres-backed implementation.
+   *
+   * Stream ids reach the store namespaced as `<sessionId>:<streamId>`, so
+   * one store serves every session without their replay histories mixing.
+   *
+   * Set to `null` to disable reconnect replay entirely.
+   */
+  eventStore?: EventStore | null;
+  /**
+   * Shared record of live sessions, so a client can resume after a proxy
+   * restart or on another instance behind a load balancer. Without one,
+   * sessions live only in this process and a resume against a fresh process
+   * is a 404.
+   *
+   * A record is written before the initialize response goes out and read
+   * only for an `mcp-session-id` this instance does not hold; the resumed
+   * session negotiates what the original did, keeps its identity, and dies
+   * at the original deadline. Client DELETE and TTL expiry delete the
+   * record, server shutdown keeps it. Pair it with the matching
+   * {@link eventStore} adapter, or a resumed session has no replay history.
+   *
+   * @example
+   * sessionRegistry: createRedisSessionRegistry(redis),
+   * eventStore: createRedisEventStore(redis),
+   */
+  sessionRegistry?: SessionRegistry;
+  /**
+   * Called when a session is closed (client DELETE, TTL expiry, or server
+   * shutdown). Wire {@link AuditMiddlewareHandle.closeSession} here to flush
+   * the ReplayManifest for the session.
+   *
+   * A returned promise is awaited: `server.close()` does not complete until
+   * every session's hook has settled, so a host that exits in the close
+   * callback never loses a final manifest. A throw or a rejection is routed
+   * to {@link onError} and never breaks teardown.
+   *
+   * @example
+   * onSessionClosed: (sessionId) => auditHandle.closeSession(sessionId)
+   */
+  onSessionClosed?: (sessionId: string) => unknown;
+  /**
+   * Re-validates an existing session on every routed request. Return `false`
+   * (or throw, which is reported through {@link onError}) to reject with 401.
+   * Use to bind sessions to their original credential — e.g. re-check the
+   * bearer token — so a leaked `mcp-session-id` alone cannot take over a
+   * session.
+   */
+  validateSession?: (
+    req: http.IncomingMessage,
+    session: { sessionId: string; identity?: Identity },
+  ) => boolean | Promise<boolean>;
+  /**
+   * Hosts allowed in the `Host` header when
+   * {@link enableDnsRebindingProtection} is on. Forwarded to the SDK
+   * transport, which only validates against a non-empty list.
+   *
+   * Default: for a loopback bind, derived from the effective bind address
+   * and the real listening port (`127.0.0.1:<port>`, `localhost:<port>`,
+   * `[::1]:<port>`). An explicit value is used verbatim, never merged with
+   * the derived list. No list is derived for a non-loopback bind.
+   */
+  allowedHosts?: string[];
+  /**
+   * Origins allowed in the `Origin` header. Forwarded to the SDK transport,
+   * which only validates against a non-empty list.
+   *
+   * Default: for a loopback bind, the derived {@link allowedHosts} entries
+   * as origins (`http://` or `https://` matching {@link tlsOptions}). An
+   * explicit value is used verbatim, never merged.
+   */
+  allowedOrigins?: string[];
+  /**
+   * Enables the SDK transport's DNS-rebinding protection (Host/Origin
+   * checks). Default: `true` when the effective bind address is loopback,
+   * `false` otherwise (a non-loopback bind usually sits behind a gateway
+   * that rewrites `Host`).
+   *
+   * Enabling this on a non-loopback bind without explicit
+   * {@link allowedHosts} / {@link allowedOrigins} validates nothing and
+   * reports a startup warning through {@link onError}.
+   */
+  enableDnsRebindingProtection?: boolean;
+}
+
+/**
+ * A tool the proxy implements itself, instead of forwarding to the
+ * upstream. See ADR-0007.
+ */
+export interface LocalTool {
+  /** The tool definition advertised in `tools/list`. */
+  tool: Tool;
+  /**
+   * Runs instead of the upstream call, from inside the innermost `next`,
+   * so the whole `toolMiddleware` pipeline (audit, redaction) still
+   * applies.
+   */
+  handler: (
+    params: CallToolRequestParams,
+    context: ProxyContext,
+  ) => Promise<CallToolResult>;
+}
+
+/** Proxy server options. */
+export interface ProxyOptions {
+  /**
+   * Human-readable name for this proxy instance. Required, and rejected at
+   * construction when empty or whitespace-only.
+   *
+   * It is stamped onto every `ProxyContext`, every audit event, and the
+   * `ReplayManifest` as provenance (ADR-0012), so a default would record a
+   * whole fleet under one name: attribution in appearance only (#122).
+   */
+  name: string;
+
+  /**
+   * Version of this proxy server (yours, not the mcpose library). MCP clients see
+   * it in the `initialize` response. Defaults to the mcpose library version when
+   * omitted; set it to your own release version when you ship your proxy.
+   */
+  version?: string;
+
+  /**
+   * Tool middleware in response-processing order (first = innermost).
+   * @example [piiMW, auditMW]  // pii redacts first, audit logs clean data
+   */
+  toolMiddleware?: ReadonlyArray<ToolMiddleware>;
+
+  /** Resource middleware in response-processing order (first = innermost). */
+  resourceMiddleware?: ReadonlyArray<ResourceMiddleware>;
+
+  /**
+   * Prompt middleware in response-processing order (first = innermost),
+   * per ADR-0002. Runs around every `prompts/get`, in both 1:1 and mesh
+   * mode.
+   *
+   * Mesh routing and the `BACKEND_UNROUTABLE` rejection for an unroutable
+   * prompt name happen inside the innermost `next` (the ADR-0007 pattern),
+   * so an observing middleware such as audit records every prompt call
+   * including the rejected ones.
+   *
+   * `prompts/list` has no pipeline yet; hiding and pass-through for prompts
+   * are deferred with it (ADR-0014).
+   */
+  promptMiddleware?: ReadonlyArray<PromptMiddleware>;
+
+  /** Tool-list middleware in response-processing order (first = innermost). */
+  listToolsMiddleware?: ReadonlyArray<ListToolsMiddleware>;
+
+  /**
+   * Tools that skip transforming middleware — upstream response forwarded
+   * as-is. Middleware wrapped in `markPassThroughObserver()` (e.g. audit)
+   * still runs for these tools.
+   */
+  passThroughTools?: ReadonlyArray<string>;
+
+  /**
+   * Resources that skip middleware — upstream response forwarded as-is.
+   * Matched against the URI the client sees, which in mesh mode is
+   * `mcpose://<backendKey>/<uri>` (ADR-0022).
+   */
+  passThroughResources?: ReadonlyArray<string>;
+
+  /**
+   * Tools hidden from list_tools and rejected at runtime with
+   * MethodNotFound. Precedence: a tool listed here AND in
+   * `passThroughTools` stays hidden. Hidden filtering is applied both
+   * before and after `listToolsMiddleware`, so list middleware cannot
+   * re-expose a hidden tool.
+   *
+   * A name array cannot see through a dispatcher (meta-tool) that takes
+   * the real tool name as an argument. Pass a {@link HiddenToolPredicate}
+   * (e.g. {@link dispatcherAwareBlock}) to close that bypass: it receives
+   * `undefined` args during list filtering and always an object at call
+   * time. See ADR-0006.
+   */
+  hiddenTools?: ReadonlyArray<string> | HiddenToolPredicate;
+
+  /**
+   * Resources hidden from list_resources and rejected at runtime with
+   * InvalidRequest. Matched against the URI the client sees, which in mesh
+   * mode is `mcpose://<backendKey>/<uri>` (ADR-0022).
+   */
+  hiddenResources?: ReadonlyArray<string>;
+
+  /**
+   * Strips `params._meta` from every request the proxy forwards (tool
+   * calls, resource reads, list and prompt calls). Default: `true`.
+   *
+   * MCP clients put correlation identifiers there (VS Code sends
+   * `progressToken`, a W3C `traceparent`, and `vscode/conversationId`),
+   * and the upstream is frequently a third party. The strip happens at the
+   * proxy boundary, before the pipeline, so middleware sees the stripped
+   * request and can still add its own `_meta` deliberately. Progress relay
+   * is unaffected: the proxy reads the client's progress token from the
+   * server-side request `extra`, and the SDK client stamps its own token
+   * on the upstream request.
+   *
+   * Applies to `passThroughTools` too; disable only globally with `false`
+   * for upstreams that read other `_meta` keys. See ADR-0008.
+   */
+  stripRequestMeta?: boolean;
+
+  /**
+   * Strips top-level `_meta` from every result the proxy returns from the
+   * upstream (tool calls, resource reads, list and prompt calls).
+   * Default: `true`.
+   *
+   * The response-direction mirror of {@link stripRequestMeta}: upstreams
+   * stamp correlation identifiers there (the SDK stamps
+   * `io.modelcontextprotocol/related-task`), and the client is a third
+   * party to them. The strip happens at the upstream boundary, inside the
+   * innermost `next`, so middleware sees the stripped result and any
+   * `_meta` middleware adds deliberately still reaches the client.
+   *
+   * Local tool results are not stripped (they have no upstream), and
+   * nested `_meta` (per-tool in `tools[]`, per-block in `content`) is
+   * untouched. Applies to pass-through tools and resources too; disable
+   * only globally with `false`. See ADR-0009.
+   */
+  stripResultMeta?: boolean;
+
+  /**
+   * Tools the proxy implements itself. Local tools appear in `tools/list`
+   * (first page only, so pagination does not duplicate them) and route to
+   * their handler instead of the upstream, from inside the innermost
+   * `next`, so the full `toolMiddleware` pipeline still runs.
+   *
+   * Precedence: `hiddenTools` beats a local tool; a local tool beats (and
+   * shadows) an upstream tool of the same name; `passThroughTools` has no
+   * effect on a local tool, because pass-through means "forward the
+   * upstream response as-is" and a local tool has no upstream.
+   *
+   * The proxy advertises the `tools` capability when this is non-empty
+   * even if the upstream has none. A duplicate local tool name throws at
+   * {@link createProxyServer}. See ADR-0007.
+   */
+  localTools?: ReadonlyArray<LocalTool>;
+
+  /**
+   * Called after every tool call with timing and outcome data. Wire to any
+   * custom telemetry sink, or to `createOtelTelemetry` from `@mcpose/otel`
+   * for OpenTelemetry spans.
+   * A sink that throws, or whose returned promise rejects, is logged and never
+   * fails the tool call. The sink is not awaited, so a slow one does not delay
+   * the call either.
+   */
+  onTelemetry?: (event: TelemetryEvent) => unknown;
+}
+
+type ProgressToken = string | number;
+
+/**
+ * Hands one event to the telemetry sink. A sink that throws, or whose returned
+ * promise rejects, is logged here and nowhere else: the caller is already past
+ * the point where the tool call could fail, and a rejection that nobody observes
+ * ends the process on Node's default `--unhandled-rejections=throw`.
+ *
+ * The sink is called, not awaited, so a slow exporter cannot delay a tool call.
+ *
+ * `Promise.resolve` rather than an `instanceof Promise` test: a sink loaded from
+ * another realm (`node:vm`), or one handing back a non-native thenable, would
+ * fail the latter and leave its rejection unobserved all the same.
+ */
+function callTelemetrySink(
+  sink: ((event: TelemetryEvent) => unknown) | undefined,
+  event: TelemetryEvent,
+): void {
+  try {
+    Promise.resolve(sink?.(event)).catch((err: unknown) => {
+      console.error(err);
+    });
+  } catch (err) {
+    console.error(err);
+  }
+}
+
+type BackendRequestOptions = Parameters<BackendClient['listTools']>[1];
+// Structural mirror of the SDK's `RequestHandlerExtra`. The SDK declares its
+// optional members as `?: T | undefined`, so this type has to as well to stay
+// assignable under `exactOptionalPropertyTypes`.
+type ProxyRequestExtra = {
+  signal?: AbortSignal | undefined;
+  _meta?: { progressToken?: ProgressToken | undefined } | undefined;
+  sendNotification?: (notification: {
+    method: 'notifications/progress';
+    params: {
+      progressToken: ProgressToken;
+      progress: number;
+      total?: number;
+      message?: string;
+    };
+  }) => Promise<void>;
+};
+
+/**
+ * Subscribers to one backend's list-changed notifications, with the
+ * capabilities each proxy server advertises. The handlers are registered
+ * from the backend's own capabilities rather than any one subscriber's, so
+ * a backend shared between proxies that advertise different surfaces
+ * forwards every surface it has, and the fan-out filters per subscriber.
+ */
+type ListChangedBus = {
+  servers: Set<Server>;
+};
+
+type ListChangedSurface = 'tools' | 'prompts' | 'resources';
+
+const listChangedBuses = new WeakMap<BackendClient, ListChangedBus>();
+const httpProxyContext = new AsyncLocalStorage<
+  Omit<ProxyContext, 'requestId'>
+>();
+
+/**
+ * Union of every backend's capabilities, plus the ADR-0007 rule that a
+ * non-empty `localTools` advertises `tools` on its own.
+ */
+function createProxyCapabilities(
+  entries: ReadonlyArray<MeshEntry>,
+  hasLocalTools: boolean,
+): ServerCapabilities {
+  const upstreams = entries.map((entry) =>
+    entry.client.getServerCapabilities(),
+  );
+  const listChanged = (supported: boolean) =>
+    supported ? { listChanged: true } : {};
+
+  return {
+    ...(upstreams.some((u) => u?.tools) || hasLocalTools
+      ? { tools: listChanged(upstreams.some((u) => u?.tools?.listChanged)) }
+      : {}),
+    ...(upstreams.some((u) => u?.resources)
+      ? {
+          resources: listChanged(
+            upstreams.some((u) => u?.resources?.listChanged),
+          ),
+        }
+      : {}),
+    ...(upstreams.some((u) => u?.prompts)
+      ? { prompts: listChanged(upstreams.some((u) => u?.prompts?.listChanged)) }
+      : {}),
+  };
+}
+
+function createRequestOptions(
+  extra: ProxyRequestExtra = {},
+): BackendRequestOptions {
+  const progressToken = extra._meta?.progressToken;
+  // `0` and `''` are legitimate progress tokens — only undefined disables.
+  const onprogress =
+    progressToken !== undefined && extra.sendNotification
+      ? ({
+          progress,
+          total,
+          message,
+        }: {
+          progress: number;
+          total?: number | undefined;
+          message?: string | undefined;
+        }) => {
+          // A client that disconnected mid-call makes sendNotification
+          // reject; dropping the progress tick is the correct outcome.
+          void extra
+            .sendNotification?.({
+              method: 'notifications/progress',
+              params: {
+                progressToken,
+                progress,
+                ...(total === undefined ? {} : { total }),
+                ...(message === undefined ? {} : { message }),
+              },
+            })
+            .catch(() => {});
+        }
+      : undefined;
+
+  if (!extra.signal && !onprogress) return undefined;
+
+  return {
+    ...(extra.signal ? { signal: extra.signal } : {}),
+    ...(onprogress ? { onprogress } : {}),
+  };
+}
+
+/**
+ * Credential-bearing headers are stripped before headers reach
+ * `ProxyContext` (and through it, audit logs). Identity resolution reads
+ * the raw `http.IncomingMessage`, so `resolveIdentity` still sees them.
+ */
+const SENSITIVE_HEADERS: ReadonlySet<string> = new Set([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+]);
+
+function normalizeHeaders(
+  headers: http.IncomingHttpHeaders,
+): Readonly<Record<string, string>> | undefined {
+  const normalized = Object.entries(headers).reduce<Record<string, string>>(
+    (acc, [key, value]) => {
+      if (SENSITIVE_HEADERS.has(key)) return acc;
+      if (typeof value === 'string') {
+        acc[key] = value;
+        return acc;
+      }
+      if (Array.isArray(value)) {
+        acc[key] = value.join(', ');
+      }
+      return acc;
+    },
+    {},
+  );
+
+  return Object.keys(normalized).length ? normalized : undefined;
+}
+
+function getMiddlewareContext(
+  proxy: ProxyIdentity,
+  signal?: AbortSignal,
+  delegatedFrom?: Identity[],
+): ProxyContext {
+  const store = httpProxyContext.getStore();
+  return createProxyContext({
+    ...store,
+    ...(signal === undefined ? {} : { signal }),
+    // A host-stamped chain wins; an extracted one fills the field only when
+    // the host left it unset, which keeps the extraction additive (ADR-0016).
+    delegatedFrom: store?.delegatedFrom ?? delegatedFrom,
+    proxy,
+  });
+}
+
+function getRejectionReason(err: unknown): RejectionReason | undefined {
+  const reason = (err as { data?: { rejectionReason?: unknown } } | null)?.data
+    ?.rejectionReason;
+  // A reason outside the union is an ordinary failure, not a rejection (#238).
+  return isRejectionReason(reason) ? reason : undefined;
+}
+
+/**
+ * Removes `params._meta` at the proxy boundary, before the pipeline runs,
+ * so middleware sees the stripped request, can still add its own `_meta`
+ * deliberately, and audit hashes cover what is actually forwarded.
+ * Identity function when there is nothing to strip.
+ */
+function stripParamsMeta<
+  Req extends { params?: { _meta?: unknown } | undefined },
+>(req: Req): Req {
+  if (req.params === undefined || !('_meta' in req.params)) return req;
+  const { _meta: _stripped, ...params } = req.params;
+  return { ...req, params };
+}
+
+/**
+ * Removes top-level `_meta` from an upstream result at the proxy boundary,
+ * inside the innermost `next`, so middleware sees the stripped result and
+ * middleware-added `_meta` still reaches the client. Nested `_meta`
+ * (per-tool in `tools[]`, per-block in `content`) is untouched.
+ * Identity function when there is nothing to strip.
+ */
+function stripTopLevelMeta<Res extends { _meta?: unknown }>(res: Res): Res {
+  if (!('_meta' in res)) return res;
+  const { _meta: _stripped, ...rest } = res;
+  // Omit<Res, '_meta'> still satisfies Res: `_meta` is optional.
+  return rest as Res;
+}
+
+/**
+ * Validates and indexes `localTools`. Throws on a duplicate name: there is
+ * no correct way to pick one, and silently keeping the last would route
+ * calls to a handler the configuration does not obviously name.
+ */
+/**
+ * Rejects a blank proxy name at construction, like a duplicate local tool name.
+ *
+ * The name is recorded as provenance on every `ProxyContext`, audit event, and
+ * `ReplayManifest` (ADR-0012), so a blank one produces a trail that looks
+ * attributed and is not (#122). The negated check covers all three bad values
+ * at once: whitespace-only trims to `''`, and `''` and an omitted name (from a
+ * JS caller the type does not bind) are falsy already.
+ */
+function assertProxyName(name: string): void {
+  if (!name?.trim()) {
+    throw new Error(
+      `mcpose: name must be a non-empty string, got ${JSON.stringify(name)}`,
+    );
+  }
+}
+
+function buildLocalToolMap(
+  localTools: ReadonlyArray<LocalTool> | undefined,
+): Map<string, LocalTool> {
+  const localToolMap = new Map<string, LocalTool>();
+  for (const localTool of localTools ?? []) {
+    const toolName = localTool.tool.name;
+    if (localToolMap.has(toolName)) {
+      throw new Error(`mcpose: duplicate local tool name "${toolName}"`);
+    }
+    localToolMap.set(toolName, localTool);
+  }
+  return localToolMap;
+}
+
+/**
+ * The backends advertising one surface, ready to list across and to route
+ * by backend key. Only these are queried or routed to, so an otherwise-valid
+ * prefix naming a backend without the surface is unroutable rather than a
+ * call the upstream cannot serve.
+ */
+function surfaceBackends(
+  entries: ReadonlyArray<MeshEntry>,
+  surface: 'tools' | 'prompts' | 'resources',
+): {
+  entries: ReadonlyArray<MeshEntry>;
+  byKey: ReadonlyMap<string, BackendClient>;
+} {
+  const selected = entries.filter(
+    (entry) => entry.client.getServerCapabilities()?.[surface] !== undefined,
+  );
+  return {
+    entries: selected,
+    byKey: new Map(selected.map((entry) => [entry.key, entry.client] as const)),
+  };
+}
+
+/** Normalizes the `hiddenTools` option to its predicate form. */
+function toHiddenToolPredicate(
+  hiddenTools: ReadonlyArray<string> | HiddenToolPredicate | undefined,
+): HiddenToolPredicate {
+  if (typeof hiddenTools === 'function') return hiddenTools;
+  const hiddenToolSet = new Set(hiddenTools ?? []);
+  return (name) => hiddenToolSet.has(name);
+}
+
+function filterHiddenTools(
+  result: ListToolsResult,
+  isHiddenTool: HiddenToolPredicate,
+): ListToolsResult {
+  // List phase: a listed tool has no arguments, so args is undefined.
+  const tools = result.tools.filter(
+    (tool) => !isHiddenTool(tool.name, undefined),
+  );
+  return tools.length === result.tools.length ? result : { ...result, tools };
+}
+
+/**
+ * Subscribes `server` to every backend's list-changed notifications, so a
+ * mesh fans them in through the same per-backend bus a 1:1 proxy uses.
+ *
+ * Every subscriber advertises the union of its backends' surfaces, so a
+ * notification a bus can emit is always one its subscribers accept, and the
+ * fan-out needs no per-surface filter.
+ */
+function registerListChangedForwarders(
+  entries: ReadonlyArray<MeshEntry>,
+  server: Server,
+  capabilities: ServerCapabilities,
+): void {
+  const leaveBuses: Array<() => void> = [];
+
+  for (const { client } of entries) {
+    const upstream = client.getServerCapabilities() ?? {};
+    const surfaces: ReadonlyArray<ListChangedSurface> = [
+      'tools',
+      'prompts',
+      'resources',
+    ];
+    if (
+      !surfaces.some(
+        (surface) =>
+          capabilities[surface]?.listChanged === true &&
+          upstream[surface]?.listChanged === true,
+      )
+    ) {
+      continue;
+    }
+
+    let bus = listChangedBuses.get(client);
+
+    if (!bus) {
+      const servers = new Set<Server>();
+      const fanOut = async (
+        notify: (proxyServer: Server) => Promise<void>,
+      ): Promise<void> => {
+        await Promise.allSettled([...servers].map(notify));
+      };
+
+      if (upstream.tools?.listChanged) {
+        client.setNotificationHandler(ToolListChangedNotificationSchema, () =>
+          fanOut((proxyServer) => proxyServer.sendToolListChanged()),
+        );
+      }
+
+      if (upstream.prompts?.listChanged) {
+        client.setNotificationHandler(PromptListChangedNotificationSchema, () =>
+          fanOut((proxyServer) => proxyServer.sendPromptListChanged()),
+        );
+      }
+
+      if (upstream.resources?.listChanged) {
+        client.setNotificationHandler(
+          ResourceListChangedNotificationSchema,
+          () => fanOut((proxyServer) => proxyServer.sendResourceListChanged()),
+        );
+      }
+
+      bus = { servers };
+      listChangedBuses.set(client, bus);
+    }
+
+    const joined = bus;
+    joined.servers.add(server);
+
+    let active = true;
+    leaveBuses.push(() => {
+      if (!active) return;
+      active = false;
+      joined.servers.delete(server);
+      if (!joined.servers.size) listChangedBuses.delete(client);
+    });
+  }
+
+  if (leaveBuses.length === 0) return;
+
+  // Accessor instead of plain assignment: a consumer setting `server.onclose`
+  // after createProxyServer() must not clobber the bus cleanup (which would
+  // leak this server into the fan-out set forever).
+  let consumerOnClose: (() => void) | undefined;
+  Object.defineProperty(server, 'onclose', {
+    configurable: true,
+    get: () => () => {
+      for (const leaveBus of leaveBuses) leaveBus();
+      consumerOnClose?.();
+    },
+    set: (fn: (() => void) | undefined) => {
+      consumerOnClose = fn;
+    },
+  });
+}
+
+/**
+ * Creates a proxy MCP server without connecting it to a transport.
+ *
+ * Mirrors upstream tool/resource/prompt lists and routes requests through
+ * middleware pipelines. `prompts/list` is forwarded as-is; `prompts/get`
+ * runs `promptMiddleware` (ADR-0014).
+ *
+ * Uses low-level `Server` (not `McpServer`) — transparent proxying requires
+ * generic list interception; `McpServer.tool()` needs names upfront.
+ *
+ * @param backends - Connected (or mock) upstream MCP client for a 1:1 proxy,
+ * or a record of named backends for mesh mode (ADR-0013), where every
+ * upstream tool and prompt is exposed as `<backendKey>__<name>`.
+ * @param options - Middleware stacks, hidden/passthrough sets.
+ * @returns Configured {@link Server} ready to connect.
+ */
+export function createProxyServer(
+  backends: Backends,
+  options: ProxyOptions,
+): Server {
+  assertProxyName(options.name);
+  const { mesh, entries } = normalizeBackends(backends);
+  for (const { key, client } of entries) {
+    if (client.getServerCapabilities() === undefined) {
+      throw new Error(
+        `mcpose: backend${mesh ? ` "${key}"` : ''} is not connected (getServerCapabilities() returned undefined). Connect the backend before calling createProxyServer().`,
+      );
+    }
+  }
+  const backend = entries[0]!.client;
+
+  const localToolMap = buildLocalToolMap(options.localTools);
+  const toolBackends = surfaceBackends(entries, 'tools');
+  const promptBackends = surfaceBackends(entries, 'prompts');
+  const resourceBackends = surfaceBackends(entries, 'resources');
+  const upstreamHasTools = toolBackends.entries.length > 0;
+
+  const capabilities = createProxyCapabilities(entries, localToolMap.size > 0);
+  const toolPipeline = pipe(options.toolMiddleware ?? []);
+  // Pass-through tools skip transforming middleware but are still seen by
+  // observers (audit, telemetry) marked via markPassThroughObserver().
+  const passThroughToolPipeline = pipe(
+    (options.toolMiddleware ?? []).filter(isPassThroughObserver),
+  );
+  const resourcePipeline = pipe(options.resourceMiddleware ?? []);
+  const promptPipeline = pipe(options.promptMiddleware ?? []);
+  const listToolsPipeline = pipe(options.listToolsMiddleware ?? []);
+
+  const isHiddenTool = toHiddenToolPredicate(options.hiddenTools);
+  // Applied uniformly at every handler entry, pass-through included: a
+  // privacy control a per-tool option could silently switch off would be
+  // the same false-confidence failure as the dispatcher bypass (ADR-0006).
+  const stripMeta = options.stripRequestMeta !== false;
+  const stripRequest = <
+    Req extends { params?: { _meta?: unknown } | undefined },
+  >(
+    req: Req,
+  ): Req => (stripMeta ? stripParamsMeta(req) : req);
+  // The response-direction mirror: applied to every upstream result at the
+  // innermost `next`, never to local tool results (they have no upstream).
+  const stripResMeta = options.stripResultMeta !== false;
+  const stripResult = <Res extends { _meta?: unknown }>(res: Res): Res =>
+    stripResMeta ? stripTopLevelMeta(res) : res;
+  const passThroughToolSet = new Set(options.passThroughTools ?? []);
+  const hiddenResourceSet = new Set(options.hiddenResources ?? []);
+  const passThroughResourceSet = new Set(options.passThroughResources ?? []);
+
+  // Stamped onto every ProxyContext so middleware and the audit trail can
+  // attribute events to this proxy instance (#85, ADR-0012). Frozen because
+  // the one object is aliased into the SDK Server, every context, and every
+  // audit event: a middleware mutating it would rewrite provenance already
+  // recorded elsewhere.
+  const proxyIdentity: ProxyIdentity = Object.freeze({
+    name: options.name,
+    version: options.version ?? VERSION,
+  });
+
+  const server = new Server(proxyIdentity, { capabilities });
+
+  registerListChangedForwarders(entries, server, capabilities);
+
+  /**
+   * Reports a backend that dropped out of a mesh list. Failure isolation is
+   * only safe if the gap is visible, and a throwing sink must not turn a
+   * degraded list into a failed one.
+   */
+  const reportDegraded = (
+    context: ProxyContext,
+    backendKey: string,
+    method: BackendDegradedTelemetryEvent['method'],
+    error: unknown,
+  ): void => {
+    callTelemetrySink(options.onTelemetry, {
+      type: 'backend_degraded',
+      requestId: context.requestId,
+      ...(context.sessionId === undefined
+        ? {}
+        : { sessionId: context.sessionId }),
+      backend: backendKey,
+      method,
+      error,
+      ...(context.identity === undefined ? {} : { identity: context.identity }),
+      ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
+    });
+  };
+
+  // ── Tool handlers ──────────────────────────────────────────────────────────
+
+  if (capabilities.tools) {
+    server.setRequestHandler(ListToolsRequestSchema, async (rawReq, extra) => {
+      // Read the chain before the strip, or it never survives a chained
+      // proxy (ADR-0016, the ADR-0011 boundary-ordering constraint).
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const req = stripRequest(rawReq);
+      const requestOptions = createRequestOptions(extra);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      const delegationError = wireError ?? detectDelegationLoop(context);
+      // Local tools are overlaid inside the innermost `next`, so
+      // listToolsMiddleware sees them exactly as it sees upstream tools.
+      // They are added to the first page only (no cursor), so a paginating
+      // client sees each local tool once; the shadow filter runs on every
+      // page, so the client sees exactly one entry per name.
+      const result = await listToolsPipeline(
+        req,
+        async (currentReq) => {
+          // Thrown inside the pipeline, so observing middleware records the
+          // attempt rather than seeing a call that never happened.
+          if (delegationError !== undefined) throw delegationError;
+          const upstreamResult: ListToolsResult = mesh
+            ? {
+                // A mesh has no cursor that means "page 3 of the union", so
+                // every backend is drained into one complete page.
+                tools: await listAcrossMesh(
+                  toolBackends.entries,
+                  async (client, cursor) => {
+                    const page = stripResult(
+                      await client.listTools(
+                        attachDelegationMeta(
+                          cursor === undefined ? {} : { cursor },
+                          context,
+                        ),
+                        requestOptions,
+                      ),
+                    );
+                    return { items: page.tools, nextCursor: page.nextCursor };
+                  },
+                  (key, error) =>
+                    reportDegraded(context, key, 'tools/list', error),
+                  namespaceName,
+                ),
+              }
+            : upstreamHasTools
+              ? stripResult(
+                  await backend.listTools(
+                    attachDelegationMeta(currentReq.params, context),
+                    requestOptions,
+                  ),
+                )
+              : { tools: [] };
+          if (!localToolMap.size) {
+            return filterHiddenTools(upstreamResult, isHiddenTool);
+          }
+          const tools = [
+            ...upstreamResult.tools.filter((t) => !localToolMap.has(t.name)),
+            // A mesh response is always the only page, so local tools belong
+            // on it whatever cursor the client sent.
+            ...(mesh || currentReq.params?.cursor === undefined
+              ? [...localToolMap.values()].map((lt) => lt.tool)
+              : []),
+          ];
+          return filterHiddenTools({ ...upstreamResult, tools }, isHiddenTool);
+        },
+        context,
+      );
+
+      return filterHiddenTools(result, isHiddenTool);
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (rawReq, extra) => {
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const req = stripRequest(rawReq);
+      const name = req.params.name;
+      const requestOptions = createRequestOptions(extra);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      const delegationError = wireError ?? detectDelegationLoop(context);
+      const start = performance.now();
+
+      const emitTelemetry = (
+        outcome: ToolCallTelemetryEvent['outcome'],
+        rejectionReason?: RejectionReason,
+      ) => {
+        callTelemetrySink(options.onTelemetry, {
+          type: 'tool_call',
+          requestId: context.requestId,
+          ...(context.sessionId === undefined
+            ? {}
+            : { sessionId: context.sessionId }),
+          tool: name,
+          duration_ms: Math.round(performance.now() - start),
+          outcome,
+          ...(rejectionReason === undefined ? {} : { rejectionReason }),
+          ...(context.identity === undefined
+            ? {}
+            : { identity: context.identity }),
+          ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
+        });
+      };
+
+      // Hidden beats pass-through. The rejection is thrown by the innermost
+      // `next` INSIDE the pipeline so middleware (audit) observes it in-chain;
+      // the backend is never called for hidden tools.
+      // Call phase: args is always an object, empty when the client sent
+      // none, so a dispatcher-aware predicate can fail closed on it.
+      const isHidden = isHiddenTool(name, req.params.arguments ?? {});
+      // Hidden beats local; local beats upstream; pass-through never
+      // applies to a local tool (it has no upstream response to forward).
+      const localTool = isHidden ? undefined : localToolMap.get(name);
+      const pipeline =
+        !isHidden && localTool === undefined && passThroughToolSet.has(name)
+          ? passThroughToolPipeline
+          : toolPipeline;
+      // The return type is annotated on the binding rather than on the arrow:
+      // Babel, which Stryker uses to instrument this file for mutation testing,
+      // cannot parse an async arrow carrying a return type inside a conditional.
+      const callBackend: (
+        r: CallToolRequest,
+      ) => Promise<CompatibilityCallToolResult> = isHidden
+        ? async () => {
+            throw rejectionMcpError(
+              'TOOL_HIDDEN',
+              ErrorCode.MethodNotFound,
+              `Tool not found: ${name}`,
+            );
+          }
+        : localTool !== undefined
+          ? (r) => localTool.handler(r.params, context)
+          : mesh
+            ? async (r) => {
+                // Routed at the innermost `next` from the post-pipeline name,
+                // so middleware can re-route a call deliberately.
+                const routed = routeNamespaced(
+                  r.params.name,
+                  toolBackends.byKey,
+                );
+                if (routed === undefined) {
+                  throw rejectionMcpError(
+                    'BACKEND_UNROUTABLE',
+                    ErrorCode.MethodNotFound,
+                    `Tool not found: ${r.params.name} — a mesh exposes tools as "<backendKey>__<tool>"`,
+                  );
+                }
+                return stripResult(
+                  await routed.client.callTool(
+                    attachDelegationMeta(
+                      { ...r.params, name: routed.name },
+                      context,
+                    ),
+                    undefined,
+                    requestOptions,
+                  ),
+                );
+              }
+            : upstreamHasTools
+              ? async (r) =>
+                  stripResult(
+                    await backend.callTool(
+                      attachDelegationMeta(r.params, context),
+                      undefined,
+                      requestOptions,
+                    ),
+                  )
+              : async () => {
+                  // Tools-less upstream: reject inside the pipeline rather
+                  // than forwarding to an upstream that cannot serve it.
+                  throw new McpError(
+                    ErrorCode.MethodNotFound,
+                    `Tool not found: ${name}`,
+                  );
+                };
+
+      try {
+        // A malformed chain replaces the innermost `next` rather than
+        // rejecting at the boundary, so the pipeline observes it, and it is
+        // decided before the tool is: the answer says nothing about the tool.
+        const result = await pipeline(
+          req,
+          delegationError === undefined
+            ? callBackend
+            : () => Promise.reject(delegationError),
+          context,
+        );
+        // MCP signals tool-level failures in-band via isError, not by throwing.
+        // Three shapes reach here, and `hasToolContent` alone cannot tell them
+        // apart because it answers false for two of them:
+        //
+        //   - a CallToolResult: judge it by `isError`;
+        //   - the legacy `{ toolResult }` shape (protocol 2024-10-07): a valid
+        //     result with no `.content`, so `mapToolResult` passes it through —
+        //     a success;
+        //   - nothing at all, from a local tool with a missing `return` or a
+        //     middleware that dropped the result: the call produced no result,
+        //     so it is not a success.
+        //
+        // A result-less call used to reach the `catch` as a TypeError from
+        // `hasToolContent` and be recorded as an error; now that the guard
+        // answers false instead of throwing, the shape has to be distinguished
+        // here or a `&&` would report it as a clean one.
+        const isResultless =
+          result === null || result === undefined || typeof result !== 'object';
+        emitTelemetry(
+          isResultless
+            ? 'error'
+            : hasToolContent(result) && result.isError === true
+              ? 'error'
+              : 'success',
+        );
+        return result;
+      } catch (err) {
+        const reason = getRejectionReason(err);
+        if (reason === undefined) emitTelemetry('error');
+        else emitTelemetry('rejected', reason);
+        throw err;
+      }
+    });
+  }
+
+  // ── Resource handlers ──────────────────────────────────────────────────────
+
+  if (capabilities.resources) {
+    server.setRequestHandler(
+      ListResourcesRequestSchema,
+      async (rawReq, extra) => {
+        const { chain, error: wireError } = readInboundDelegation(rawReq);
+        const context = getMiddlewareContext(
+          proxyIdentity,
+          extra.signal,
+          chain,
+        );
+        const delegationError = wireError ?? detectDelegationLoop(context);
+        // `resources/list` runs no pipeline, so there is no observer to
+        // record the attempt: the rejection is thrown here instead.
+        if (delegationError !== undefined) throw delegationError;
+        const requestOptions = createRequestOptions(extra);
+        const result = mesh
+          ? {
+              // Each URI is exposed as `mcpose://<key>/<uri>` (ADR-0022), so
+              // two backends serving the same URI never collide.
+              resources: await listAcrossMesh(
+                resourceBackends.entries,
+                async (client, cursor) => {
+                  const page = stripResult(
+                    await client.listResources(
+                      attachDelegationMeta(
+                        cursor === undefined ? {} : { cursor },
+                        context,
+                      ),
+                      requestOptions,
+                    ),
+                  );
+                  return { items: page.resources, nextCursor: page.nextCursor };
+                },
+                (key, error) =>
+                  reportDegraded(context, key, 'resources/list', error),
+                namespaceUri,
+              ),
+            }
+          : stripResult(
+              await backend.listResources(
+                attachDelegationMeta(stripRequest(rawReq).params, context),
+                requestOptions,
+              ),
+            );
+        if (!hiddenResourceSet.size) return result;
+        return {
+          ...result,
+          resources: result.resources.filter(
+            (r) => !hiddenResourceSet.has(r.uri),
+          ),
+        };
+      },
+    );
+
+    server.setRequestHandler(ReadResourceRequestSchema, (rawReq, extra) => {
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const req = stripRequest(rawReq);
+      const uri = req.params.uri;
+      const requestOptions = createRequestOptions(extra);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      const delegationError = wireError ?? detectDelegationLoop(context);
+
+      if (hiddenResourceSet.has(uri)) {
+        throw rejectionMcpError(
+          'RESOURCE_HIDDEN',
+          ErrorCode.InvalidRequest,
+          `Resource not found: ${uri}`,
+        );
+      }
+      // In mesh mode the exposed URI is unwrapped to a backend and its own
+      // URI; an unwrappable one is rejected loudly, with no lookup of which
+      // backend listed it (ADR-0022). Resolved from the post-pipeline params
+      // so middleware can re-route a read deliberately.
+      const readUpstream = (
+        params: ReadResourceRequest['params'],
+      ): Promise<ReadResourceResult> => {
+        if (delegationError !== undefined) throw delegationError;
+        if (!mesh) {
+          return backend
+            .readResource(attachDelegationMeta(params, context), requestOptions)
+            .then(stripResult);
+        }
+        const routed = routeResourceUri(params.uri, resourceBackends.byKey);
+        if (routed === undefined) {
+          throw rejectionMcpError(
+            'BACKEND_UNROUTABLE',
+            ErrorCode.InvalidRequest,
+            `Resource not found: ${params.uri} — a mesh exposes resources as "mcpose://<backendKey>/<uri>"`,
+          );
+        }
+        return routed.client
+          .readResource(
+            attachDelegationMeta({ ...params, uri: routed.uri }, context),
+            requestOptions,
+          )
+          .then(stripResult);
+      };
+
+      if (passThroughResourceSet.has(uri)) {
+        // A pass-through resource runs no pipeline at all, so as with
+        // `resources/list` the rejection is thrown here.
+        return readUpstream(req.params);
+      }
+      return resourcePipeline(req, (r) => readUpstream(r.params), context);
+    });
+  }
+
+  // ── Prompt handlers ───────────────────────────────────────────────────────
+  // `prompts/get` runs the promptMiddleware pipeline; `prompts/list` is still
+  // pass-through (ADR-0014).
+
+  if (capabilities.prompts && mesh) {
+    // Prompt names are plain strings, so they namespace and route exactly
+    // like tool names (ADR-0013).
+    server.setRequestHandler(
+      ListPromptsRequestSchema,
+      async (rawReq, extra) => {
+        const { chain, error: wireError } = readInboundDelegation(rawReq);
+        const requestOptions = createRequestOptions(extra);
+        const context = getMiddlewareContext(
+          proxyIdentity,
+          extra.signal,
+          chain,
+        );
+        // No pipeline here either, so the rejection is thrown at the handler.
+        const delegationError = wireError ?? detectDelegationLoop(context);
+        if (delegationError !== undefined) throw delegationError;
+        return {
+          prompts: await listAcrossMesh(
+            promptBackends.entries,
+            async (client, cursor) => {
+              const page = stripResult(
+                await client.listPrompts(
+                  attachDelegationMeta(
+                    cursor === undefined ? {} : { cursor },
+                    context,
+                  ),
+                  requestOptions,
+                ),
+              );
+              return { items: page.prompts, nextCursor: page.nextCursor };
+            },
+            (key, error) => reportDegraded(context, key, 'prompts/list', error),
+            namespaceName,
+          ),
+        };
+      },
+    );
+
+    server.setRequestHandler(GetPromptRequestSchema, (rawReq, extra) => {
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const req = stripRequest(rawReq);
+      const requestOptions = createRequestOptions(extra);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      const delegationError = wireError ?? detectDelegationLoop(context);
+      // Routed at the innermost `next` from the post-pipeline name, so the
+      // rejection is thrown in-chain and middleware (audit) observes it.
+      return promptPipeline(
+        req,
+        async (r) => {
+          if (delegationError !== undefined) throw delegationError;
+          const routed = routeNamespaced(r.params.name, promptBackends.byKey);
+          if (routed === undefined) {
+            throw rejectionMcpError(
+              'BACKEND_UNROUTABLE',
+              ErrorCode.MethodNotFound,
+              `Prompt not found: ${r.params.name} — a mesh exposes prompts as "<backendKey>__<prompt>"`,
+            );
+          }
+          return stripResult(
+            await routed.client.getPrompt(
+              attachDelegationMeta({ ...r.params, name: routed.name }, context),
+              requestOptions,
+            ),
+          );
+        },
+        context,
+      );
+    });
+  } else if (capabilities.prompts) {
+    server.setRequestHandler(ListPromptsRequestSchema, (rawReq, extra) => {
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      // No pipeline here either, so the rejection is thrown at the handler.
+      const delegationError = wireError ?? detectDelegationLoop(context);
+      if (delegationError !== undefined) throw delegationError;
+      return backend
+        .listPrompts(
+          attachDelegationMeta(stripRequest(rawReq).params, context),
+          createRequestOptions(extra),
+        )
+        .then(stripResult);
+    });
+
+    server.setRequestHandler(GetPromptRequestSchema, (rawReq, extra) => {
+      const { chain, error: wireError } = readInboundDelegation(rawReq);
+      const requestOptions = createRequestOptions(extra);
+      const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+      const delegationError = wireError ?? detectDelegationLoop(context);
+      return promptPipeline(
+        stripRequest(rawReq),
+        async (r) => {
+          if (delegationError !== undefined) throw delegationError;
+          return stripResult(
+            await backend.getPrompt(
+              attachDelegationMeta(r.params, context),
+              requestOptions,
+            ),
+          );
+        },
+        context,
+      );
+    });
+  }
+
+  return server;
+}
+
+/**
+ * Starts the proxy on stdio.
+ * Calls {@link createProxyServer} then connects to `StdioServerTransport`.
+ * Use `createProxyServer` directly for testable access to the server.
+ */
+export async function startProxy(
+  backends: Backends,
+  options: ProxyOptions,
+): Promise<void> {
+  const server = createProxyServer(backends, options);
+  await server.connect(new StdioServerTransport());
+}
+
+/**
+ * Enforces `maxBodyBytes`.
+ *
+ * Fast path: a declared `Content-Length` over the limit is rejected before
+ * any body is read. Chunked/streamed bodies are counted as they arrive.
+ *
+ * @returns `true` when the request was already rejected (caller must stop).
+ */
+function applyBodySizeLimit(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  maxBodyBytes: number,
+): boolean {
+  const reject413 = (): void => {
+    if (!res.headersSent) {
+      res.writeHead(413, { 'content-type': 'application/json' }).end(
+        JSON.stringify({
+          error: {
+            message: 'Request body too large',
+            data: { rejectionReason: 'BODY_LIMIT' },
+          },
+        }),
+      );
+    }
+  };
+
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > maxBodyBytes) {
+    reject413();
+    req.destroy();
+    return true;
+  }
+
+  let total = 0;
+  const originalPush = req.push.bind(req);
+  (req as unknown as { push: typeof req.push }).push = (
+    chunk: Buffer | string | null,
+    enc?: BufferEncoding,
+  ): boolean => {
+    const chunkBytes =
+      chunk === null
+        ? 0
+        : typeof chunk === 'string'
+          ? Buffer.byteLength(chunk, enc)
+          : chunk.length;
+    if (chunk !== null && total + chunkBytes > maxBodyBytes) {
+      reject413();
+      if (res.headersSent) {
+        // Too late for a clean 413 — sever the connection instead of
+        // leaving the client on a hung socket.
+        res.destroy();
+      } else {
+        // Mute the response for downstream writers (the SDK transport will
+        // observe the destroyed request and try to send its own error).
+        const muted = res as unknown as Record<string, unknown>;
+        muted.writeHead = () => res;
+        muted.write = () => true;
+        muted.end = () => res;
+      }
+      req.destroy(new Error('Request body too large'));
+      return false;
+    }
+    total += chunkBytes;
+    return originalPush(chunk, enc);
+  };
+  return false;
+}
+
+/**
+ * True for bind addresses only reachable from the local machine.
+ * `127.` catches the whole 127.0.0.0/8 block Node can bind.
+ */
+function isLoopbackHost(host: string): boolean {
+  return (
+    host === 'localhost' ||
+    host === '::1' ||
+    host === '::ffff:127.0.0.1' ||
+    host.startsWith('127.')
+  );
+}
+
+const MAX_NODE_TIMER_DELAY_MS = 2 ** 31 - 1;
+
+/**
+ * Starts the proxy over Streamable HTTP with stateful sessions.
+ *
+ * Sessions keyed by `mcp-session-id`. Upstream notifications fanned out to
+ * all active sessions via their GET SSE stream. Dropped connections can
+ * replay missed notifications via the built-in in-memory EventStore (or a
+ * custom persistent store for multi-instance deployments).
+ *
+ * @returns Promise resolving to the listening `http.Server` (or `https.Server`
+ * when `tlsOptions` is supplied).
+ */
+export function startHttpProxy(
+  backends: Backends,
+  options: ProxyOptions,
+  httpOptions: HttpProxyOptions = {},
+): Promise<http.Server> {
+  // Sessions build their proxy server lazily, so surface configuration
+  // errors (a blank name, duplicate local tool names, invalid backend keys)
+  // at startup, not on first initialize.
+  assertProxyName(options.name);
+  buildLocalToolMap(options.localTools);
+  normalizeBackends(backends);
+
+  const mcpPath = httpOptions.path ?? '/mcp';
+  const port = httpOptions.port ?? 3000;
+  const host = httpOptions.host ?? '127.0.0.1';
+  const loopback = isLoopbackHost(host);
+  const dnsRebindingProtection =
+    httpOptions.enableDnsRebindingProtection ?? loopback;
+  // Bounded by default (#107): unlimited sessions that never expire are a
+  // memory exhaustion path for any client that can initialize. `Infinity`
+  // is the opt-out for both; `maxSessions: 0` already means "reject every
+  // session", so it cannot double as one. The `!(x >= n)` form also
+  // rejects NaN, which a plain `x < n` would let through.
+  const maxSessions = httpOptions.maxSessions ?? 1000;
+  const sessionTtlMs = httpOptions.sessionTtlMs ?? 30 * 60 * 1000;
+  if (!(maxSessions >= 0)) {
+    throw new Error(
+      `mcpose: maxSessions must be >= 0 or Infinity, got ${String(httpOptions.maxSessions)}`,
+    );
+  }
+  if (!(sessionTtlMs > 0)) {
+    throw new Error(
+      `mcpose: sessionTtlMs must be > 0 or Infinity, got ${String(httpOptions.sessionTtlMs)}`,
+    );
+  }
+  if (Number.isFinite(sessionTtlMs) && sessionTtlMs > MAX_NODE_TIMER_DELAY_MS) {
+    throw new Error(
+      `mcpose: sessionTtlMs must be <= ${MAX_NODE_TIMER_DELAY_MS} or Infinity, got ${String(httpOptions.sessionTtlMs)}`,
+    );
+  }
+  // Resolved once, like the two limits above, so a bad value fails at startup
+  // instead of quietly gating nothing. A `NaN` cap compares false against both
+  // the declared `Content-Length` and the running byte count, so a body far
+  // larger than the configured limit passes this layer untouched.
+  // `Number(process.env.MAX_BODY_BYTES)` is the ordinary way a host wires an
+  // operator-supplied limit in, and it is NaN when the key is unset or
+  // misspelled; #264 rejected a non-finite `budget.maxCallsPerSession` for
+  // exactly this reason. `Infinity` opts out, and `0`, like `maxSessions: 0`,
+  // keeps its literal meaning instead of doubling as one.
+  const maxBodyBytes = httpOptions.maxBodyBytes ?? 4 * 1024 * 1024;
+  if (!(maxBodyBytes >= 0)) {
+    throw new Error(
+      `mcpose: maxBodyBytes must be >= 0 or Infinity, got ${String(httpOptions.maxBodyBytes)}`,
+    );
+  }
+  // Filled in once the server is listening (the real port is only known
+  // then); sessions are only created after that. The SDK transport
+  // validates Host/Origin only against a non-empty list, so an enabled flag
+  // without a list would be an inert control — see #74.
+  let derivedAllowedHosts: string[] | undefined;
+  let derivedAllowedOrigins: string[] | undefined;
+  const eventStore =
+    httpOptions.eventStore === null
+      ? undefined
+      : (httpOptions.eventStore ?? createInMemoryEventStore());
+  const registry = httpOptions.sessionRegistry;
+
+  interface Session {
+    transport: StreamableHTTPServerTransport;
+    proxyServer: Server;
+    identity?: Identity;
+    ttlTimer?: NodeJS.Timeout;
+  }
+  // session ID → live session held by this instance
+  const sessions = new Map<string, Session>();
+
+  // Sessions being initialized or resumed (identity resolution or registry
+  // lookup in flight) — counted so concurrent admissions cannot overshoot
+  // maxSessions.
+  let pendingSessions = 0;
+
+  const reportError = (err: unknown): void => {
+    // `onError` is observability, so its own failure must change nothing, the
+    // same containment `onAuditError` applies to `@mcpose/audit`'s reporter
+    // (#172) and `createConsentMiddleware` applies to its resolver hook. Left
+    // unguarded, a throwing reporter replaced the 401 this file documents for
+    // a failed auth hook with a 500, aborted `destroySession` before it closed
+    // the proxy server, and threw out of the `server.on('error')` handler
+    // that exists precisely so a post-listen error does not crash the process.
+    // An async reporter that rejects after its first await escapes the same
+    // guard one tick later (#245): nobody observes the rejection, and Node's
+    // default --unhandled-rejections=throw ends the process, so the returned
+    // promise is adopted here too.
+    try {
+      Promise.resolve((httpOptions.onError ?? console.error)(err)).catch(() => {
+        // Nothing left to report it to.
+      });
+    } catch {
+      // Nothing left to report it to.
+    }
+  };
+
+  /**
+   * Single teardown path for every way a session can end: client DELETE,
+   * TTL expiry, and server shutdown. Clears the TTL timer, drops the shared
+   * record unless the session is meant to outlive this process, fires and
+   * awaits `onSessionClosed` (guarded — a throwing or rejecting hook must not
+   * break teardown), and closes the proxy server so it leaves the listChanged
+   * fan-out bus. Idempotent: a second call for the same id is a no-op.
+   */
+  const destroySession = async (
+    id: string,
+    keepRecord = false,
+  ): Promise<void> => {
+    const session = sessions.get(id);
+    if (!session) return;
+    sessions.delete(id);
+    if (session.ttlTimer !== undefined) clearTimeout(session.ttlTimer);
+    if (registry && !keepRecord) await registry.delete(id).catch(reportError);
+    try {
+      await httpOptions.onSessionClosed?.(id);
+    } catch (err) {
+      reportError(err);
+    }
+    await session.proxyServer.close().catch(reportError);
+  };
+
+  /**
+   * Takes a session live on this instance. `expiresAt` is the session's
+   * deadline fixed at creation, so a resumed session gets the remaining
+   * lifetime rather than a fresh TTL; `undefined` means it never expires.
+   */
+  const admitSession = (
+    id: string,
+    transport: StreamableHTTPServerTransport,
+    proxyServer: Server,
+    identity: Identity | undefined,
+    expiresAt: number | undefined,
+  ): void => {
+    let ttlTimer: NodeJS.Timeout | undefined;
+    if (expiresAt !== undefined) {
+      // A record from a proxy with a longer TTL may still exceed Node's
+      // timer ceiling; clamping only makes that timer fire early and
+      // re-check nothing, since the session is then simply closed.
+      const remaining = Math.min(
+        Math.max(expiresAt - Date.now(), 0),
+        MAX_NODE_TIMER_DELAY_MS,
+      );
+      ttlTimer = setTimeout(() => {
+        void destroySession(id);
+      }, remaining);
+      ttlTimer.unref();
+    }
+    sessions.set(id, {
+      transport,
+      proxyServer,
+      ...(identity === undefined ? {} : { identity }),
+      ...(ttlTimer === undefined ? {} : { ttlTimer }),
+    });
+  };
+
+  const sessionLimitBody = JSON.stringify({
+    error: {
+      message: 'Session limit reached',
+      data: { rejectionReason: 'SESSION_LIMIT' },
+    },
+  });
+
+  // Builds the transport for one session. The id is fixed before the
+  // transport exists so the event store can be scoped to it: stream ids are
+  // namespaced per session (#154).
+  const createTransport = (
+    sessionId: string,
+    onsessioninitialized: (id: string) => void | Promise<void>,
+  ): StreamableHTTPServerTransport => {
+    // An explicit list is used verbatim; the derived loopback list only
+    // fills the gap so the default actually validates something.
+    const allowedHosts = httpOptions.allowedHosts ?? derivedAllowedHosts;
+    const allowedOrigins = httpOptions.allowedOrigins ?? derivedAllowedOrigins;
+    return new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => sessionId,
+      ...(eventStore
+        ? { eventStore: scopeEventStore(eventStore, sessionId) }
+        : {}),
+      ...(allowedHosts ? { allowedHosts } : {}),
+      ...(allowedOrigins ? { allowedOrigins } : {}),
+      enableDnsRebindingProtection: dnsRebindingProtection,
+      onsessioninitialized,
+      onsessionclosed: (id) => {
+        void destroySession(id);
+      },
+    });
+  };
+
+  // Resumes in flight, so concurrent requests for one unknown id build one
+  // session between them instead of one each.
+  const resuming = new Map<
+    string,
+    Promise<Session | { status: number; body: string } | undefined>
+  >();
+
+  /**
+   * Rebuilds a session this instance does not hold from its shared record:
+   * `undefined` when the registry has no live record for it, or the SDK's
+   * own rejection when the replayed initialize did not bring the transport
+   * up (a failed Host or Origin check, which the real request would fail
+   * identically).
+   */
+  const resumeSession = (
+    id: string,
+    sharedRegistry: SessionRegistry,
+    req: http.IncomingMessage,
+  ): Promise<Session | { status: number; body: string } | undefined> => {
+    const inflight = resuming.get(id);
+    if (inflight) return inflight;
+    pendingSessions += 1;
+    const attempt = (async () => {
+      const record = await sharedRegistry.get(id);
+      if (
+        record === undefined ||
+        (record.expiresAt !== undefined && record.expiresAt <= Date.now())
+      ) {
+        return undefined;
+      }
+      // The pending slot is already counted, so this instance can be full
+      // by exactly one.
+      if (sessions.size + pendingSessions > maxSessions) {
+        return { status: 503, body: sessionLimitBody };
+      }
+      const proxyServer = createProxyServer(backends, options);
+      const transport = createTransport(id, (sid) => {
+        admitSession(
+          sid,
+          transport,
+          proxyServer,
+          record.identity,
+          record.expiresAt,
+        );
+      });
+      try {
+        await proxyServer.connect(transport as Transport);
+        const answer = await replayInitialize(transport, record.initialize, {
+          ...(req.headers.host === undefined ? {} : { host: req.headers.host }),
+          ...(req.headers.origin === undefined
+            ? {}
+            : { origin: req.headers.origin }),
+        });
+        return sessions.get(id) ?? answer;
+      } finally {
+        // Not admitted, whether the SDK refused the replay or threw: close
+        // the orphaned proxy server before it leaks (memory + listChanged
+        // fan-out), as the fresh-session path does.
+        if (!sessions.has(id)) void proxyServer.close().catch(reportError);
+      }
+    })().finally(() => {
+      resuming.delete(id);
+      pendingSessions -= 1;
+    });
+    resuming.set(id, attempt);
+    return attempt;
+  };
+
+  const requestHandler = (
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ) => {
+    const handle = async () => {
+      if (httpOptions.onRequest !== undefined) {
+        let allowed: boolean;
+        try {
+          allowed = await httpOptions.onRequest(req, res);
+        } catch (err) {
+          // Failing closed is the right answer for the caller; it is not an
+          // answer for the operator, whose only signal would otherwise be a
+          // stream of 401s. Same containment the session teardown path
+          // already uses for a throwing `onSessionClosed`.
+          reportError(err);
+          if (!res.headersSent) res.writeHead(401).end();
+          return;
+        }
+        if (!allowed) return;
+      }
+
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const method = req.method ?? '';
+
+      if (
+        url.pathname !== mcpPath ||
+        !['GET', 'POST', 'DELETE'].includes(method)
+      ) {
+        res.writeHead(404).end();
+        return;
+      }
+
+      if (method === 'POST') {
+        const rejected = applyBodySizeLimit(req, res, maxBodyBytes);
+        if (rejected) return;
+      }
+
+      const sessionId = req.headers['mcp-session-id'];
+      const headers = normalizeHeaders(req.headers);
+
+      if (typeof sessionId === 'string') {
+        // Route to an existing session, resuming it from the shared registry
+        // if another process created it — stamp its resolved identity into
+        // context.
+        const session =
+          sessions.get(sessionId) ??
+          (registry
+            ? await resumeSession(sessionId, registry, req)
+            : undefined);
+        if (!session) {
+          res.writeHead(404).end();
+          return;
+        }
+        if ('status' in session) {
+          res
+            .writeHead(session.status, { 'content-type': 'application/json' })
+            .end(session.body);
+          return;
+        }
+        if (httpOptions.validateSession !== undefined) {
+          let valid: boolean;
+          try {
+            valid = await httpOptions.validateSession(req, {
+              sessionId,
+              ...(session.identity === undefined
+                ? {}
+                : { identity: session.identity }),
+            });
+          } catch (err) {
+            reportError(err);
+            valid = false;
+          }
+          if (!valid) {
+            if (!res.headersSent) res.writeHead(401).end();
+            return;
+          }
+        }
+        const requestContext: Omit<ProxyContext, 'requestId'> = {
+          transport: 'http',
+          sessionId,
+          ...(headers === undefined ? {} : { headers }),
+          ...(session.identity === undefined
+            ? {}
+            : { identity: session.identity }),
+        };
+        await httpProxyContext.run(requestContext, () =>
+          session.transport.handleRequest(req, res),
+        );
+      } else {
+        // New session — only an initialize POST may create one. A
+        // session-less GET/DELETE can never initialize, so reject it
+        // before constructing a Server/transport (which would otherwise
+        // leak into the listChanged fan-out bus).
+        if (method !== 'POST') {
+          res.writeHead(400, { 'content-type': 'application/json' }).end(
+            JSON.stringify({
+              jsonrpc: '2.0',
+              error: {
+                code: -32000,
+                message: 'Bad Request: no valid session ID provided',
+              },
+              id: null,
+            }),
+          );
+          return;
+        }
+
+        // Count this initialize as pending so concurrent initializes
+        // cannot overshoot maxSessions while identity resolution awaits.
+        if (sessions.size + pendingSessions >= maxSessions) {
+          res
+            .writeHead(503, { 'content-type': 'application/json' })
+            .end(sessionLimitBody);
+          return;
+        }
+        pendingSessions += 1;
+
+        // The shared record carries the client's initialize params, and the
+        // SDK owns parsing the body, so tap the bytes as they arrive rather
+        // than reading the stream out from under it. The same seam the body
+        // limit uses.
+        const bodyChunks: Buffer[] = [];
+        if (registry) {
+          const push = req.push.bind(req);
+          (req as unknown as { push: typeof req.push }).push = (
+            chunk: Buffer | string | null,
+            enc?: BufferEncoding,
+          ): boolean => {
+            if (chunk !== null) {
+              bodyChunks.push(
+                typeof chunk === 'string' ? Buffer.from(chunk, enc) : chunk,
+              );
+            }
+            return push(chunk, enc);
+          };
+        }
+
+        try {
+          // Resolve identity once for the lifetime of this session
+          let identity: Identity | undefined;
+          if (httpOptions.resolveIdentity !== undefined) {
+            try {
+              identity = await httpOptions.resolveIdentity(req);
+            } catch (err) {
+              reportError(err);
+              if (!res.headersSent) res.writeHead(401).end();
+              return;
+            }
+          }
+
+          const proxyServer = createProxyServer(backends, options);
+          const sessionId = randomUUID();
+          const transport = createTransport(sessionId, async (id) => {
+            // The deadline is fixed here and travels with the record, so a
+            // resume elsewhere inherits what is left of it. Infinity opts
+            // out; setTimeout would clamp it to 1ms.
+            const expiresAt = Number.isFinite(sessionTtlMs)
+              ? Date.now() + sessionTtlMs
+              : undefined;
+            // The SDK awaits this hook before it answers, so the record is
+            // durable before the client can present the id anywhere. A
+            // throw here becomes the SDK's 400 with the error text in the
+            // body, so the real cause goes to onError and the client gets a
+            // message that names nothing about the backing store.
+            if (registry) {
+              try {
+                await registry.set(id, {
+                  initialize: initializeParamsOf(
+                    Buffer.concat(bodyChunks).toString(),
+                  ),
+                  ...(identity === undefined ? {} : { identity }),
+                  ...(expiresAt === undefined ? {} : { expiresAt }),
+                });
+              } catch (err) {
+                reportError(err);
+                throw new Error('mcpose: session registry unavailable');
+              }
+            }
+            admitSession(id, transport, proxyServer, identity, expiresAt);
+          });
+
+          const requestContext: Omit<ProxyContext, 'requestId'> = {
+            transport: 'http',
+            ...(headers === undefined ? {} : { headers }),
+            ...(identity === undefined ? {} : { identity }),
+          };
+          // See backendClient.ts: the SDK's transports are not assignable to
+          // its own `Transport` interface under `exactOptionalPropertyTypes`
+          // (here `onclose?: () => void` vs `onclose: (() => void) | undefined`).
+          await proxyServer.connect(transport as Transport);
+          try {
+            await httpProxyContext.run(requestContext, () =>
+              transport.handleRequest(req, res),
+            );
+          } finally {
+            // No session came up — a non-initialize body the transport
+            // rejected, or a registry that refused the record — so close the
+            // orphaned proxy server before it leaks (memory + listChanged
+            // fan-out).
+            if (!sessions.has(sessionId)) {
+              void proxyServer.close().catch(reportError);
+            }
+          }
+        } finally {
+          pendingSessions -= 1;
+        }
+      }
+    };
+
+    handle().catch((err) => {
+      if (!res.headersSent) res.writeHead(500).end();
+      reportError(err);
+    });
+  };
+
+  const server: http.Server = httpOptions.tlsOptions
+    ? https.createServer(httpOptions.tlsOptions, requestHandler)
+    : http.createServer(requestHandler);
+
+  const rawClose = server.close.bind(server);
+  let shuttingDown = false;
+
+  server.close = (callback?: (err?: Error) => void) => {
+    if (shuttingDown) return rawClose(callback);
+    shuttingDown = true;
+
+    // Tear down every session through the single teardown path (clears TTL
+    // timers, fires and awaits onSessionClosed so audit manifests flush
+    // before the close callback runs).
+    // Shared records are kept: the sessions are meant to resume on the next
+    // process, and their deadlines expire them on their own.
+    void Promise.allSettled(
+      [...sessions.keys()].map((id) => destroySession(id, true)),
+    ).finally(() => {
+      rawClose(callback);
+      // Idle keep-alive and lingering SSE sockets would otherwise keep the
+      // close callback pending indefinitely.
+      server.closeAllConnections();
+    });
+
+    return server;
+  };
+
+  if (!loopback && httpOptions.resolveIdentity === undefined) {
+    reportError(
+      new Error(
+        `mcpose: startHttpProxy is binding non-loopback address "${host}" without resolveIdentity — ` +
+          'anything that can route to this host can call the upstream with ' +
+          "the proxy's credentials. Pass resolveIdentity, or bind 127.0.0.1.",
+      ),
+    );
+  }
+  // The SDK transport validates Host/Origin only against a non-empty list,
+  // and no list is derived for a non-loopback bind, so this combination is
+  // an inert flag — the false-confidence case the derived defaults exist
+  // to remove.
+  if (
+    dnsRebindingProtection &&
+    !loopback &&
+    httpOptions.allowedHosts === undefined &&
+    httpOptions.allowedOrigins === undefined
+  ) {
+    reportError(
+      new Error(
+        'mcpose: enableDnsRebindingProtection is on, but no allowedHosts or ' +
+          'allowedOrigins are set and none are derived for a non-loopback ' +
+          'bind, so the transport validates nothing. Pass allowedHosts ' +
+          'and/or allowedOrigins.',
+      ),
+    );
+  }
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      // Route post-listen server errors (e.g. EMFILE) to onError instead of
+      // crashing the process with an unhandled 'error' event.
+      server.on('error', reportError);
+      if (dnsRebindingProtection && loopback) {
+        const addr = server.address();
+        const actualPort =
+          addr !== null && typeof addr === 'object' ? addr.port : port;
+        const hosts = [
+          `127.0.0.1:${actualPort}`,
+          `localhost:${actualPort}`,
+          `[::1]:${actualPort}`,
+        ];
+        const scheme = httpOptions.tlsOptions ? 'https' : 'http';
+        derivedAllowedHosts = hosts;
+        derivedAllowedOrigins = hosts.map((h) => `${scheme}://${h}`);
+      }
+      resolve(server);
+    });
+  });
+}