mcpose 2.1.1 → 3.1.0

package/dist/core.js

@@ -3,54 +3,131 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import * as http from 'node:http';
 import * as https from 'node:https';
 import { randomUUID } from 'node:crypto';
-import { createRequire } from 'node:module';
 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 { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { pipe } from './middleware.js';
-import { createProxyContext } from './proxyContext.js';
-import { createInMemoryEventStore } from './eventStore.js';
-import { rejectionMcpError } from './rejection.js';
-// Source our own package version once at module load. `createRequire` works under
-// ESM on Node 18+ without the `--experimental-json-modules` flag and avoids the
-// tsconfig and runtime caveats of a static JSON import.
-const readPackageJson = createRequire(import.meta.url);
-const pkg = readPackageJson('../package.json');
-/** Name the proxy advertises when `ProxyOptions.name` is omitted. */
-const DEFAULT_PROXY_NAME = 'mcpose';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { pipe, isPassThroughObserver } from './middleware.js';
+import { createProxyContext, } from './proxyContext.js';
+import { listAcrossMesh, namespaceName, namespaceUri, normalizeBackends, routeNamespaced, routeResourceUri, } from './mesh.js';
+import { attachDelegationMeta, detectDelegationLoop, readInboundDelegation, } from './delegation.js';
+import { createInMemoryEventStore, scopeEventStore } from './eventStore.js';
+import { initializeParamsOf, replayInitialize, } from './sessionRegistry.js';
+import { isRejectionReason, rejectionMcpError } from './rejection.js';
+import { VERSION } from './version.js';
 /**
- * Narrows `CompatibilityCallToolResult` to `CallToolResult` (has `.content` array).
- * Both union members carry `[x: string]: unknown`, so this avoids unsafe casts.
+ * 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) {
-    return Array.isArray(r.content);
+    return (r !== null &&
+        typeof r === 'object' &&
+        Array.isArray(r.content));
+}
+/**
+ * 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, handlers) {
+    if (!hasToolContent(result))
+        return result;
+    const content = result.content
+        .map((block) => block.type === 'text' ? handlers.onText(block) : handlers.onOther(block))
+        .filter((block) => block !== null);
+    const structured = result.structuredContent === undefined
+        ? undefined
+        : handlers.onStructured(result.structuredContent);
+    const { structuredContent: _dropped, ...rest } = result;
+    return {
+        ...rest,
+        content,
+        ...(structured === undefined ? {} : { structuredContent: structured }),
+    };
+}
+/**
+ * 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) {
+    try {
+        Promise.resolve(sink?.(event)).catch((err) => {
+            console.error(err);
+        });
+    }
+    catch (err) {
+        console.error(err);
+    }
 }
 const listChangedBuses = new WeakMap();
 const httpProxyContext = new AsyncLocalStorage();
-function createProxyCapabilities(backend) {
-    const upstream = backend.getServerCapabilities();
+/**
+ * Union of every backend's capabilities, plus the ADR-0007 rule that a
+ * non-empty `localTools` advertises `tools` on its own.
+ */
+function createProxyCapabilities(entries, hasLocalTools) {
+    const upstreams = entries.map((entry) => entry.client.getServerCapabilities());
+    const listChanged = (supported) => supported ? { listChanged: true } : {};
     return {
-        ...(upstream?.tools
-            ? { tools: upstream.tools.listChanged ? { listChanged: true } : {} }
+        ...(upstreams.some((u) => u?.tools) || hasLocalTools
+            ? { tools: listChanged(upstreams.some((u) => u?.tools?.listChanged)) }
             : {}),
-        ...(upstream?.resources
+        ...(upstreams.some((u) => u?.resources)
             ? {
-                resources: upstream.resources.listChanged
-                    ? { listChanged: true }
-                    : {},
+                resources: listChanged(upstreams.some((u) => u?.resources?.listChanged)),
             }
             : {}),
-        ...(upstream?.prompts
-            ? { prompts: upstream.prompts.listChanged ? { listChanged: true } : {} }
+        ...(upstreams.some((u) => u?.prompts)
+            ? { prompts: listChanged(upstreams.some((u) => u?.prompts?.listChanged)) }
             : {}),
     };
 }
 function createRequestOptions(extra = {}) {
     const progressToken = extra._meta?.progressToken;
-    const onprogress = progressToken && extra.sendNotification
+    // `0` and `''` are legitimate progress tokens — only undefined disables.
+    const onprogress = progressToken !== undefined && extra.sendNotification
         ? ({ progress, total, message, }) => {
-            void extra.sendNotification?.({
+            // 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,
@@ -58,7 +135,8 @@ function createRequestOptions(extra = {}) {
                     ...(total === undefined ? {} : { total }),
                     ...(message === undefined ? {} : { message }),
                 },
-            });
+            })
+                .catch(() => { });
         }
         : undefined;
     if (!extra.signal && !onprogress)
@@ -68,8 +146,22 @@ function createRequestOptions(extra = {}) {
         ...(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 = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+]);
 function normalizeHeaders(headers) {
     const normalized = Object.entries(headers).reduce((acc, [key, value]) => {
+        if (SENSITIVE_HEADERS.has(key))
+            return acc;
         if (typeof value === 'string') {
             acc[key] = value;
             return acc;
@@ -81,143 +173,426 @@ function normalizeHeaders(headers) {
     }, {});
     return Object.keys(normalized).length ? normalized : undefined;
 }
-function getMiddlewareContext(signal) {
+function getMiddlewareContext(proxy, signal, delegatedFrom) {
+    const store = httpProxyContext.getStore();
     return createProxyContext({
-        ...httpProxyContext.getStore(),
+        ...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 filterHiddenTools(result, hiddenToolSet) {
-    if (!hiddenToolSet.size)
-        return result;
-    return {
-        ...result,
-        tools: result.tools.filter((tool) => !hiddenToolSet.has(tool.name)),
-    };
+function getRejectionReason(err) {
+    const reason = err?.data
+        ?.rejectionReason;
+    // A reason outside the union is an ordinary failure, not a rejection (#238).
+    return isRejectionReason(reason) ? reason : undefined;
 }
-function registerListChangedForwarders(backend, server, capabilities) {
-    if (!capabilities.tools?.listChanged &&
-        !capabilities.resources?.listChanged &&
-        !capabilities.prompts?.listChanged) {
-        return;
+/**
+ * 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) {
+    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) {
+    if (!('_meta' in res))
+        return res;
+    const { _meta: _stripped, ...rest } = res;
+    // Omit<Res, '_meta'> still satisfies Res: `_meta` is optional.
+    return rest;
+}
+/**
+ * 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) {
+    if (!name?.trim()) {
+        throw new Error(`mcpose: name must be a non-empty string, got ${JSON.stringify(name)}`);
     }
-    let bus = listChangedBuses.get(backend);
-    if (!bus) {
-        const servers = new Set();
-        const fanOut = async (notify) => {
-            await Promise.allSettled([...servers].map((proxyServer) => notify(proxyServer)));
-        };
-        if (capabilities.tools?.listChanged) {
-            backend.setNotificationHandler(ToolListChangedNotificationSchema, () => fanOut((proxyServer) => proxyServer.sendToolListChanged()));
+}
+function buildLocalToolMap(localTools) {
+    const localToolMap = new Map();
+    for (const localTool of localTools ?? []) {
+        const toolName = localTool.tool.name;
+        if (localToolMap.has(toolName)) {
+            throw new Error(`mcpose: duplicate local tool name "${toolName}"`);
         }
-        if (capabilities.prompts?.listChanged) {
-            backend.setNotificationHandler(PromptListChangedNotificationSchema, () => fanOut((proxyServer) => proxyServer.sendPromptListChanged()));
+        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, surface) {
+    const selected = entries.filter((entry) => entry.client.getServerCapabilities()?.[surface] !== undefined);
+    return {
+        entries: selected,
+        byKey: new Map(selected.map((entry) => [entry.key, entry.client])),
+    };
+}
+/** Normalizes the `hiddenTools` option to its predicate form. */
+function toHiddenToolPredicate(hiddenTools) {
+    if (typeof hiddenTools === 'function')
+        return hiddenTools;
+    const hiddenToolSet = new Set(hiddenTools ?? []);
+    return (name) => hiddenToolSet.has(name);
+}
+function filterHiddenTools(result, isHiddenTool) {
+    // 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, server, capabilities) {
+    const leaveBuses = [];
+    for (const { client } of entries) {
+        const upstream = client.getServerCapabilities() ?? {};
+        const surfaces = [
+            'tools',
+            'prompts',
+            'resources',
+        ];
+        if (!surfaces.some((surface) => capabilities[surface]?.listChanged === true &&
+            upstream[surface]?.listChanged === true)) {
+            continue;
         }
-        if (capabilities.resources?.listChanged) {
-            backend.setNotificationHandler(ResourceListChangedNotificationSchema, () => fanOut((proxyServer) => proxyServer.sendResourceListChanged()));
+        let bus = listChangedBuses.get(client);
+        if (!bus) {
+            const servers = new Set();
+            const fanOut = async (notify) => {
+                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);
         }
-        bus = { servers };
-        listChangedBuses.set(backend, 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);
+        });
     }
-    bus.servers.add(server);
-    const prevOnClose = server.onclose;
-    let active = true;
-    server.onclose = () => {
-        if (!active)
-            return;
-        active = false;
-        bus.servers.delete(server);
-        if (!bus.servers.size)
-            listChangedBuses.delete(backend);
-        prevOnClose?.();
-    };
+    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;
+    Object.defineProperty(server, 'onclose', {
+        configurable: true,
+        get: () => () => {
+            for (const leaveBus of leaveBuses)
+                leaveBus();
+            consumerOnClose?.();
+        },
+        set: (fn) => {
+            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 are forwarded as-is.
+ * 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 backend - Connected (or mock) upstream MCP client.
+ * @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(backend, options = {}) {
-    const capabilities = createProxyCapabilities(backend);
+export function createProxyServer(backends, options) {
+    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 hiddenToolSet = new Set(options.hiddenTools ?? []);
+    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) => (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) => stripResMeta ? stripTopLevelMeta(res) : res;
     const passThroughToolSet = new Set(options.passThroughTools ?? []);
     const hiddenResourceSet = new Set(options.hiddenResources ?? []);
     const passThroughResourceSet = new Set(options.passThroughResources ?? []);
-    const server = new Server({
-        name: options.name ?? DEFAULT_PROXY_NAME,
-        version: options.version ?? pkg.version,
-    }, { capabilities });
-    registerListChangedForwarders(backend, server, capabilities);
+    // 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 = 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, backendKey, method, error) => {
+        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 (req, extra) => {
+        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(extra.signal);
-            const result = await listToolsPipeline(req, async (currentReq) => filterHiddenTools(await backend.listTools(currentReq.params, requestOptions), hiddenToolSet), context);
-            return filterHiddenTools(result, hiddenToolSet);
+            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 = 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 (req, extra) => {
+        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(extra.signal);
-            const start = Date.now();
+            const context = getMiddlewareContext(proxyIdentity, extra.signal, chain);
+            const delegationError = wireError ?? detectDelegationLoop(context);
+            const start = performance.now();
             const emitTelemetry = (outcome, rejectionReason) => {
-                options.onTelemetry?.({
+                callTelemetrySink(options.onTelemetry, {
                     type: 'tool_call',
                     requestId: context.requestId,
                     ...(context.sessionId === undefined
                         ? {}
                         : { sessionId: context.sessionId }),
                     tool: name,
-                    duration_ms: Date.now() - start,
+                    duration_ms: Math.round(performance.now() - start),
                     outcome,
                     ...(rejectionReason === undefined ? {} : { rejectionReason }),
                     ...(context.identity === undefined
                         ? {}
                         : { identity: context.identity }),
+                    ...(context.proxy === undefined ? {} : { proxy: context.proxy }),
                 });
             };
-            if (hiddenToolSet.has(name)) {
-                emitTelemetry('rejected', 'TOOL_HIDDEN');
-                throw rejectionMcpError('TOOL_HIDDEN', ErrorCode.MethodNotFound, `Tool not found: ${name}`);
-            }
-            if (passThroughToolSet.has(name)) {
-                try {
-                    const result = await backend.callTool(req.params, undefined, requestOptions);
-                    emitTelemetry('success');
-                    return result;
+            // 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 = isHidden
+                ? async () => {
+                    throw rejectionMcpError('TOOL_HIDDEN', ErrorCode.MethodNotFound, `Tool not found: ${name}`);
                 }
-                catch (err) {
-                    emitTelemetry('error');
-                    throw err;
-                }
-            }
+                : 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 {
-                const result = await toolPipeline(req, (r) => backend.callTool(r.params, undefined, requestOptions), context);
-                emitTelemetry('success');
+                // 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) {
-                emitTelemetry('error');
+                const reason = getRejectionReason(err);
+                if (reason === undefined)
+                    emitTelemetry('error');
+                else
+                    emitTelemetry('rejected', reason);
                 throw err;
             }
         });
     }
     // ── Resource handlers ──────────────────────────────────────────────────────
     if (capabilities.resources) {
-        server.setRequestHandler(ListResourcesRequestSchema, async (req, extra) => {
-            const result = await backend.listResources(req.params, createRequestOptions(extra));
+        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 {
@@ -225,23 +600,107 @@ export function createProxyServer(backend, options = {}) {
                 resources: result.resources.filter((r) => !hiddenResourceSet.has(r.uri)),
             };
         });
-        server.setRequestHandler(ReadResourceRequestSchema, (req, extra) => {
+        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(extra.signal);
+            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) => {
+                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)) {
-                return backend.readResource(req.params, requestOptions);
+                // 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) => backend.readResource(r.params, requestOptions), context);
+            return resourcePipeline(req, (r) => readUpstream(r.params), context);
         });
     }
-    // ── Prompt handlers (pass-through) ────────────────────────────────────────
-    if (capabilities.prompts) {
-        server.setRequestHandler(ListPromptsRequestSchema, (req, extra) => backend.listPrompts(req.params, createRequestOptions(extra)));
-        server.setRequestHandler(GetPromptRequestSchema, (req, extra) => backend.getPrompt(req.params, createRequestOptions(extra)));
+    // ── 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;
 }
@@ -250,31 +709,77 @@ export function createProxyServer(backend, options = {}) {
  * Calls {@link createProxyServer} then connects to `StdioServerTransport`.
  * Use `createProxyServer` directly for testable access to the server.
  */
-export async function startProxy(backend, options = {}) {
-    const server = createProxyServer(backend, options);
+export async function startProxy(backends, options) {
+    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, res, maxBodyBytes) {
+    const reject413 = () => {
+        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.push = (chunk, enc) => {
-        if (chunk !== null && total + chunk.length > maxBodyBytes) {
-            if (!res.headersSent)
-                res.writeHead(413).end();
-            // Mute the response for downstream writers (the SDK transport will
-            // observe the destroyed request and try to send its own error).
-            const muted = res;
-            muted.writeHead = () => res;
-            muted.write = () => true;
-            muted.end = () => res;
+        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;
+                muted.writeHead = () => res;
+                muted.write = () => true;
+                muted.end = () => res;
+            }
             req.destroy(new Error('Request body too large'));
             return false;
         }
-        if (chunk !== null)
-            total += chunk.length;
+        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) {
+    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.
  *
@@ -286,15 +791,215 @@ function applyBodySizeLimit(req, res, maxBodyBytes) {
  * @returns Promise resolving to the listening `http.Server` (or `https.Server`
  * when `tlsOptions` is supplied).
  */
-export function startHttpProxy(backend, options = {}, httpOptions = {}) {
+export function startHttpProxy(backends, options, httpOptions = {}) {
+    // 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;
+    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;
+    let derivedAllowedOrigins;
     const eventStore = httpOptions.eventStore === null
         ? undefined
         : (httpOptions.eventStore ?? createInMemoryEventStore());
-    // session ID → { transport, proxyServer, identity }
+    const registry = httpOptions.sessionRegistry;
+    // session ID → live session held by this instance
     const sessions = new Map();
+    // 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) => {
+        // `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, keepRecord = false) => {
+        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, transport, proxyServer, identity, expiresAt) => {
+        let ttlTimer;
+        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, onsessioninitialized) => {
+        // 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();
+    /**
+     * 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, sharedRegistry, req) => {
+        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);
+                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, res) => {
         const handle = async () => {
             if (httpOptions.onRequest !== undefined) {
@@ -302,7 +1007,12 @@ export function startHttpProxy(backend, options = {}, httpOptions = {}) {
                 try {
                     allowed = await httpOptions.onRequest(req, res);
                 }
-                catch {
+                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;
@@ -318,85 +1028,173 @@ export function startHttpProxy(backend, options = {}, httpOptions = {}) {
                 return;
             }
             if (method === 'POST') {
-                applyBodySizeLimit(req, res, httpOptions.maxBodyBytes ?? 4 * 1024 * 1024);
+                const rejected = applyBodySizeLimit(req, res, maxBodyBytes);
+                if (rejected)
+                    return;
             }
             const sessionId = req.headers['mcp-session-id'];
             const headers = normalizeHeaders(req.headers);
-            await httpProxyContext.run(
-            // Base context — requestId added per-request by getMiddlewareContext()
-            { transport: 'http' }, async () => {
-                if (typeof sessionId === 'string') {
-                    // Route to existing session — stamp its resolved identity into context
-                    const session = sessions.get(sessionId);
-                    if (!session) {
-                        res.writeHead(404).end();
+            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;
+                    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 = {
-                        transport: 'http',
-                        sessionId,
-                        ...(headers === undefined ? {} : { headers }),
-                        ...(session.identity === undefined
-                            ? {}
-                            : { identity: session.identity }),
+                }
+                const requestContext = {
+                    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 = [];
+                if (registry) {
+                    const push = req.push.bind(req);
+                    req.push = (chunk, enc) => {
+                        if (chunk !== null) {
+                            bodyChunks.push(typeof chunk === 'string' ? Buffer.from(chunk, enc) : chunk);
+                        }
+                        return push(chunk, enc);
                     };
-                    await httpProxyContext.run(requestContext, () => session.transport.handleRequest(req, res));
                 }
-                else {
-                    // New session (initialize request)
-                    if (httpOptions.maxSessions !== undefined &&
-                        sessions.size >= httpOptions.maxSessions) {
-                        res.writeHead(503).end();
-                        return;
-                    }
+                try {
                     // Resolve identity once for the lifetime of this session
                     let identity;
                     if (httpOptions.resolveIdentity !== undefined) {
                         try {
                             identity = await httpOptions.resolveIdentity(req);
                         }
-                        catch {
+                        catch (err) {
+                            reportError(err);
                             if (!res.headersSent)
                                 res.writeHead(401).end();
                             return;
                         }
                     }
-                    const proxyServer = createProxyServer(backend, options);
-                    const transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: randomUUID,
-                        ...(eventStore ? { eventStore } : {}),
-                        onsessioninitialized: (id) => {
-                            sessions.set(id, { transport, proxyServer, identity });
-                            if (httpOptions.sessionTtlMs !== undefined) {
-                                const timer = setTimeout(() => {
-                                    const session = sessions.get(id);
-                                    if (session) {
-                                        sessions.delete(id);
-                                        void session.proxyServer.close();
-                                    }
-                                }, httpOptions.sessionTtlMs);
-                                timer.unref();
+                    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 }),
+                                });
                             }
-                        },
-                        onsessionclosed: (id) => {
-                            sessions.delete(id);
-                            httpOptions.onSessionClosed?.(id);
-                        },
+                            catch (err) {
+                                reportError(err);
+                                throw new Error('mcpose: session registry unavailable');
+                            }
+                        }
+                        admitSession(id, transport, proxyServer, identity, expiresAt);
                     });
                     const requestContext = {
                         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);
-                    await httpProxyContext.run(requestContext, () => transport.handleRequest(req, res));
+                    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();
-            (httpOptions.onError ?? console.error)(err);
+            reportError(err);
         });
     };
     const server = httpOptions.tlsOptions
@@ -404,21 +1202,60 @@ export function startHttpProxy(backend, options = {}, httpOptions = {}) {
         : http.createServer(requestHandler);
     const rawClose = server.close.bind(server);
     let shuttingDown = false;
-    server.close = ((callback) => {
+    server.close = (callback) => {
         if (shuttingDown)
             return rawClose(callback);
         shuttingDown = true;
-        const activeSessions = [...sessions.values()];
-        sessions.clear();
-        void Promise.allSettled(activeSessions.map(({ proxyServer }) => proxyServer.close())).finally(() => {
+        // 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 ? [host] : []), () => {
+        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);
         });
     });