mcp-compose 0.3.0 → 0.4.0

package/dist/src/gateway.js

@@ -1,39 +1,551 @@
 import { createServer as createHttpServer } from 'node:http';
-import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import crossSpawn from 'cross-spawn';
 import { OAuthClient } from './oauth.js';
+import { killProcessTree } from './process-tree.js';
 class UnauthorizedError extends Error {
     wwwAuthenticate;
-    constructor(wwwAuthenticate) {
-        super('Upstream returned 401 Unauthorized');
+    status;
+    constructor(wwwAuthenticate, status = 401) {
+        super(status === 403 ? 'Upstream returned 403 Forbidden' : 'Upstream returned 401 Unauthorized');
         this.wwwAuthenticate = wwwAuthenticate;
+        this.status = status;
         this.name = 'UnauthorizedError';
     }
 }
+/** A legacy upstream has one shared server session, so it cannot safely
+ * impersonate more than one passthrough caller at a time. */
+class CredentialAffinityError extends Error {
+    constructor() {
+        super('The shared legacy upstream session belongs to another credential; retry after that session is closed');
+        this.name = 'CredentialAffinityError';
+    }
+}
 // --- Helpers ---
 const REQUEST_TIMEOUT_MS = 120_000;
-const MAX_NOTIFICATION_BUFFER = 1000;
+const BACKEND_PROBE_TIMEOUT_MS = 5_000;
 const MAX_STDOUT_LINE_LENGTH = 10 * 1024 * 1024; // 10 MB
 const MAX_SSE_BUFFER = 10 * 1024 * 1024; // 10 MB
-function isJsonRpcMessage(value) {
-    return typeof value === 'object' && value !== null && 'jsonrpc' in value;
+const MAX_REQUEST_BODY_BYTES = MAX_STDOUT_LINE_LENGTH;
+const MAX_SSE_WRITE_QUEUE_BYTES = MAX_SSE_BUFFER;
+const MAX_PRE_HEADER_EVENT_BYTES = MAX_SSE_BUFFER;
+const SSE_KEEP_ALIVE_MS = 15_000;
+const CURRENT_MODERN_PROTOCOL_VERSION = '2026-07-28';
+const SUPPORTED_MODERN_PROTOCOL_VERSIONS = [CURRENT_MODERN_PROTOCOL_VERSION];
+const LEGACY_PROTOCOL_VERSION = '2025-11-25';
+const GATEWAY_CLIENT_INFO = { name: 'mcp-compose', version: '0.3.2' };
+const MODERN_META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const MODERN_META_CLIENT_INFO = 'io.modelcontextprotocol/clientInfo';
+const MODERN_META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const MODERN_META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+const SUBSCRIPTION_ID_META = 'io.modelcontextprotocol/subscriptionId';
+const HTTP_RESPONSE_META = Symbol('gateway HTTP response metadata');
+class UpstreamBodyTooLargeError extends Error {
+    constructor() {
+        super('Upstream response exceeds gateway limit');
+        this.name = 'UpstreamBodyTooLargeError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isModernProtocolVersion(version) {
+    return typeof version === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(version)
+        && version >= CURRENT_MODERN_PROTOCOL_VERSION;
+}
+function hasModernProtocolMetaKey(message) {
+    return isRecord(message.params)
+        && isRecord(message.params['_meta'])
+        && hasOwn(message.params['_meta'], MODERN_META_PROTOCOL_VERSION);
+}
+function modernProtocolVersionFromMessage(message) {
+    if (!isRecord(message.params) || !isRecord(message.params['_meta']))
+        return undefined;
+    const version = message.params['_meta'][MODERN_META_PROTOCOL_VERSION];
+    return typeof version === 'string' ? version : undefined;
+}
+function isModernClientRequest(message, protocolVersionHeader) {
+    // A protocol-version meta member is an explicit attempt to use the modern
+    // transport, even if its value is malformed or unsupported. It must be
+    // validated below rather than falling through into a legacy session.
+    return hasModernProtocolMetaKey(message)
+        || isModernProtocolVersion(protocolVersionHeader);
+}
+function decodedMcpNameHeader(value) {
+    const encoded = /^=\?base64\?([A-Za-z0-9+/]*={0,2})\?=$/.exec(value);
+    if (!encoded)
+        return value;
+    try {
+        const payload = encoded[1];
+        if (payload === undefined)
+            return undefined;
+        const decoded = Buffer.from(payload, 'base64');
+        // Buffer silently accepts malformed base64, so require its canonical form.
+        if (decoded.toString('base64') !== encoded[1])
+            return undefined;
+        const text = decoded.toString('utf8');
+        // Node replaces malformed UTF-8 with U+FFFD. Reject it instead of
+        // accepting a lossy name that no longer identifies the JSON-RPC request.
+        if (!Buffer.from(text, 'utf8').equals(decoded))
+            return undefined;
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+function requestName(message) {
+    if (!isRecord(message.params))
+        return undefined;
+    if (message.method === 'tools/call' || message.method === 'prompts/get') {
+        return typeof message.params['name'] === 'string' ? message.params['name'] : undefined;
+    }
+    if (message.method === 'resources/read') {
+        return typeof message.params['uri'] === 'string' ? message.params['uri'] : undefined;
+    }
+    return undefined;
+}
+function requiresMcpName(method) {
+    return method === 'tools/call' || method === 'resources/read' || method === 'prompts/get';
+}
+function hasModernProtocolMeta(message, version) {
+    return modernProtocolVersionFromMessage(message) === version;
+}
+function hasRequiredModernClientCapabilities(message) {
+    if (!isRecord(message.params) || !isRecord(message.params['_meta']))
+        return false;
+    return isRecord(message.params['_meta'][MODERN_META_CLIENT_CAPABILITIES]);
+}
+function hasValidModernClientMetadata(message) {
+    if (!isRecord(message.params) || !isRecord(message.params['_meta']))
+        return false;
+    const meta = message.params['_meta'];
+    const clientInfo = meta[MODERN_META_CLIENT_INFO];
+    return clientInfo === undefined || (isRecord(clientInfo)
+        && typeof clientInfo['name'] === 'string' && typeof clientInfo['version'] === 'string');
+}
+function stripModernMeta(message) {
+    if (!isRecord(message.params) || !isRecord(message.params['_meta']))
+        return message;
+    const meta = Object.fromEntries(Object.entries(message.params['_meta'])
+        .filter(([key]) => key !== MODERN_META_PROTOCOL_VERSION
+        && key !== MODERN_META_CLIENT_INFO && key !== MODERN_META_CLIENT_CAPABILITIES));
+    return { ...message, params: { ...message.params, _meta: meta } };
+}
+function injectModernMeta(message, protocolVersion, clientCapabilities = {}, clientInfo = GATEWAY_CLIENT_INFO) {
+    const params = isRecord(message.params) ? message.params : {};
+    const meta = isRecord(params['_meta']) ? params['_meta'] : {};
+    return {
+        ...message,
+        params: {
+            ...params,
+            _meta: {
+                ...meta,
+                [MODERN_META_PROTOCOL_VERSION]: protocolVersion,
+                [MODERN_META_CLIENT_INFO]: clientInfo,
+                [MODERN_META_CLIENT_CAPABILITIES]: clientCapabilities,
+            },
+        },
+    };
+}
+function transformBackendResponse(response, method, clientEra, backendEra) {
+    if (clientEra === backendEra)
+        return response;
+    if (isRecord(response.error)) {
+        const error = { ...response.error };
+        // Only resource reads changed their not-found code. Extension methods are
+        // opaque and may legitimately use either value for their own semantics.
+        const isResourceRead = method === 'resources/read' || method === 'resources/templates/read';
+        if (isResourceRead && clientEra === 'modern' && backendEra === 'legacy' && error['code'] === -32002) {
+            error['code'] = -32602;
+        }
+        if (isResourceRead && clientEra === 'legacy' && backendEra === 'modern' && error['code'] === -32602) {
+            error['code'] = -32002;
+        }
+        return { ...response, error };
+    }
+    if (!isRecord(response.result))
+        return response;
+    const result = { ...response.result };
+    if (clientEra === 'modern' && backendEra === 'legacy')
+        result['resultType'] = 'complete';
+    if (clientEra === 'legacy' && backendEra === 'modern')
+        delete result['resultType'];
+    return { ...response, result };
+}
+function ensureModernCompleteResult(response) {
+    if (!isRecord(response.result) || hasOwn(response.result, 'resultType'))
+        return response;
+    return { ...response, result: { ...response.result, resultType: 'complete' } };
+}
+function discoverFromInitialize(initializeResult) {
+    const initialize = isRecord(initializeResult) ? initializeResult : {};
+    const result = {
+        supportedVersions: SUPPORTED_MODERN_PROTOCOL_VERSIONS,
+        resultType: 'complete',
+    };
+    if (hasOwn(initialize, 'capabilities'))
+        result['capabilities'] = initialize['capabilities'];
+    if (hasOwn(initialize, 'instructions'))
+        result['instructions'] = initialize['instructions'];
+    if (hasOwn(initialize, 'serverInfo')) {
+        result['_meta'] = { [MODERN_META_SERVER_INFO]: initialize['serverInfo'] };
+    }
+    return result;
+}
+function initializeFromDiscover(discoverResult) {
+    const discover = isRecord(discoverResult) ? discoverResult : {};
+    const meta = isRecord(discover['_meta']) ? discover['_meta'] : {};
+    const result = {
+        protocolVersion: LEGACY_PROTOCOL_VERSION,
+        capabilities: discover['capabilities'] ?? {},
+        serverInfo: meta[MODERN_META_SERVER_INFO] ?? GATEWAY_CLIENT_INFO,
+    };
+    if (hasOwn(discover, 'instructions'))
+        result['instructions'] = discover['instructions'];
+    return result;
+}
+function hasOwn(value, key) {
+    return Object.hasOwn(value, key);
+}
+function isJsonRpcId(value) {
+    return typeof value === 'string' || (typeof value === 'number' && Number.isSafeInteger(value));
 }
 function hasRequestId(msg) {
-    return msg.id !== undefined && msg.id !== null;
+    return Object.hasOwn(msg, 'id');
+}
+function hasBackendRequestId(msg) {
+    return hasRequestId(msg);
+}
+function isJsonRpcError(value) {
+    return isRecord(value)
+        && typeof value['code'] === 'number'
+        && Number.isFinite(value['code'])
+        && typeof value['message'] === 'string';
+}
+/** A client or server request. Notifications are requests with no id member. */
+function isJsonRpcRequest(value) {
+    if (!isRecord(value) || value['jsonrpc'] !== '2.0' || typeof value['method'] !== 'string')
+        return false;
+    if ((hasOwn(value, 'id') && !isJsonRpcId(value['id']))
+        || (hasOwn(value, 'params') && !isRecord(value['params'])))
+        return false;
+    return !hasOwn(value, 'result') && !hasOwn(value, 'error');
+}
+function isJsonRpcResponse(value) {
+    if (!isRecord(value) || value['jsonrpc'] !== '2.0' || !hasOwn(value, 'id') || !isJsonRpcId(value['id'])) {
+        return false;
+    }
+    if (hasOwn(value, 'method') || hasOwn(value, 'params'))
+        return false;
+    const hasResult = hasOwn(value, 'result');
+    const hasError = hasOwn(value, 'error');
+    return hasResult !== hasError && (!hasError || isJsonRpcError(value['error']));
+}
+function mcpNameHeaderValue(msg) {
+    const name = requestName(msg);
+    if (name === undefined)
+        return '';
+    return /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/.test(name)
+        && !/^=\?base64\?.*\?=$/.test(name)
+        ? name
+        : `=?base64?${Buffer.from(name, 'utf8').toString('base64')}?=`;
+}
+function protocolVersionFromInitializeResponse(msg, response) {
+    if (msg.method !== 'initialize' || typeof response?.result !== 'object' || response.result === null) {
+        return undefined;
+    }
+    const protocolVersion = 'protocolVersion' in response.result
+        ? response.result.protocolVersion
+        : undefined;
+    return typeof protocolVersion === 'string' ? protocolVersion : undefined;
+}
+function supportedVersions(value) {
+    if (!isRecord(value))
+        return undefined;
+    const versions = value['supportedVersions'];
+    return Array.isArray(versions) && versions.every((version) => typeof version === 'string')
+        ? versions
+        : undefined;
+}
+function chooseSupportedModernVersion(value) {
+    const remoteVersions = supportedVersions(value);
+    if (!remoteVersions)
+        return undefined;
+    return SUPPORTED_MODERN_PROTOCOL_VERSIONS.find((version) => remoteVersions.includes(version));
+}
+/** Error response payloads use a pre-discovery shape in existing servers. */
+function chooseSupportedModernErrorVersion(value) {
+    if (!isRecord(value))
+        return undefined;
+    const versions = value['supportedVersions'] ?? value['supported'];
+    if (!Array.isArray(versions) || !versions.every((version) => typeof version === 'string'))
+        return undefined;
+    return SUPPORTED_MODERN_PROTOCOL_VERSIONS.find((version) => versions.includes(version));
+}
+function isRecognizableModernError(message) {
+    if (!isRecord(message.error) || typeof message.error['code'] !== 'number')
+        return false;
+    // These codes were introduced for modern HTTP protocol validation and
+    // version negotiation. A legacy method-not-found response is intentionally
+    // not included: it is the signal to fall back to the legacy handshake.
+    return message.error['code'] === -32020 || message.error['code'] === -32021 || message.error['code'] === -32022;
+}
+function isRecognizableModernProbeError(response, requestId) {
+    return isMatchingResponse(response, requestId) && isRecognizableModernError(response);
+}
+function modernErrorDiscoveryVersion(response, requestId) {
+    if (!isMatchingResponse(response, requestId) || !isRecognizableModernError(response))
+        return undefined;
+    const errorData = isRecord(response.error) ? response.error['data'] : undefined;
+    return chooseSupportedModernErrorVersion(errorData);
+}
+/** A Streamable HTTP endpoint may reject the temporary discovery method while
+ * still proving it understands a correlated JSON-RPC 2.0 request. */
+function isModernMissingDiscoveryMethod(response, requestId) {
+    return isMatchingResponse(response, requestId)
+        && isRecord(response.error)
+        && response.error['code'] === -32601
+        && responseMeta(response)?.status === 404;
+}
+function isMatchingResponse(response, requestId) {
+    return isJsonRpcResponse(response) && response.id === requestId;
+}
+function modernDiscoveryVersion(response, requestId) {
+    return isMatchingResponse(response, requestId)
+        ? chooseSupportedModernVersion(response.result)
+        : undefined;
+}
+function isLegacyInitializeResponse(response, requestId) {
+    return isMatchingResponse(response, requestId)
+        && isRecord(response.result)
+        && response.result['protocolVersion'] === LEGACY_PROTOCOL_VERSION;
+}
+function probeTimeout(operation) {
+    return new Promise((resolve, reject) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+            resolve(undefined);
+        }, BACKEND_PROBE_TIMEOUT_MS);
+        timer.unref();
+        operation(controller.signal).then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            // Authentication challenges are actionable by the current client. Do
+            // not hide one as an inconclusive probe, or negotiation would fall
+            // through into a legacy handshake using the same invalid credential.
+            if (err instanceof UnauthorizedError)
+                reject(err);
+            else
+                resolve(undefined);
+        });
+    });
+}
+const CORS_ALLOWED_HEADERS = [
+    'Authorization',
+    'Content-Type',
+    'Accept',
+    'Mcp-Session-Id',
+    'MCP-Protocol-Version',
+    'Mcp-Method',
+    'Mcp-Name',
+];
+function corsAllowedHeaders(requestedHeaders) {
+    const allowed = new Map(CORS_ALLOWED_HEADERS.map((header) => [header.toLowerCase(), header]));
+    if (!requestedHeaders)
+        return CORS_ALLOWED_HEADERS.join(', ');
+    for (const requested of requestedHeaders.split(',')) {
+        const header = requested.trim();
+        // Header names are tokens, so this both limits the reflected prefix and
+        // prevents a malformed preflight header from becoming a response header.
+        if (/^mcp-param-[!#$%&'*+.^_`|~0-9a-z-]+$/i.test(header)) {
+            allowed.set(header.toLowerCase(), header);
+        }
+    }
+    return [...allowed.values()].join(', ');
+}
+function isSafeLocalOrigin(origin, port) {
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.origin !== origin || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:'))
+        return false;
+    // Do not trust a hostname merely because it resolves locally: DNS rebinding
+    // can change that resolution after validation. Only literal loopback names
+    // are accepted, at any local development port, plus this endpoint itself.
+    const loopback = parsed.hostname === '127.0.0.1'
+        || parsed.hostname === 'localhost' || parsed.hostname === '[::1]';
+    return loopback || parsed.origin === `http://127.0.0.1:${String(port)}`;
 }
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on('data', (chunk) => { chunks.push(chunk); });
-        req.on('end', () => { resolve(Buffer.concat(chunks).toString('utf8')); });
+        let size = 0;
+        let tooLarge = false;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_REQUEST_BODY_BYTES) {
+                tooLarge = true;
+                chunks.length = 0;
+                // Consume the rest of the request rather than leaving a keep-alive
+                // socket with an unread body, but never retain it in memory.
+                req.resume();
+                return;
+            }
+            if (!tooLarge)
+                chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (tooLarge)
+                reject(new Error('Request body exceeds gateway limit'));
+            else
+                resolve(Buffer.concat(chunks).toString('utf8'));
+        });
         req.on('error', reject);
     });
 }
-let sseEventId = 0;
-function sendSSE(res, msg) {
-    if (res.writableEnded || res.destroyed)
+function safeResponseHeaders(headers) {
+    const safeHeaders = {};
+    // This is deliberately small: framing, connection, cookie, and arbitrary
+    // upstream headers belong to the upstream hop, not the gateway response.
+    for (const name of [
+        'content-type', 'cache-control', 'www-authenticate', 'mcp-protocol-version',
+    ]) {
+        const value = headers.get(name);
+        if (value)
+            safeHeaders[name] = value;
+    }
+    return safeHeaders;
+}
+/** Consume a fetch body without allowing an upstream peer to allocate an
+ * unbounded string in the gateway.  Aborting the owning request also stops a
+ * peer that keeps writing after the limit has been reached. */
+async function readBoundedResponseText(response, controller) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return '';
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_REQUEST_BODY_BYTES) {
+                controller?.abort(new UpstreamBodyTooLargeError());
+                await reader.cancel().catch(() => { });
+                throw new UpstreamBodyTooLargeError();
+            }
+            chunks.push(value);
+        }
+        return new TextDecoder().decode(Buffer.concat(chunks));
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function drainBoundedResponse(response, controller) {
+    await readBoundedResponseText(response, controller).catch(() => { });
+}
+function setHttpResponseMeta(message, status, headers) {
+    const safeHeaders = safeResponseHeaders(headers);
+    Object.defineProperty(message, HTTP_RESPONSE_META, {
+        value: { status, headers: safeHeaders },
+        enumerable: false,
+    });
+    return message;
+}
+function responseMeta(message) {
+    return message[HTTP_RESPONSE_META];
+}
+function createSseWriter(res) {
+    let queue = [];
+    let queueBytes = 0;
+    let draining = false;
+    let closed = false;
+    let ending = false;
+    let endPromise;
+    let resolveEnd;
+    const closeOverflow = () => {
+        closed = true;
+        queue = [];
+        queueBytes = 0;
+        // A reader that cannot drain a bounded queue must not pin an unbounded
+        // response buffer or an SSE subscription forever.
+        res.destroy();
         return false;
-    return res.write(`event: message\nid: ${String(++sseEventId)}\ndata: ${JSON.stringify(msg)}\n\n`);
+    };
+    const finish = () => {
+        if (!ending || draining || queue.length > 0 || closed)
+            return;
+        closed = true;
+        res.removeListener('drain', onDrain);
+        if (res.writableEnded || res.destroyed) {
+            resolveEnd?.();
+            return;
+        }
+        res.end(() => { resolveEnd?.(); });
+    };
+    const flush = () => {
+        draining = false;
+        while (!closed && queue.length > 0) {
+            const chunk = queue.shift();
+            if (chunk === undefined)
+                continue;
+            queueBytes -= Buffer.byteLength(chunk);
+            if (!res.write(chunk)) {
+                draining = true;
+                return;
+            }
+        }
+        finish();
+    };
+    const write = (chunk) => {
+        if (closed || res.writableEnded || res.destroyed)
+            return false;
+        if (draining) {
+            const bytes = Buffer.byteLength(chunk);
+            if (queueBytes + bytes > MAX_SSE_WRITE_QUEUE_BYTES)
+                return closeOverflow();
+            queue.push(chunk);
+            queueBytes += bytes;
+            return true;
+        }
+        if (!res.write(chunk))
+            draining = true;
+        return true;
+    };
+    const onDrain = () => { flush(); };
+    const onClose = () => {
+        closed = true;
+        queue = [];
+        queueBytes = 0;
+        resolveEnd?.();
+    };
+    res.on('drain', onDrain);
+    res.once('close', onClose);
+    return {
+        writeMessage: (msg) => write(`event: message\r\ndata: ${JSON.stringify(msg)}\r\n\r\n`),
+        writeComment: () => write(':\r\n\r\n'),
+        end: () => {
+            if (endPromise)
+                return endPromise;
+            if (closed)
+                return Promise.resolve();
+            ending = true;
+            endPromise = new Promise((resolve) => { resolveEnd = resolve; });
+            finish();
+            return endPromise;
+        },
+    };
 }
 function makeErrorResponse(id, code, message) {
     return JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id });
@@ -51,8 +563,13 @@ function buildProtectedResourceUrls(remoteUrl) {
     return urls;
 }
 // --- Stdio Backend ---
-function createStdioBackend(command, logger) {
-    const child = spawn(command, { stdio: ['pipe', 'pipe', 'pipe'], shell: true, detached: true });
+function createStdioBackend(command, args, logger) {
+    const child = crossSpawn(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: false,
+        detached: process.platform !== 'win32',
+        windowsHide: true,
+    });
     // stdio: ['pipe','pipe','pipe'] guarantees non-null streams
     if (!child.stdout || !child.stderr || !child.stdin) {
         throw new Error('Failed to create stdio pipes');
@@ -61,17 +578,52 @@ function createStdioBackend(command, logger) {
     const childStderr = child.stderr;
     const childStdin = child.stdin;
     const pendingRequests = new Map();
+    const cancelledRequestIds = new Set();
+    const cancelledRequestTimers = new Map();
     let stdoutBuffer = '';
     const backend = {
+        era: 'legacy',
+        ready: Promise.resolve(),
+        beginReadiness() { return this.ready; },
         onServerMessage: null,
         onClose: null,
-        sendRequest(msg, _ctx) {
+        sendRequest(msg, _ctx, signal) {
             return new Promise((resolve) => {
-                const timer = setTimeout(() => {
+                let settled = false;
+                const settle = (response) => {
+                    if (settled)
+                        return;
+                    settled = true;
                     pendingRequests.delete(msg.id);
-                    resolve({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'Request timeout' } });
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve(response);
+                };
+                const timer = setTimeout(() => {
+                    settle({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'Request timeout' } });
                 }, REQUEST_TIMEOUT_MS);
-                pendingRequests.set(msg.id, { resolve, timer });
+                const onAbort = () => {
+                    cancelledRequestIds.add(msg.id);
+                    const oldTimer = cancelledRequestTimers.get(msg.id);
+                    if (oldTimer)
+                        clearTimeout(oldTimer);
+                    const expiry = setTimeout(() => {
+                        cancelledRequestIds.delete(msg.id);
+                        cancelledRequestTimers.delete(msg.id);
+                    }, REQUEST_TIMEOUT_MS);
+                    expiry.unref();
+                    cancelledRequestTimers.set(msg.id, expiry);
+                    settle({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'Request cancelled' } });
+                };
+                pendingRequests.set(msg.id, {
+                    resolve: (response) => { settle(response); },
+                    timer,
+                });
+                if (signal?.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal?.addEventListener('abort', onAbort, { once: true });
                 childStdin.write(JSON.stringify(msg) + '\n');
             });
         },
@@ -89,17 +641,21 @@ function createStdioBackend(command, logger) {
                 clearTimeout(pending.timer);
             }
             pendingRequests.clear();
-            // Kill the entire process group (shell + actual MCP server process)
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, 'SIGTERM');
-            }
-            catch {
-                try {
-                    child.kill('SIGTERM');
-                }
-                catch { /* already dead */ }
+            for (const timer of cancelledRequestTimers.values())
+                clearTimeout(timer);
+            cancelledRequestTimers.clear();
+            cancelledRequestIds.clear();
+            if (child.pid)
+                killProcessTree(child.pid);
+            // Detach every stdio handle synchronously. Waiting only for SIGTERM's
+            // eventual exit event leaves an idle gateway process pinned by its pipes.
+            childStdin.destroy();
+            childStdout.destroy();
+            childStderr.destroy();
+            for (const stream of [childStdin, childStdout, childStderr]) {
+                stream.unref?.();
             }
+            child.unref();
         },
     };
     childStdout.on('data', (chunk) => {
@@ -116,18 +672,31 @@ function createStdioBackend(command, logger) {
                 continue;
             try {
                 const parsed = JSON.parse(line);
-                if (!isJsonRpcMessage(parsed))
-                    continue;
-                // Route response to pending request, or forward as server-initiated message
-                if (hasRequestId(parsed) && pendingRequests.has(parsed.id)) {
-                    const pending = pendingRequests.get(parsed.id);
-                    if (pending) {
-                        pendingRequests.delete(parsed.id);
-                        clearTimeout(pending.timer);
-                        pending.resolve(parsed);
+                if (isJsonRpcResponse(parsed)) {
+                    // A response is only meaningful to the matching pending request. Do
+                    // not broadcast malformed or mismatched responses as notifications.
+                    if (!hasBackendRequestId(parsed))
+                        continue;
+                    if (cancelledRequestIds.delete(parsed.id)) {
+                        const timer = cancelledRequestTimers.get(parsed.id);
+                        if (timer)
+                            clearTimeout(timer);
+                        cancelledRequestTimers.delete(parsed.id);
+                        // A stdio peer cannot be force-cancelled at the protocol layer. Do
+                        // not turn a late response to a locally cancelled request into a
+                        // server notification for every connected client.
+                        continue;
+                    }
+                    if (pendingRequests.has(parsed.id)) {
+                        const pending = pendingRequests.get(parsed.id);
+                        if (pending) {
+                            pendingRequests.delete(parsed.id);
+                            clearTimeout(pending.timer);
+                            pending.resolve(parsed);
+                        }
                     }
                 }
-                else {
+                else if (isJsonRpcRequest(parsed)) {
                     backend.onServerMessage?.(parsed);
                 }
             }
@@ -160,42 +729,52 @@ function createStdioBackend(command, logger) {
  * in real time so in-flight clients see progress without waiting for the
  * entire response. Returns the JSON-RPC response matching originalMsg.
  */
-async function parseSseResponse(res, originalMsg, backend, logger) {
+async function parseSseResponse(res, originalMsg, backend, logger, onEvent, controller) {
     const reader = res.body?.getReader();
     if (!reader)
         return undefined;
-    const requestId = hasRequestId(originalMsg) ? originalMsg.id : null;
+    const requestId = hasBackendRequestId(originalMsg) ? originalMsg.id : undefined;
     const decoder = new TextDecoder();
     let buffer = '';
     let response;
     const handleBlock = (block) => {
-        let data;
-        for (const line of block.split('\n')) {
-            if (line.startsWith('data: '))
-                data = line.slice(6);
-            else if (line.startsWith('data:'))
-                data = line.slice(5);
+        const dataLines = [];
+        for (const line of block.split(/\r?\n/)) {
+            // SSE comments and fields other than data are intentionally ignored.
+            if (line.startsWith('data:'))
+                dataLines.push(line.slice(5).replace(/^ /, ''));
         }
-        if (!data?.trim())
-            return;
+        const data = dataLines.join('\n');
+        if (!data.trim())
+            return false;
         let parsed;
         try {
             parsed = JSON.parse(data);
         }
         catch {
-            return;
+            return false;
         }
-        if (!isJsonRpcMessage(parsed))
-            return;
-        if (requestId !== null && hasRequestId(parsed) && parsed.id === requestId) {
+        if (isJsonRpcResponse(parsed) && requestId !== undefined && parsed.id === requestId) {
             response = parsed;
+            return true;
         }
-        else {
-            backend.onServerMessage?.(parsed);
+        else if (isJsonRpcRequest(parsed)) {
+            if (hasRequestId(parsed)) {
+                // Server-initiated requests need MRTR to be unambiguous. This gateway
+                // intentionally has no MRTR bridge, so never leak them to another
+                // request or subscription stream.
+                logger('debug', `Dropping server-initiated request ${parsed.method ?? '<unknown>'}`);
+            }
+            else if (onEvent) {
+                onEvent(parsed);
+            }
+            else {
+                backend.onServerMessage?.(parsed);
+            }
         }
+        return false;
     };
     try {
-        let searchFrom = 0;
         for (;;) {
             const { done, value } = await reader.read();
             if (done)
@@ -203,17 +782,22 @@ async function parseSseResponse(res, originalMsg, backend, logger) {
             buffer += decoder.decode(value, { stream: true });
             if (buffer.length > MAX_SSE_BUFFER) {
                 logger('info', `SSE event exceeded ${String(MAX_SSE_BUFFER)} bytes without terminator; aborting`);
+                controller?.abort(new UpstreamBodyTooLargeError());
                 await reader.cancel().catch(() => { });
-                return response;
+                throw new UpstreamBodyTooLargeError();
             }
-            let boundary = buffer.indexOf('\n\n', searchFrom);
-            while (boundary !== -1) {
-                handleBlock(buffer.slice(0, boundary));
-                buffer = buffer.slice(boundary + 2);
-                boundary = buffer.indexOf('\n\n');
+            let boundary = /\r?\n\r?\n/.exec(buffer);
+            while (boundary?.index !== undefined) {
+                const completed = handleBlock(buffer.slice(0, boundary.index));
+                buffer = buffer.slice(boundary.index + boundary[0].length);
+                if (completed) {
+                    await reader.cancel().catch(() => { });
+                    return response;
+                }
+                boundary = /\r?\n\r?\n/.exec(buffer);
             }
-            searchFrom = Math.max(0, buffer.length - 1);
         }
+        buffer += decoder.decode();
         if (buffer.trim())
             handleBlock(buffer);
     }
@@ -226,107 +810,706 @@ async function parseSseResponse(res, originalMsg, backend, logger) {
     }
     return response;
 }
-function createProxyBackend(remoteUrl, headers, authMode, oauthClient, logger) {
+function createProxyBackend(remoteUrl, transport, headers, authMode, oauthClient, logger) {
     let remoteSessionId;
+    let remoteSessionAuthorization;
+    let hasRemoteSessionAuthorization = false;
+    let negotiatedProtocolVersion;
     let accessToken;
-    // Preload cached token (managed mode only) so the first request avoids
-    // an unnecessary 401 roundtrip. Passthrough mode never holds tokens.
-    const initialTokenLoad = oauthClient
-        ? oauthClient.getAccessToken().then((token) => {
+    const activeFetches = new Set();
+    const ssePending = new Map();
+    let sseEndpoint;
+    let sseConnect;
+    let sseController;
+    // An old SSE transport has one shared GET connection even when its server
+    // does not issue Mcp-Session-Id.  Bind that connection at creation time,
+    // rather than waiting for a header which some valid legacy servers omit.
+    let sseAuthorization;
+    let hasSseAuthorization = false;
+    function invalidateLegacySse(error) {
+        sseEndpoint = undefined;
+        remoteSessionId = undefined;
+        remoteSessionAuthorization = undefined;
+        hasRemoteSessionAuthorization = false;
+        sseAuthorization = undefined;
+        hasSseAuthorization = false;
+        sseConnect = undefined;
+        for (const [, pending] of ssePending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        ssePending.clear();
+    }
+    // Do not even read cached credentials until a client-triggered request
+    // reaches this backend. OAuth work is request-owned so an abandoned client
+    // or gateway stop can abort metadata and token I/O as well as fetches.
+    async function loadCachedToken(signal) {
+        if (!oauthClient || accessToken)
+            return;
+        try {
+            const token = await oauthClient.getAccessToken(signal ? { signal } : {});
             if (token && !accessToken)
                 accessToken = token;
-        }).catch(() => { })
-        : Promise.resolve();
-    async function forwardToRemote(msg, ctx, retryCount = 0) {
-        await initialTokenLoad;
-        const reqHeaders = {
-            'Content-Type': 'application/json',
-            'Accept': 'application/json, text/event-stream',
-            ...headers,
-        };
-        if (authMode === 'passthrough') {
-            if (ctx?.authorization)
-                reqHeaders['Authorization'] = ctx.authorization;
         }
-        else if (accessToken) {
-            reqHeaders['Authorization'] = `Bearer ${accessToken}`;
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            // A cache/discovery failure is not an auth failure. Let the upstream
+            // issue its normal challenge, which may select different metadata.
         }
-        if (remoteSessionId && msg.method !== 'initialize') {
-            reqHeaders['Mcp-Session-Id'] = remoteSessionId;
+    }
+    function assertLegacySessionAffinity(ctx) {
+        if (authMode !== 'passthrough' || !remoteSessionId)
+            return;
+        if (!hasRemoteSessionAuthorization || remoteSessionAuthorization !== ctx?.authorization) {
+            throw new CredentialAffinityError();
+        }
+    }
+    function assertLegacySseAffinity(ctx) {
+        if (authMode !== 'passthrough' || !hasSseAuthorization)
+            return;
+        if (sseAuthorization !== ctx?.authorization)
+            throw new CredentialAffinityError();
+    }
+    function claimLegacySseAffinity(ctx) {
+        assertLegacySseAffinity(ctx);
+        if (authMode === 'passthrough' && !hasSseAuthorization) {
+            sseAuthorization = ctx?.authorization;
+            hasSseAuthorization = true;
         }
-        let res;
+    }
+    async function refreshAfterUnauthorized(wwwAuth, signal) {
+        if (!oauthClient)
+            return;
+        accessToken = await oauthClient.handleUnauthorized(wwwAuth, signal ? { signal } : {});
+    }
+    function isInsufficientScopeChallenge(status, wwwAuthenticate) {
+        if (status !== 403 || !wwwAuthenticate)
+            return false;
+        const bearer = /(?:^|,)\s*Bearer\s+([\s\S]*)/i.exec(wwwAuthenticate);
+        if (!bearer?.[1])
+            return false;
+        // Stop at a following auth-scheme, but retain comma-separated Bearer
+        // parameters such as scope and resource_metadata.
+        const challenge = bearer[1].split(/,\s*[A-Za-z][A-Za-z0-9_-]*\s+(?=[A-Za-z_-]+=)/)[0] ?? '';
+        return /(?:^|,)\s*error\s*=\s*(?:"insufficient_scope"|insufficient_scope)(?:\s*,|\s*$)/i.test(challenge);
+    }
+    async function forwardToRemote(msg, ctx, retryCount = 0, signal, onEvent, onResponseStart, deadline = Date.now() + REQUEST_TIMEOUT_MS) {
+        const controller = new AbortController();
+        const requestTimeout = new Error('Request timeout');
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            controller.abort(requestTimeout);
+        const timeout = setTimeout(() => { controller.abort(requestTimeout); }, Math.max(0, remaining));
+        const abortFromCaller = () => { controller.abort(signal?.reason); };
+        if (signal?.aborted)
+            controller.abort(signal.reason);
+        else
+            signal?.addEventListener('abort', abortFromCaller, { once: true });
+        activeFetches.add(controller);
         try {
-            res = await fetch(remoteUrl, {
-                method: 'POST',
-                headers: reqHeaders,
-                body: JSON.stringify(msg),
+            await loadCachedToken(controller.signal);
+            assertLegacySessionAffinity(ctx);
+            const inboundAccept = ctx?.accept;
+            const accepts = (mediaType) => {
+                const escaped = mediaType.replace('/', '\\/');
+                const match = new RegExp(`(?:^|,)\\s*${escaped}(?:\\s*;([^,]*))?(?:,|$)`, 'i').exec(inboundAccept ?? '');
+                return match !== null && !/(?:^|;)\\s*q\\s*=\\s*0(?:\\.0*)?\\s*(?:;|$)/i.test(match[1] ?? '');
+            };
+            const accept = [
+                inboundAccept,
+                !accepts('application/json') ? 'application/json' : undefined,
+                !accepts('text/event-stream') ? 'text/event-stream' : undefined,
+            ].filter((value) => value !== undefined).join(', ');
+            const reqHeaders = new Headers({
+                ...headers,
+                'Content-Type': 'application/json',
+                'Accept': accept,
             });
+            const protocolVersion = ctx?.protocolVersion ?? backend.protocolVersion ?? negotiatedProtocolVersion;
+            if (protocolVersion)
+                reqHeaders.set('MCP-Protocol-Version', protocolVersion);
+            reqHeaders.set('Mcp-Method', msg.method ?? '');
+            if (requestName(msg) !== undefined)
+                reqHeaders.set('Mcp-Name', mcpNameHeaderValue(msg));
+            for (const [name, value] of ctx?.mcpParamHeaders ?? []) {
+                reqHeaders.append(name, value);
+            }
+            if (authMode === 'passthrough') {
+                if (ctx?.authorization)
+                    reqHeaders.set('Authorization', ctx.authorization);
+            }
+            else if (accessToken) {
+                reqHeaders.set('Authorization', `Bearer ${accessToken}`);
+            }
+            if (backend.era === 'legacy' && remoteSessionId && msg.method !== 'initialize') {
+                reqHeaders.set('Mcp-Session-Id', remoteSessionId);
+            }
+            let res;
+            try {
+                res = await fetch(remoteUrl, {
+                    method: 'POST',
+                    headers: reqHeaders,
+                    body: JSON.stringify(msg),
+                    signal: controller.signal,
+                    redirect: 'error',
+                });
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                logger('info', `Remote fetch failed: ${errMsg}`);
+                return {
+                    jsonrpc: '2.0',
+                    id: hasRequestId(msg) ? msg.id : null,
+                    error: {
+                        code: -32000,
+                        message: controller.signal.reason === requestTimeout
+                            ? 'Request timeout'
+                            : `Remote server unreachable: ${errMsg}`,
+                    },
+                };
+            }
+            if (res.status === 401 || isInsufficientScopeChallenge(res.status, res.headers.get('www-authenticate') ?? undefined)) {
+                const wwwAuth = res.headers.get('www-authenticate') ?? undefined;
+                if (authMode === 'passthrough' && res.status === 401) {
+                    throw new UnauthorizedError(wwwAuth);
+                }
+                if (oauthClient && retryCount < 2) {
+                    // Only a response that will actually be retried may be consumed.
+                    await drainBoundedResponse(res, controller);
+                    logger('info', `Received ${String(res.status)} authentication challenge, starting OAuth flow...`);
+                    await refreshAfterUnauthorized(wwwAuth, controller.signal);
+                    logger('info', 'OAuth completed, retrying request...');
+                    return await forwardToRemote(msg, ctx, retryCount + 1, signal, onEvent, onResponseStart, deadline);
+                }
+            }
+            const sessionHeader = res.headers.get('mcp-session-id');
+            if (sessionHeader) {
+                remoteSessionId = sessionHeader;
+                // A legacy upstream session is owned by the client credential that
+                // created it. Keep that exact credential solely for its cleanup.
+                remoteSessionAuthorization = authMode === 'passthrough' ? ctx?.authorization : undefined;
+                hasRemoteSessionAuthorization = authMode === 'passthrough';
+            }
+            if (res.status === 202) {
+                await drainBoundedResponse(res, controller);
+                return undefined;
+            }
+            // HTTP status and safe response headers are available as soon as fetch
+            // resolves, before the potentially long-lived SSE body is decoded.
+            // Commit downstream SSE framing here so notifications can flow live.
+            onResponseStart?.({ status: res.status, headers: safeResponseHeaders(res.headers) });
+            if (!res.ok) {
+                let text;
+                try {
+                    text = await readBoundedResponseText(res, controller);
+                }
+                catch (err) {
+                    if (err instanceof UpstreamBodyTooLargeError) {
+                        return {
+                            jsonrpc: '2.0', id: hasRequestId(msg) ? msg.id : null,
+                            error: { code: -32000, message: err.message },
+                        };
+                    }
+                    throw err;
+                }
+                logger('info', `Remote server returned HTTP ${String(res.status)}`);
+                try {
+                    const response = JSON.parse(text);
+                    if (isJsonRpcResponse(response))
+                        return setHttpResponseMeta(response, res.status, res.headers);
+                }
+                catch {
+                    // A non-JSON error cannot identify a modern JSON-RPC endpoint.
+                }
+                return {
+                    jsonrpc: '2.0',
+                    id: hasRequestId(msg) ? msg.id : null,
+                    error: { code: -32000, message: `Remote server error: ${String(res.status)}` },
+                };
+            }
+            const contentType = res.headers.get('content-type') ?? '';
+            if (contentType.includes('text/event-stream')) {
+                let response;
+                try {
+                    response = await parseSseResponse(res, msg, backend, logger, onEvent, controller);
+                }
+                catch (err) {
+                    if (err instanceof UpstreamBodyTooLargeError) {
+                        return {
+                            jsonrpc: '2.0', id: hasRequestId(msg) ? msg.id : null,
+                            error: { code: -32000, message: err.message },
+                        };
+                    }
+                    throw err;
+                }
+                negotiatedProtocolVersion ??= protocolVersionFromInitializeResponse(msg, response);
+                return response && setHttpResponseMeta(response, res.status, res.headers);
+            }
+            let response;
+            try {
+                response = JSON.parse(await readBoundedResponseText(res, controller));
+            }
+            catch (err) {
+                if (err instanceof UpstreamBodyTooLargeError) {
+                    return {
+                        jsonrpc: '2.0', id: hasRequestId(msg) ? msg.id : null,
+                        error: { code: -32000, message: err.message },
+                    };
+                }
+                return {
+                    jsonrpc: '2.0', id: hasRequestId(msg) ? msg.id : null,
+                    error: { code: -32603, message: 'Remote server returned an invalid JSON-RPC response' },
+                };
+            }
+            if (!isJsonRpcResponse(response)) {
+                return {
+                    jsonrpc: '2.0',
+                    id: hasRequestId(msg) ? msg.id : null,
+                    error: { code: -32603, message: 'Remote server returned an invalid JSON-RPC response' },
+                };
+            }
+            negotiatedProtocolVersion ??= protocolVersionFromInitializeResponse(msg, response);
+            return setHttpResponseMeta(response, res.status, res.headers);
         }
-        catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            logger('info', `Remote fetch failed: ${errMsg}`);
-            return {
-                jsonrpc: '2.0',
-                id: hasRequestId(msg) ? msg.id : null,
-                error: { code: -32000, message: `Remote server unreachable: ${errMsg}` },
-            };
+        finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', abortFromCaller);
+            activeFetches.delete(controller);
         }
-        if (res.status === 401) {
-            const wwwAuth = res.headers.get('www-authenticate') ?? undefined;
-            if (authMode === 'passthrough') {
-                // Drain body so the connection can be reused.
-                await res.text().catch(() => { });
-                throw new UnauthorizedError(wwwAuth);
+    }
+    function sseHeaders(ctx) {
+        const requestHeaders = new Headers({ ...headers, Accept: 'text/event-stream' });
+        if (ctx?.protocolVersion)
+            requestHeaders.set('MCP-Protocol-Version', ctx.protocolVersion);
+        for (const [name, value] of ctx?.mcpParamHeaders ?? [])
+            requestHeaders.append(name, value);
+        if (authMode === 'passthrough') {
+            if (ctx?.authorization)
+                requestHeaders.set('Authorization', ctx.authorization);
+        }
+        else if (accessToken) {
+            requestHeaders.set('Authorization', `Bearer ${accessToken}`);
+        }
+        return requestHeaders;
+    }
+    async function connectLegacySse(ctx, signal) {
+        assertLegacySessionAffinity(ctx);
+        assertLegacySseAffinity(ctx);
+        if (sseEndpoint)
+            return;
+        if (sseConnect)
+            return sseConnect;
+        claimLegacySseAffinity(ctx);
+        sseConnect = (async () => {
+            const controller = new AbortController();
+            const abortFromCaller = () => { controller.abort(signal?.reason); };
+            if (signal?.aborted)
+                controller.abort(signal.reason);
+            else
+                signal?.addEventListener('abort', abortFromCaller, { once: true });
+            const timeout = setTimeout(() => { controller.abort(new Error('Legacy SSE connection timed out')); }, REQUEST_TIMEOUT_MS);
+            timeout.unref();
+            await loadCachedToken(controller.signal);
+            sseController = controller;
+            activeFetches.add(controller);
+            let endpointResolve;
+            let endpointReject;
+            const endpointReady = new Promise((resolve, reject) => {
+                endpointResolve = resolve;
+                endpointReject = reject;
+            });
+            try {
+                let response;
+                for (let retryCount = 0; retryCount <= 2; retryCount += 1) {
+                    response = await fetch(remoteUrl, {
+                        method: 'GET', headers: sseHeaders(ctx), signal: controller.signal, redirect: 'error',
+                    });
+                    const wwwAuth = response.headers.get('www-authenticate') ?? undefined;
+                    if (response.status !== 401 && !isInsufficientScopeChallenge(response.status, wwwAuth))
+                        break;
+                    await drainBoundedResponse(response, controller);
+                    if (authMode === 'passthrough')
+                        throw new UnauthorizedError(wwwAuth, response.status);
+                    if (!oauthClient || retryCount === 2)
+                        break;
+                    await refreshAfterUnauthorized(wwwAuth, controller.signal);
+                }
+                if (!response)
+                    throw new Error('Legacy SSE endpoint did not return a response');
+                if (!response.ok || !response.body) {
+                    await drainBoundedResponse(response, controller);
+                    const wwwAuth = response.headers.get('www-authenticate') ?? undefined;
+                    if (response.status === 401 || isInsufficientScopeChallenge(response.status, wwwAuth)) {
+                        throw new UnauthorizedError(wwwAuth, response.status);
+                    }
+                    throw new Error(`Legacy SSE endpoint returned ${String(response.status)}`);
+                }
+                const remoteSession = response.headers.get('mcp-session-id');
+                if (remoteSession) {
+                    remoteSessionId = remoteSession;
+                    remoteSessionAuthorization = authMode === 'passthrough' ? ctx?.authorization : undefined;
+                    hasRemoteSessionAuthorization = authMode === 'passthrough';
+                }
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                const rejectInvalidEndpoint = (error) => {
+                    // An endpoint event is untrusted input. Abort both the fetch and its
+                    // reader before rejecting readiness so an invalid event cannot leave
+                    // a credential-bearing GET stream alive in the background.
+                    endpointReject?.(error);
+                    controller.abort(error);
+                    void reader.cancel(error).catch(() => { });
+                };
+                const handleBlock = (block) => {
+                    let event = '';
+                    const data = [];
+                    for (const line of block.split(/\r?\n/)) {
+                        if (line.startsWith('event:'))
+                            event = line.slice(6).trim();
+                        if (line.startsWith('data:'))
+                            data.push(line.slice(5).replace(/^ /, ''));
+                    }
+                    const payload = data.join('\n');
+                    if (!payload)
+                        return;
+                    if (event === 'endpoint') {
+                        try {
+                            const endpoint = new URL(payload, remoteUrl);
+                            const configured = new URL(remoteUrl);
+                            if ((endpoint.protocol !== 'http:' && endpoint.protocol !== 'https:')
+                                || endpoint.origin !== configured.origin
+                                || endpoint.username !== configured.username
+                                || endpoint.password !== configured.password) {
+                                throw new Error('Legacy SSE endpoint must use the configured upstream origin');
+                            }
+                            // The endpoint is a one-time connection property. A later
+                            // endpoint event must not retarget an established session.
+                            if (sseEndpoint)
+                                return;
+                            sseEndpoint = endpoint.toString();
+                            endpointResolve?.();
+                        }
+                        catch (err) {
+                            rejectInvalidEndpoint(err instanceof Error
+                                ? err : new Error('Legacy SSE endpoint event contained an invalid URL'));
+                        }
+                        return;
+                    }
+                    try {
+                        const message = JSON.parse(payload);
+                        if (isJsonRpcResponse(message) && hasBackendRequestId(message)) {
+                            const pending = ssePending.get(message.id);
+                            if (pending) {
+                                ssePending.delete(message.id);
+                                clearTimeout(pending.timer);
+                                pending.resolve(message);
+                            }
+                        }
+                        else if (isJsonRpcRequest(message)) {
+                            if (hasRequestId(message))
+                                logger('debug', `Dropping server-initiated request ${message.method ?? '<unknown>'}`);
+                            else
+                                backend.onServerMessage?.(message);
+                        }
+                    }
+                    catch {
+                        logger('debug', 'Ignoring invalid legacy SSE event');
+                    }
+                };
+                const streamFinished = (async () => {
+                    try {
+                        for (;;) {
+                            const { done, value } = await reader.read();
+                            if (done)
+                                break;
+                            buffer += decoder.decode(value, { stream: true });
+                            if (buffer.length > MAX_SSE_BUFFER) {
+                                controller.abort(new UpstreamBodyTooLargeError());
+                                throw new UpstreamBodyTooLargeError();
+                            }
+                            let boundary = /\r?\n\r?\n/.exec(buffer);
+                            while (boundary?.index !== undefined) {
+                                handleBlock(buffer.slice(0, boundary.index));
+                                buffer = buffer.slice(boundary.index + boundary[0].length);
+                                boundary = /\r?\n\r?\n/.exec(buffer);
+                            }
+                        }
+                        buffer += decoder.decode();
+                        if (buffer.trim())
+                            handleBlock(buffer);
+                    }
+                    catch (err) {
+                        if (!controller.signal.aborted)
+                            logger('info', `Legacy SSE stream failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    finally {
+                        try {
+                            reader.releaseLock();
+                        }
+                        catch { /* ignore */ }
+                        clearTimeout(timeout);
+                        signal?.removeEventListener('abort', abortFromCaller);
+                        activeFetches.delete(controller);
+                        if (sseController === controller)
+                            sseController = undefined;
+                        const streamError = new Error(controller.signal.aborted
+                            ? 'Legacy SSE stream aborted' : 'Legacy SSE stream closed');
+                        endpointReject?.(streamError);
+                        invalidateLegacySse(streamError);
+                    }
+                })();
+                try {
+                    await endpointReady;
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    controller.abort(error);
+                    await streamFinished;
+                    throw error;
+                }
+                // The connection now belongs to the shared legacy session, not to
+                // the request that happened to establish it.
+                signal?.removeEventListener('abort', abortFromCaller);
             }
-            if (oauthClient && retryCount < 2) {
-                logger('info', 'Received 401, starting OAuth flow...');
-                accessToken = await oauthClient.handleUnauthorized(wwwAuth);
-                logger('info', 'OAuth completed, retrying request...');
-                return await forwardToRemote(msg, ctx, retryCount + 1);
+            finally {
+                if (!sseEndpoint) {
+                    clearTimeout(timeout);
+                    signal?.removeEventListener('abort', abortFromCaller);
+                    activeFetches.delete(controller);
+                    if (sseController === controller)
+                        sseController = undefined;
+                }
             }
+        })();
+        try {
+            await sseConnect;
         }
-        const sessionHeader = res.headers.get('mcp-session-id');
-        if (sessionHeader) {
-            remoteSessionId = sessionHeader;
+        catch (err) {
+            sseConnect = undefined;
+            sseEndpoint = undefined;
+            throw err;
         }
-        if (res.status === 202)
-            return undefined;
-        if (!res.ok) {
-            const text = await res.text();
-            logger('info', `Remote error: ${String(res.status)} ${text.slice(0, 200)}`);
-            return {
-                jsonrpc: '2.0',
-                id: hasRequestId(msg) ? msg.id : null,
-                error: { code: -32000, message: `Remote server error: ${String(res.status)}` },
+    }
+    async function sendOverLegacySse(msg, ctx, signal) {
+        await connectLegacySse(ctx, signal);
+        assertLegacySessionAffinity(ctx);
+        assertLegacySseAffinity(ctx);
+        const endpoint = sseEndpoint;
+        if (!endpoint)
+            throw new Error('Legacy SSE endpoint is unavailable');
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const postController = new AbortController();
+            const postTimeout = setTimeout(() => { postController.abort(new Error('Request timeout')); }, REQUEST_TIMEOUT_MS);
+            postTimeout.unref();
+            const settle = (response) => {
+                if (settled)
+                    return;
+                settled = true;
+                ssePending.delete(msg.id);
+                clearTimeout(timer);
+                clearTimeout(postTimeout);
+                signal?.removeEventListener('abort', onAbort);
+                activeFetches.delete(postController);
+                resolve(response);
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                ssePending.delete(msg.id);
+                clearTimeout(timer);
+                clearTimeout(postTimeout);
+                signal?.removeEventListener('abort', onAbort);
+                activeFetches.delete(postController);
+                reject(error);
+            };
+            const timer = setTimeout(() => {
+                settle({
+                    jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'Request timeout' },
+                });
+            }, REQUEST_TIMEOUT_MS);
+            const onAbort = () => {
+                postController.abort(signal?.reason);
+                settle({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'Request cancelled' } });
             };
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+            ssePending.set(msg.id, { resolve: settle, reject: fail, timer });
+            const requestHeaders = sseHeaders(ctx);
+            requestHeaders.set('Content-Type', 'application/json');
+            requestHeaders.set('Mcp-Method', msg.method ?? '');
+            if (requestName(msg) !== undefined)
+                requestHeaders.set('Mcp-Name', mcpNameHeaderValue(msg));
+            if (remoteSessionId)
+                requestHeaders.set('Mcp-Session-Id', remoteSessionId);
+            activeFetches.add(postController);
+            const postMessage = async (retryCount = 0) => {
+                const response = await fetch(endpoint, {
+                    method: 'POST', headers: requestHeaders, body: JSON.stringify(msg), signal: postController.signal, redirect: 'error',
+                });
+                if (response.ok || response.status === 202) {
+                    await drainBoundedResponse(response, postController);
+                    return;
+                }
+                if (response.status === 401 || isInsufficientScopeChallenge(response.status, response.headers.get('www-authenticate') ?? undefined)) {
+                    const wwwAuth = response.headers.get('www-authenticate') ?? undefined;
+                    if (authMode === 'passthrough') {
+                        await drainBoundedResponse(response, postController);
+                        fail(new UnauthorizedError(wwwAuth, response.status));
+                        return;
+                    }
+                    if (!oauthClient || retryCount === 2) {
+                        await drainBoundedResponse(response, postController);
+                        fail(new UnauthorizedError(wwwAuth, response.status));
+                        return;
+                    }
+                    await drainBoundedResponse(response, postController);
+                    await refreshAfterUnauthorized(wwwAuth, postController.signal);
+                    if (accessToken)
+                        requestHeaders.set('Authorization', `Bearer ${accessToken}`);
+                    await postMessage(retryCount + 1);
+                    return;
+                }
+                let text;
+                try {
+                    text = await readBoundedResponseText(response, postController);
+                }
+                catch (err) {
+                    if (err instanceof UpstreamBodyTooLargeError) {
+                        settle({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: err.message } });
+                        return;
+                    }
+                    throw err;
+                }
+                settle({ jsonrpc: '2.0', id: msg.id, error: {
+                        code: -32000, message: `Legacy SSE message post failed: ${String(response.status)} ${text.slice(0, 200)}`,
+                    } });
+            };
+            void postMessage().catch((err) => {
+                if (postController.signal.aborted)
+                    return;
+                fail(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    async function sendLegacySseNotification(msg, ctx, signal) {
+        await connectLegacySse(ctx, signal);
+        assertLegacySessionAffinity(ctx);
+        assertLegacySseAffinity(ctx);
+        const endpoint = sseEndpoint;
+        if (!endpoint)
+            throw new Error('Legacy SSE endpoint is unavailable');
+        const controller = new AbortController();
+        const abortFromCaller = () => { controller.abort(signal?.reason); };
+        if (signal?.aborted)
+            controller.abort(signal.reason);
+        else
+            signal?.addEventListener('abort', abortFromCaller, { once: true });
+        const timeout = setTimeout(() => { controller.abort(new Error('Request timeout')); }, REQUEST_TIMEOUT_MS);
+        timeout.unref();
+        activeFetches.add(controller);
+        try {
+            for (let retryCount = 0; retryCount <= 2; retryCount += 1) {
+                const requestHeaders = sseHeaders(ctx);
+                requestHeaders.set('Content-Type', 'application/json');
+                requestHeaders.set('Mcp-Method', msg.method ?? '');
+                if (requestName(msg) !== undefined)
+                    requestHeaders.set('Mcp-Name', mcpNameHeaderValue(msg));
+                if (remoteSessionId)
+                    requestHeaders.set('Mcp-Session-Id', remoteSessionId);
+                const response = await fetch(endpoint, {
+                    method: 'POST', headers: requestHeaders, body: JSON.stringify(msg), signal: controller.signal, redirect: 'error',
+                });
+                if (response.status === 401 || isInsufficientScopeChallenge(response.status, response.headers.get('www-authenticate') ?? undefined)) {
+                    const wwwAuth = response.headers.get('www-authenticate') ?? undefined;
+                    if (authMode === 'passthrough') {
+                        await drainBoundedResponse(response, controller);
+                        throw new UnauthorizedError(wwwAuth, response.status);
+                    }
+                    if (!oauthClient || retryCount === 2) {
+                        await drainBoundedResponse(response, controller);
+                        throw new UnauthorizedError(wwwAuth, response.status);
+                    }
+                    await drainBoundedResponse(response, controller);
+                    await refreshAfterUnauthorized(wwwAuth, controller.signal);
+                    continue;
+                }
+                if (!response.ok && response.status !== 202) {
+                    try {
+                        await readBoundedResponseText(response, controller);
+                    }
+                    catch (err) {
+                        if (err instanceof UpstreamBodyTooLargeError)
+                            throw err;
+                    }
+                    throw new Error(`Legacy SSE notification post failed: ${String(response.status)}`);
+                }
+                await drainBoundedResponse(response, controller);
+                return;
+            }
         }
-        const contentType = res.headers.get('content-type') ?? '';
-        // SSE response: parse events and extract JSON-RPC messages
-        if (contentType.includes('text/event-stream')) {
-            return await parseSseResponse(res, msg, backend, logger);
+        finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', abortFromCaller);
+            activeFetches.delete(controller);
         }
-        return await res.json();
     }
     const backend = {
+        era: 'legacy',
+        ready: Promise.resolve(),
+        beginReadiness() { return this.ready; },
         onServerMessage: null,
         onClose: null,
-        async sendRequest(msg, ctx) {
-            const response = await forwardToRemote(msg, ctx);
+        async sendRequest(msg, ctx, signal, onEvent, onResponseStart) {
+            if (transport === 'sse')
+                return sendOverLegacySse(msg, ctx, signal);
+            const response = await forwardToRemote(msg, ctx, 0, signal, onEvent, onResponseStart);
             return response ?? { jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: 'No response from remote' } };
         },
-        sendNotification(msg, ctx) {
-            forwardToRemote(msg, ctx).catch((err) => {
+        sendNotification(msg, ctx, signal) {
+            if (transport === 'sse') {
+                void sendLegacySseNotification(msg, ctx, signal).catch((err) => {
+                    logger('debug', `Notification forward failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+                return;
+            }
+            forwardToRemote(msg, ctx, 0, signal).catch((err) => {
                 const errMsg = err instanceof Error ? err.message : String(err);
                 logger('debug', `Notification forward failed: ${errMsg}`);
             });
         },
         close() {
+            sseController?.abort();
+            for (const [id, pending] of ssePending) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error(`Gateway stopped while waiting for legacy SSE request ${String(id)}`));
+            }
+            ssePending.clear();
+            for (const controller of activeFetches)
+                controller.abort();
+            activeFetches.clear();
             // Send DELETE to close remote session
-            if (remoteSessionId) {
+            if (backend.era === 'legacy' && remoteSessionId) {
                 const reqHeaders = { ...headers, 'Mcp-Session-Id': remoteSessionId };
-                if (accessToken)
+                if (authMode === 'passthrough') {
+                    if (remoteSessionAuthorization)
+                        reqHeaders['Authorization'] = remoteSessionAuthorization;
+                }
+                else if (accessToken) {
                     reqHeaders['Authorization'] = `Bearer ${accessToken}`;
-                void fetch(remoteUrl, { method: 'DELETE', headers: reqHeaders }).catch(() => { });
+                }
+                void fetch(remoteUrl, {
+                    method: 'DELETE',
+                    headers: reqHeaders,
+                    signal: AbortSignal.timeout(BACKEND_PROBE_TIMEOUT_MS),
+                    redirect: 'error',
+                }).then((response) => drainBoundedResponse(response)).catch(() => { });
             }
         },
     };
@@ -337,6 +1520,7 @@ export function createGateway(options) {
     const logLevel = options.logLevel ?? 'info';
     const { port } = options;
     const sessions = new Map();
+    const subscriptions = new Map();
     const proxyAuthMode = options.mode === 'proxy'
         ? options.authMode ?? 'managed'
         : 'managed';
@@ -355,27 +1539,209 @@ export function createGateway(options) {
     let nextRequestId = 1;
     let restartBackoff = 1000;
     let restartTimer = null;
+    function requestedNotifications(params) {
+        if (!isRecord(params) || !isRecord(params['notifications']))
+            return {};
+        // Local synthesis can only relay notifications it receives, but must not
+        // erase extension filters before the acknowledgement establishes what the
+        // caller asked to observe.
+        return { ...params['notifications'] };
+    }
+    function subscriptionMatches(subscription, message) {
+        const method = message.method;
+        if (!method?.startsWith('notifications/'))
+            return false;
+        const shortMethod = method.slice('notifications/'.length);
+        if (subscription.notifications[method] === true || subscription.notifications[shortMethod] === true)
+            return true;
+        const listChange = /^(.+)\/list_changed$/.exec(shortMethod);
+        if (listChange) {
+            const category = listChange[1]?.replace(/[-_/.](.)/g, (_whole, character) => character.toUpperCase());
+            if (category && subscription.notifications[`${category}ListChanged`] === true)
+                return true;
+        }
+        if (method !== 'notifications/resources/updated' || !isRecord(message.params))
+            return false;
+        const uris = subscription.notifications['resourceSubscriptions'];
+        return Array.isArray(uris) && typeof message.params['uri'] === 'string'
+            && uris.includes(message.params['uri']);
+    }
+    function closeSubscription(id) {
+        const subscription = subscriptions.get(id);
+        if (!subscription)
+            return;
+        clearInterval(subscription.keepAlive);
+        subscriptions.delete(id);
+        if (subscription.sessionId)
+            sessions.get(subscription.sessionId)?.subscriptions.delete(id);
+        void subscription.writer.end();
+    }
+    function publishChangeNotification(message) {
+        // A legacy backend has no request correlation. Deliver notifications only
+        // to explicit subscriptions whose standard or extension filter matches.
+        if (hasRequestId(message)) {
+            logger('debug', `Dropping server-initiated request ${message.method ?? '<unknown>'}`);
+            return;
+        }
+        if (!message.method?.startsWith('notifications/')) {
+            logger('debug', `Dropping uncorrelated server notification ${message.method ?? '<unknown>'}`);
+            return;
+        }
+        for (const subscription of [...subscriptions.values()]) {
+            if (!subscriptionMatches(subscription, message))
+                continue;
+            const params = isRecord(message.params) ? message.params : {};
+            const tagged = {
+                ...message,
+                params: { ...params, _meta: {
+                        ...(isRecord(params['_meta']) ? params['_meta'] : {}),
+                        [SUBSCRIPTION_ID_META]: subscription.id,
+                    } },
+            };
+            if (!subscription.writer.writeMessage(tagged))
+                closeSubscription(subscription.key);
+        }
+    }
+    function openSubscription(res, params, sessionId, id, owner = sessionId ?? randomUUID()) {
+        // A subscription may remain quiet for a long time. Flush the headers now
+        // so the client has an established stream before its first notification.
+        res.flushHeaders();
+        const key = `${owner}:${typeof id}:${String(id)}`;
+        const writer = createSseWriter(res);
+        const subscription = {
+            key,
+            owner,
+            id,
+            notifications: requestedNotifications(params),
+            response: res,
+            writer,
+            keepAlive: setInterval(() => {
+                if (!writer.writeComment())
+                    closeSubscription(key);
+            }, SSE_KEEP_ALIVE_MS),
+        };
+        if (sessionId)
+            subscription.sessionId = sessionId;
+        subscription.keepAlive.unref();
+        // Reusing a wire id replaces only a stream owned by the same legacy
+        // session. Modern request-scoped streams receive a unique owner instead.
+        closeSubscription(key);
+        subscriptions.set(key, subscription);
+        if (sessionId)
+            sessions.get(sessionId)?.subscriptions.add(key);
+        // The acknowledgement establishes the subscription's correlation before
+        // any change notification can be written to this stream.
+        writer.writeMessage({
+            jsonrpc: '2.0',
+            method: 'notifications/subscriptions/acknowledged',
+            params: { _meta: { [SUBSCRIPTION_ID_META]: id }, notifications: subscription.notifications },
+        });
+        res.on('close', () => { closeSubscription(key); });
+    }
+    async function negotiateBackend(candidate, requestCtx) {
+        const discover = async (protocolVersion) => {
+            const requestId = nextRequestId++;
+            const response = await probeTimeout((signal) => candidate.sendRequest({
+                jsonrpc: '2.0',
+                id: requestId,
+                method: 'server/discover',
+                params: {
+                    _meta: {
+                        'io.modelcontextprotocol/protocolVersion': protocolVersion,
+                        'io.modelcontextprotocol/clientInfo': requestCtx?.clientInfo ?? GATEWAY_CLIENT_INFO,
+                        'io.modelcontextprotocol/clientCapabilities': requestCtx?.clientCapabilities ?? {},
+                    },
+                },
+            }, {
+                ...requestCtx,
+                protocolVersion,
+                mcpParamHeaders: requestCtx?.mcpParamHeaders ?? [],
+            }, signal));
+            return { requestId, response };
+        };
+        const initialVersion = SUPPORTED_MODERN_PROTOCOL_VERSIONS[0];
+        if (initialVersion === undefined)
+            return;
+        const initial = await discover(initialVersion);
+        const initialResponse = initial.response;
+        const initialVersionSelection = modernDiscoveryVersion(initialResponse, initial.requestId);
+        if (initialVersionSelection) {
+            candidate.era = 'modern';
+            candidate.protocolVersion = initialVersionSelection;
+            return;
+        }
+        if (isModernMissingDiscoveryMethod(initialResponse, initial.requestId)) {
+            candidate.era = 'modern';
+            candidate.protocolVersion = initialVersion;
+            return;
+        }
+        const retryVersion = modernErrorDiscoveryVersion(initialResponse, initial.requestId);
+        if (retryVersion) {
+            candidate.era = 'modern';
+            candidate.protocolVersion = initialVersion;
+            const retry = await discover(retryVersion);
+            const retryVersionSelection = modernDiscoveryVersion(retry.response, retry.requestId);
+            if (retryVersionSelection) {
+                candidate.protocolVersion = retryVersionSelection;
+                return;
+            }
+            // A recognized modern error must never make this backend look legacy.
+            candidate.protocolVersion = retryVersion;
+            logger('info', 'Modern backend rejected the selected discovery version');
+            return;
+        }
+        if (isRecognizableModernProbeError(initialResponse, initial.requestId)) {
+            candidate.era = 'modern';
+            candidate.protocolVersion = initialVersion;
+            logger('info', 'Modern backend rejected discovery without a compatible version');
+            return;
+        }
+        candidate.era = 'legacy';
+        const initializeRequestId = nextRequestId++;
+        const initializeResponse = await candidate.sendRequest({
+            jsonrpc: '2.0',
+            id: initializeRequestId,
+            method: 'initialize',
+            params: {
+                protocolVersion: LEGACY_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: GATEWAY_CLIENT_INFO,
+            },
+        }, {
+            ...requestCtx,
+            protocolVersion: LEGACY_PROTOCOL_VERSION,
+            mcpParamHeaders: requestCtx?.mcpParamHeaders ?? [],
+        });
+        if (isLegacyInitializeResponse(initializeResponse, initializeRequestId)) {
+            candidate.initializeResult = initializeResponse.result;
+            candidate.sendNotification({
+                jsonrpc: '2.0',
+                method: 'notifications/initialized',
+                params: {},
+            }, {
+                ...requestCtx,
+                protocolVersion: LEGACY_PROTOCOL_VERSION,
+                mcpParamHeaders: requestCtx?.mcpParamHeaders ?? [],
+            });
+            return;
+        }
+        logger('info', 'Legacy backend initialization failed');
+    }
     function startBackend() {
         let b;
         if (options.mode === 'stdio') {
-            b = createStdioBackend(options.command, logger);
+            b = createStdioBackend(options.command, options.args ?? [], logger);
         }
         else {
-            b = createProxyBackend(options.url, options.headers ?? {}, proxyAuthMode, sharedOAuthClient, logger);
+            b = createProxyBackend(options.url, options.transport ?? 'http', options.headers ?? {}, proxyAuthMode, sharedOAuthClient, logger);
         }
         b.onServerMessage = (msg) => {
-            for (const session of sessions.values()) {
-                if (session.liveSSE && sendSSE(session.liveSSE, msg))
-                    continue;
-                if (session.liveSSE)
-                    session.liveSSE = null;
-                if (session.notificationBuffer.length < MAX_NOTIFICATION_BUFFER) {
-                    session.notificationBuffer.push(msg);
-                }
-            }
+            publishChangeNotification(msg);
         };
         b.onClose = () => {
             logger('info', `Backend died, restarting in ${String(restartBackoff)}ms`);
+            for (const subscriptionId of [...subscriptions.keys()])
+                closeSubscription(subscriptionId);
             sessions.clear();
             restartTimer = setTimeout(() => {
                 restartTimer = null;
@@ -383,18 +1749,158 @@ export function createGateway(options) {
                 restartBackoff = Math.min(restartBackoff * 2, 30_000);
             }, restartBackoff);
         };
+        let readiness;
+        let readinessAuthorization;
+        let hasReadinessAuthorization = false;
+        b.beginReadiness = (ctx) => {
+            // Legacy negotiation itself creates/uses the one shared upstream
+            // session. Serialize its credential ownership before the probe reveals
+            // the backend era, otherwise two concurrent callers could race an
+            // initialize challenge with different Authorization values.
+            if (options.mode === 'proxy' && proxyAuthMode === 'passthrough'
+                && (readiness !== undefined || b.era === 'legacy')) {
+                if (!hasReadinessAuthorization) {
+                    readinessAuthorization = ctx?.authorization;
+                    hasReadinessAuthorization = true;
+                }
+                else if (readinessAuthorization !== ctx?.authorization) {
+                    return Promise.reject(new CredentialAffinityError());
+                }
+            }
+            if (!readiness) {
+                const sharedReadiness = negotiateBackend(b, ctx).catch((err) => {
+                    if (err instanceof UnauthorizedError) {
+                        // The request that triggered the probe must receive the upstream
+                        // challenge. Do not classify the endpoint from an unauthenticated
+                        // probe; a later request may supply a valid credential.
+                        throw err;
+                    }
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    // Negotiation must not prevent a restarted gateway from serving a
+                    // backend that comes up later. Treat unexpected probe failures like the
+                    // documented legacy fallback, while retaining the diagnostic.
+                    b.era = 'legacy';
+                    logger('info', `Backend negotiation failed: ${errMsg}`);
+                });
+                readiness = sharedReadiness;
+                void sharedReadiness.catch(() => {
+                    // Only clear the attempt that failed. Requests which joined it see
+                    // the same challenge, while the next request can negotiate again.
+                    if (readiness === sharedReadiness) {
+                        readiness = undefined;
+                        b.ready = Promise.resolve();
+                        // A 401 during probing has not created a usable upstream session.
+                        // Release its tentative owner so the client can answer the
+                        // challenge with a different credential on the next request.
+                        hasReadinessAuthorization = false;
+                        readinessAuthorization = undefined;
+                    }
+                });
+                void sharedReadiness.then(() => {
+                    // Modern HTTP has no shared server-side legacy session, so callers
+                    // may independently use their own passthrough credentials.
+                    if (b.era === 'modern') {
+                        hasReadinessAuthorization = false;
+                        readinessAuthorization = undefined;
+                    }
+                }).catch(() => { });
+            }
+            b.ready = readiness;
+            return readiness;
+        };
+        if (options.mode === 'stdio')
+            void b.beginReadiness();
         return b;
     }
     let backend = startBackend();
-    async function sendRequest(msg, ctx) {
+    function resetAbandonedLegacyProxyBackend(candidate) {
+        if (options.mode !== 'proxy' || candidate !== backend || candidate.era !== 'legacy' || sessions.size !== 0)
+            return;
+        // The first readiness handshake may have created a credential-bound remote
+        // session before its downstream initializer disconnected. Close that
+        // orphan and replace the backend so a later caller is not affinity-blocked.
+        candidate.close();
+        backend = startBackend();
+    }
+    async function sendRequest(msg, ctx, clientEra = 'legacy', signal, onEvent, onResponseStart) {
+        const currentBackend = backend;
+        await currentBackend.beginReadiness(ctx);
+        if (currentBackend.era === 'modern' && clientEra === 'legacy') {
+            if (msg.method === 'ping')
+                return { jsonrpc: '2.0', id: msg.id, result: {} };
+            if (msg.method === 'logging/setLevel' || msg.method === 'notifications/roots/list_changed') {
+                return { jsonrpc: '2.0', id: msg.id, result: {} };
+            }
+        }
         const originalId = msg.id;
-        const internalId = nextRequestId++;
-        const response = await backend.sendRequest({ ...msg, id: internalId }, ctx);
+        // Modern HTTP is request-scoped. Retaining its client request id keeps a
+        // relayed subscriptions/listen stream transparent: the upstream
+        // acknowledgement and all notifications use the caller's subscription id.
+        const internalId = currentBackend.era === 'modern'
+            ? originalId : nextRequestId++;
+        const outgoing = currentBackend.era === 'legacy' && clientEra === 'modern'
+            ? stripModernMeta(msg)
+            : currentBackend.era === 'modern' && clientEra === 'legacy'
+                ? injectModernMeta(msg, currentBackend.protocolVersion ?? CURRENT_MODERN_PROTOCOL_VERSION, ctx?.clientCapabilities ?? {}, ctx?.clientInfo ?? GATEWAY_CLIENT_INFO)
+                : msg;
+        const outgoingCtx = currentBackend.era === 'legacy' && clientEra === 'modern'
+            ? { ...ctx, protocolVersion: LEGACY_PROTOCOL_VERSION, mcpParamHeaders: ctx?.mcpParamHeaders ?? [] }
+            : currentBackend.era === 'modern' && clientEra === 'legacy'
+                ? {
+                    ...ctx,
+                    protocolVersion: currentBackend.protocolVersion ?? CURRENT_MODERN_PROTOCOL_VERSION,
+                    mcpParamHeaders: ctx?.mcpParamHeaders ?? [],
+                }
+                : ctx;
+        const response = await currentBackend.sendRequest({ ...outgoing, id: internalId }, outgoingCtx, signal, onEvent, onResponseStart);
         restartBackoff = 1000;
-        return { ...response, id: originalId };
+        if (!isMatchingResponse(response, internalId)) {
+            return {
+                jsonrpc: '2.0',
+                id: originalId,
+                error: { code: -32603, message: 'Remote server returned a response with an unexpected id' },
+            };
+        }
+        const transformedBase = { ...transformBackendResponse(response, msg.method, clientEra, currentBackend.era), id: originalId };
+        const transformed = clientEra === 'modern' ? ensureModernCompleteResult(transformedBase) : transformedBase;
+        // Cross-era bridges synthesize protocol responses. Same-era HTTP proxy
+        // responses may retain the safe status and headers from upstream.
+        const meta = responseMeta(response);
+        if (meta && currentBackend.era === clientEra) {
+            Object.defineProperty(transformed, HTTP_RESPONSE_META, { value: meta, enumerable: false });
+        }
+        return transformed;
     }
-    function sendNotification(msg, ctx) {
-        backend.sendNotification(msg, ctx);
+    function sendNotification(msg, ctx, clientEra = 'legacy', signal) {
+        const currentBackend = backend;
+        void currentBackend.beginReadiness(ctx).then(() => {
+            if (currentBackend.era === 'modern' && clientEra === 'legacy' && (msg.method === 'ping'
+                || msg.method === 'logging/setLevel'
+                || msg.method === 'notifications/roots/list_changed'
+                || msg.method === 'notifications/initialized'))
+                return;
+            const outgoing = currentBackend.era === 'legacy' && clientEra === 'modern'
+                ? stripModernMeta(msg)
+                : currentBackend.era === 'modern' && clientEra === 'legacy'
+                    ? injectModernMeta(msg, currentBackend.protocolVersion ?? CURRENT_MODERN_PROTOCOL_VERSION, ctx?.clientCapabilities ?? {}, ctx?.clientInfo ?? GATEWAY_CLIENT_INFO)
+                    : msg;
+            const outgoingCtx = currentBackend.era === 'legacy' && clientEra === 'modern'
+                ? { ...ctx, protocolVersion: LEGACY_PROTOCOL_VERSION, mcpParamHeaders: ctx?.mcpParamHeaders ?? [] }
+                : currentBackend.era === 'modern' && clientEra === 'legacy'
+                    ? {
+                        ...ctx,
+                        protocolVersion: currentBackend.protocolVersion ?? CURRENT_MODERN_PROTOCOL_VERSION,
+                        mcpParamHeaders: ctx?.mcpParamHeaders ?? [],
+                    }
+                    : ctx;
+            currentBackend.sendNotification(outgoing, outgoingCtx, signal);
+        }).catch((err) => {
+            // Notifications deliberately have no response channel.  They must still
+            // observe readiness/auth failures so a rejected probe never becomes an
+            // unhandled rejection that terminates Node.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logger('debug', `Notification forward failed: ${errMsg}`);
+        });
     }
     function writeUnauthorized(res, err, requestId) {
         if (res.headersSent)
@@ -402,81 +1908,121 @@ export function createGateway(options) {
         const respHeaders = { 'Content-Type': 'application/json' };
         if (err.wwwAuthenticate)
             respHeaders['WWW-Authenticate'] = err.wwwAuthenticate;
-        res.writeHead(401, respHeaders);
+        res.writeHead(err.status, respHeaders);
         res.end(JSON.stringify({
             jsonrpc: '2.0',
             id: requestId,
-            error: { code: -32001, message: 'Unauthorized' },
+            error: { code: -32001, message: err.status === 403 ? 'Forbidden' : 'Unauthorized' },
         }));
     }
-    async function handleRequestOverSSE(res, message, session, ctx) {
-        // Passthrough mode delays SSE headers so a 401 from upstream can still
-        // surface as an HTTP 401 to the client (re-auth requires this).
-        if (proxyAuthMode === 'passthrough') {
-            let response;
-            try {
-                response = await sendRequest(message, ctx);
+    function writeCredentialConflict(res, requestId) {
+        if (res.headersSent)
+            return;
+        res.writeHead(409, { 'Content-Type': 'application/json' });
+        res.end(makeErrorResponse(requestId, -32000, 'The shared legacy upstream session belongs to another credential; close it before switching credentials'));
+    }
+    async function handleRequestOverSSE(res, message, session, ctx, clientEra) {
+        const controller = new AbortController();
+        const detach = () => { controller.abort(); };
+        res.on('close', detach);
+        let writer;
+        let headersStarted = false;
+        let preHeaderEvents = [];
+        let preHeaderBytes = 0;
+        const start = (meta) => {
+            if (headersStarted || res.destroyed || res.writableEnded)
+                return;
+            const headers = {
+                ...(meta?.headers ?? {}),
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': meta?.headers['cache-control'] ?? 'no-cache',
+                'X-Accel-Buffering': 'no',
+            };
+            if (clientEra === 'legacy' && session)
+                headers['Mcp-Session-Id'] = session.id;
+            res.writeHead(meta?.status ?? 200, headers);
+            writer = createSseWriter(res);
+            headersStarted = true;
+            for (const event of preHeaderEvents) {
+                if (!writer.writeMessage(event))
+                    break;
             }
-            catch (err) {
-                if (err instanceof UnauthorizedError) {
-                    writeUnauthorized(res, err, message.id);
-                    return;
-                }
-                throw err;
+            preHeaderEvents = [];
+            preHeaderBytes = 0;
+        };
+        const sink = (event) => {
+            if (writer) {
+                if (!writer.writeMessage(event))
+                    controller.abort(new Error('SSE downstream closed'));
+                return;
             }
-            res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                'Mcp-Session-Id': session.id,
-            });
-            const pending = session.notificationBuffer;
-            session.notificationBuffer = [];
-            for (const notif of pending)
-                sendSSE(res, notif);
-            sendSSE(res, response);
-            res.end();
-            return;
-        }
-        res.writeHead(200, {
-            'Content-Type': 'text/event-stream',
-            'Cache-Control': 'no-cache',
-            'Mcp-Session-Id': session.id,
-        });
-        const pending = session.notificationBuffer;
-        session.notificationBuffer = [];
-        for (const notif of pending)
-            sendSSE(res, notif);
-        session.liveSSE = res;
-        const detachIfOwned = () => {
-            if (session.liveSSE === res)
-                session.liveSSE = null;
+            const bytes = Buffer.byteLength(JSON.stringify(event));
+            if (preHeaderBytes + bytes > MAX_PRE_HEADER_EVENT_BYTES) {
+                controller.abort(new Error('SSE pre-header queue exceeded gateway limit'));
+                res.destroy();
+                return;
+            }
+            preHeaderEvents.push(event);
+            preHeaderBytes += bytes;
         };
-        res.on('close', detachIfOwned);
         try {
-            const response = await sendRequest(message, ctx);
-            sendSSE(res, response);
+            const response = await sendRequest(message, ctx, clientEra, controller.signal, sink, start);
+            const meta = responseMeta(response);
+            start(meta);
+            writer?.writeMessage(response);
         }
         catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            sendSSE(res, {
+            if (err instanceof UnauthorizedError) {
+                writeUnauthorized(res, err, message.id);
+                return;
+            }
+            if (err instanceof CredentialAffinityError) {
+                writeCredentialConflict(res, message.id);
+                return;
+            }
+            logger('info', `Request failed before an SSE response could complete (${err instanceof Error ? err.name : 'Error'})`);
+            start();
+            writer?.writeMessage({
                 jsonrpc: '2.0',
                 id: message.id,
-                error: { code: -32603, message: errMsg },
+                error: { code: -32603, message: 'Gateway request failed' },
             });
         }
         finally {
-            res.removeListener('close', detachIfOwned);
-            detachIfOwned();
-            res.end();
+            res.removeListener('close', detach);
+            await writer?.end();
+            if (!writer && !res.writableEnded && !res.destroyed)
+                res.end();
         }
     }
     function respondWithJson(res, response, sessionId) {
-        res.writeHead(200, { 'Content-Type': 'application/json', 'Mcp-Session-Id': sessionId });
+        const meta = responseMeta(response);
+        const headers = { 'Content-Type': 'application/json', ...(meta?.headers ?? {}) };
+        if (sessionId)
+            headers['Mcp-Session-Id'] = sessionId;
+        res.writeHead(meta?.status ?? 200, headers);
         res.end(JSON.stringify(response));
     }
     // --- HTTP handlers ---
     async function handlePost(req, res) {
-        const body = await readBody(req);
+        const requestController = new AbortController();
+        const abortRequest = () => {
+            // `close` also follows a normal res.end().  Only treat it as a client
+            // disconnect while the gateway has not completed the downstream reply.
+            if (!res.writableFinished)
+                requestController.abort(new Error('Gateway client disconnected'));
+        };
+        req.once('aborted', abortRequest);
+        res.once('close', abortRequest);
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch {
+            res.writeHead(413, { 'Content-Type': 'application/json' });
+            res.end(makeErrorResponse(null, -32600, 'Request body exceeds gateway limit'));
+            return;
+        }
         let message;
         try {
             message = JSON.parse(body);
@@ -486,40 +2032,212 @@ export function createGateway(options) {
             res.end(makeErrorResponse(null, -32700, 'Parse error'));
             return;
         }
-        if (!isJsonRpcMessage(message)) {
+        if (!isJsonRpcRequest(message)) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(makeErrorResponse(null, -32600, 'Invalid Request'));
             return;
         }
         const authHeader = req.headers.authorization;
-        const ctx = {};
+        const protocolVersionHeader = req.headers['mcp-protocol-version'];
+        const ctx = { mcpParamHeaders: [] };
         if (typeof authHeader === 'string')
             ctx.authorization = authHeader;
+        if (typeof protocolVersionHeader === 'string')
+            ctx.protocolVersion = protocolVersionHeader;
+        if (typeof req.headers.accept === 'string')
+            ctx.accept = req.headers.accept;
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+            const name = req.rawHeaders[i];
+            const value = req.rawHeaders[i + 1];
+            if (name?.toLowerCase().startsWith('mcp-param-') && value !== undefined) {
+                ctx.mcpParamHeaders.push([name, value]);
+            }
+        }
+        const modernClient = isModernClientRequest(message, protocolVersionHeader);
+        if (modernClient) {
+            const methodHeader = req.headers['mcp-method'];
+            const nameHeader = req.headers['mcp-name'];
+            const method = typeof methodHeader === 'string' ? methodHeader : undefined;
+            const encodedName = typeof nameHeader === 'string' ? nameHeader : undefined;
+            const decodedName = encodedName === undefined ? undefined : decodedMcpNameHeader(encodedName);
+            const protocolVersion = typeof protocolVersionHeader === 'string' ? protocolVersionHeader : undefined;
+            const expectedName = requestName(message);
+            if (!protocolVersion || !method || method !== message.method
+                || (requiresMcpName(message.method)
+                    ? expectedName === undefined || encodedName === undefined || decodedName === undefined || decodedName !== expectedName
+                    : encodedName !== undefined)
+                || !hasModernProtocolMeta(message, protocolVersion)
+                || !hasValidModernClientMetadata(message)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(makeErrorResponse(message.id ?? null, -32020, 'MCP request headers do not match the JSON-RPC body'));
+                return;
+            }
+            if (!hasRequiredModernClientCapabilities(message)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(makeErrorResponse(message.id ?? null, -32021, 'MissingRequiredClientCapability'));
+                return;
+            }
+            if (!SUPPORTED_MODERN_PROTOCOL_VERSIONS.includes(protocolVersion)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: message.id ?? null,
+                    error: {
+                        code: -32022,
+                        message: 'Unsupported protocol version',
+                        data: { supported: SUPPORTED_MODERN_PROTOCOL_VERSIONS, requested: protocolVersion },
+                    },
+                }));
+                return;
+            }
+            if (message.method === 'subscriptions/listen') {
+                if (!hasRequestId(message)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(makeErrorResponse(null, -32600, 'subscriptions/listen requires a request id'));
+                    return;
+                }
+                try {
+                    const currentBackend = backend;
+                    await currentBackend.beginReadiness(ctx);
+                    if (currentBackend.era === 'legacy') {
+                        res.writeHead(200, {
+                            'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no',
+                        });
+                        openSubscription(res, message.params, undefined, message.id);
+                    }
+                    else {
+                        await handleRequestOverSSE(res, message, undefined, ctx, 'modern');
+                    }
+                }
+                catch (err) {
+                    if (err instanceof UnauthorizedError)
+                        writeUnauthorized(res, err, message.id);
+                    else
+                        throw err;
+                }
+                return;
+            }
+            if (message.method === 'server/discover') {
+                if (!hasRequestId(message)) {
+                    res.writeHead(202);
+                    res.end();
+                    return;
+                }
+                try {
+                    const currentBackend = backend;
+                    await currentBackend.beginReadiness(ctx);
+                    const response = currentBackend.era === 'legacy'
+                        ? { jsonrpc: '2.0', id: message.id, result: discoverFromInitialize(currentBackend.initializeResult) }
+                        : await sendRequest(message, ctx, 'modern', requestController.signal);
+                    respondWithJson(res, response);
+                }
+                catch (err) {
+                    if (err instanceof UnauthorizedError) {
+                        writeUnauthorized(res, err, message.id);
+                        return;
+                    }
+                    if (err instanceof CredentialAffinityError) {
+                        writeCredentialConflict(res, message.id);
+                        return;
+                    }
+                    throw err;
+                }
+                return;
+            }
+            // initialize was removed from the modern protocol. Do not accidentally
+            // turn it into a legacy session just because the endpoint is shared.
+            if (message.method === 'initialize') {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(makeErrorResponse(message.id ?? null, -32601, 'Method not found'));
+                return;
+            }
+            if (hasRequestId(message)) {
+                const clientAcceptsSSE = (req.headers.accept ?? '').includes('text/event-stream');
+                try {
+                    if (clientAcceptsSSE)
+                        await handleRequestOverSSE(res, message, undefined, ctx, 'modern');
+                    else
+                        respondWithJson(res, await sendRequest(message, ctx, 'modern', requestController.signal));
+                }
+                catch (err) {
+                    if (err instanceof UnauthorizedError) {
+                        writeUnauthorized(res, err, message.id);
+                        return;
+                    }
+                    if (err instanceof CredentialAffinityError) {
+                        writeCredentialConflict(res, message.id);
+                        return;
+                    }
+                    throw err;
+                }
+            }
+            else {
+                sendNotification(message, ctx, 'modern', requestController.signal);
+                res.writeHead(202);
+                res.end();
+            }
+            return;
+        }
         if (message.method === 'initialize') {
             const session = {
                 id: randomUUID(),
-                notificationBuffer: [],
-                liveSSE: null,
+                subscriptions: new Set(),
+                clientCapabilities: isRecord(message.params) && isRecord(message.params['capabilities'])
+                    ? message.params['capabilities'] : {},
+                clientInfo: isRecord(message.params) && isRecord(message.params['clientInfo'])
+                    ? message.params['clientInfo'] : GATEWAY_CLIENT_INFO,
             };
             sessions.set(session.id, session);
+            ctx.clientCapabilities = session.clientCapabilities;
+            ctx.clientInfo = session.clientInfo;
             logger('info', `Session ${session.id.slice(0, 8)} created (${String(sessions.size)} active)`);
             try {
                 if (hasRequestId(message)) {
-                    const response = await sendRequest(message, ctx);
+                    const currentBackend = backend;
+                    await currentBackend.beginReadiness(ctx);
+                    // The gateway owns the legacy backend handshake. A legacy client
+                    // still receives its normal initialize result, but its request must
+                    // not open a second backend session.
+                    const response = currentBackend.era === 'legacy' && currentBackend.initializeResult !== undefined
+                        ? { jsonrpc: '2.0', id: message.id, result: currentBackend.initializeResult }
+                        : currentBackend.era === 'modern'
+                            ? await (async () => {
+                                const discovery = await sendRequest({
+                                    jsonrpc: '2.0', id: message.id, method: 'server/discover', params: {},
+                                }, ctx, 'legacy', requestController.signal);
+                                return isRecord(discovery.result)
+                                    ? { jsonrpc: '2.0', id: message.id, result: initializeFromDiscover(discovery.result) }
+                                    : discovery;
+                            })()
+                            : await sendRequest(message, ctx, 'legacy', requestController.signal);
+                    // The downstream transport may close while an abort-aware backend
+                    // resolves with a JSON-RPC cancellation error instead of throwing.
+                    // Never retain a session that was not successfully handed to it.
+                    if (requestController.signal.aborted || res.destroyed || res.writableEnded) {
+                        sessions.delete(session.id);
+                        resetAbandonedLegacyProxyBackend(currentBackend);
+                        return;
+                    }
                     respondWithJson(res, response, session.id);
                 }
                 else {
-                    sendNotification(message, ctx);
+                    sendNotification(message, ctx, 'legacy', requestController.signal);
                     res.writeHead(202, { 'Mcp-Session-Id': session.id });
                     res.end();
                 }
             }
             catch (err) {
                 sessions.delete(session.id);
+                if (requestController.signal.aborted || res.destroyed)
+                    resetAbandonedLegacyProxyBackend(backend);
                 if (err instanceof UnauthorizedError) {
                     writeUnauthorized(res, err, message.id ?? null);
                     return;
                 }
+                if (err instanceof CredentialAffinityError) {
+                    writeCredentialConflict(res, message.id ?? null);
+                    return;
+                }
                 throw err;
             }
             return;
@@ -536,14 +2254,51 @@ export function createGateway(options) {
             res.end(makeErrorResponse(message.id ?? null, -32000, 'Session not found or expired'));
             return;
         }
-        if (hasRequestId(message) && message.method !== undefined) {
+        ctx.clientCapabilities = session.clientCapabilities;
+        ctx.clientInfo = session.clientInfo;
+        if (message.method === 'subscriptions/listen') {
+            if (!hasRequestId(message)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(makeErrorResponse(null, -32600, 'subscriptions/listen requires a request id'));
+                return;
+            }
+            try {
+                const currentBackend = backend;
+                await currentBackend.beginReadiness(ctx);
+                if (currentBackend.era === 'modern') {
+                    await handleRequestOverSSE(res, message, session, ctx, 'legacy');
+                }
+                else {
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        'X-Accel-Buffering': 'no',
+                        'Mcp-Session-Id': session.id,
+                    });
+                    openSubscription(res, message.params, session.id, message.id);
+                }
+            }
+            catch (err) {
+                if (err instanceof UnauthorizedError) {
+                    writeUnauthorized(res, err, message.id);
+                    return;
+                }
+                if (err instanceof CredentialAffinityError) {
+                    writeCredentialConflict(res, message.id);
+                    return;
+                }
+                throw err;
+            }
+            return;
+        }
+        if (hasRequestId(message)) {
             const clientAcceptsSSE = (req.headers.accept ?? '').includes('text/event-stream');
             try {
                 if (clientAcceptsSSE) {
-                    await handleRequestOverSSE(res, message, session, ctx);
+                    await handleRequestOverSSE(res, message, session, ctx, 'legacy');
                 }
                 else {
-                    const response = await sendRequest(message, ctx);
+                    const response = await sendRequest(message, ctx, 'legacy', requestController.signal);
                     respondWithJson(res, response, session.id);
                 }
             }
@@ -552,26 +2307,64 @@ export function createGateway(options) {
                     writeUnauthorized(res, err, message.id);
                     return;
                 }
+                if (err instanceof CredentialAffinityError) {
+                    writeCredentialConflict(res, message.id);
+                    return;
+                }
                 throw err;
             }
             return;
         }
-        sendNotification(message, ctx);
+        if (message.method === 'notifications/initialized') {
+            const currentBackend = backend;
+            try {
+                await currentBackend.beginReadiness(ctx);
+            }
+            catch (err) {
+                if (err instanceof UnauthorizedError) {
+                    writeUnauthorized(res, err, null);
+                    return;
+                }
+                if (err instanceof CredentialAffinityError) {
+                    writeCredentialConflict(res, null);
+                    return;
+                }
+                throw err;
+            }
+            // Legacy backends were already initialized by the gateway during
+            // readiness. Forwarding the client's lifecycle notification would make
+            // the upstream observe the same transition twice.
+            if (currentBackend.era === 'legacy') {
+                res.writeHead(202);
+                res.end();
+                return;
+            }
+        }
+        sendNotification(message, ctx, 'legacy', requestController.signal);
         res.writeHead(202);
         res.end();
     }
     function handleDelete(req, res) {
+        if (isModernProtocolVersion(req.headers['mcp-protocol-version'])) {
+            res.writeHead(405, { 'Content-Type': 'text/plain' });
+            res.end('Method Not Allowed');
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         if (typeof sessionId !== 'string') {
             res.writeHead(400, { 'Content-Type': 'text/plain' });
             res.end('Missing Mcp-Session-Id header');
             return;
         }
-        if (!sessions.delete(sessionId)) {
+        const session = sessions.get(sessionId);
+        if (!session) {
             res.writeHead(404, { 'Content-Type': 'text/plain' });
             res.end('Session not found');
             return;
         }
+        for (const subscriptionId of session.subscriptions)
+            closeSubscription(subscriptionId);
+        sessions.delete(sessionId);
         logger('info', `Session ${sessionId.slice(0, 8)} destroyed (${String(sessions.size)} active)`);
         res.writeHead(200);
         res.end();
@@ -586,15 +2379,37 @@ export function createGateway(options) {
             res.end('Method Not Allowed');
             return;
         }
+        const controller = new AbortController();
+        const abortFromClient = () => {
+            if (!res.writableFinished)
+                controller.abort(new Error('Gateway client disconnected'));
+        };
+        req.once('aborted', abortFromClient);
+        res.once('close', abortFromClient);
+        const timeout = setTimeout(() => { controller.abort(new Error('Protected-resource request timeout')); }, REQUEST_TIMEOUT_MS);
+        timeout.unref();
+        const cleanup = () => {
+            clearTimeout(timeout);
+            req.removeListener('aborted', abortFromClient);
+            res.removeListener('close', abortFromClient);
+        };
         let lastStatus = 404;
         let lastBody = '';
-        let lastContentType = 'application/json';
+        let lastHeaders = { 'content-type': 'application/json' };
         for (const target of upstreamProtectedResourceUrls) {
             let upstream;
             try {
+                const headers = new Headers({
+                    ...(options.mode === 'proxy' ? options.headers ?? {} : {}),
+                    Accept: typeof req.headers.accept === 'string' ? req.headers.accept : 'application/json',
+                });
+                if (typeof req.headers.authorization === 'string')
+                    headers.set('Authorization', req.headers.authorization);
                 upstream = await fetch(target, {
                     method: 'GET',
-                    headers: { 'Accept': 'application/json' },
+                    headers,
+                    signal: controller.signal,
+                    redirect: 'error',
                 });
             }
             catch (err) {
@@ -602,25 +2417,51 @@ export function createGateway(options) {
                 logger('info', `Protected-resource fetch failed (${target}): ${errMsg}`);
                 continue;
             }
-            const text = await upstream.text();
+            let text;
+            try {
+                text = await readBoundedResponseText(upstream, controller);
+            }
+            catch (err) {
+                if (err instanceof UpstreamBodyTooLargeError) {
+                    cleanup();
+                    res.writeHead(502, { 'Content-Type': 'application/json' });
+                    res.end(makeErrorResponse(null, -32603, err.message));
+                    return;
+                }
+                throw err;
+            }
+            const forwardedHeaders = safeResponseHeaders(upstream.headers);
+            forwardedHeaders['content-type'] ??= 'application/json';
             if (upstream.ok) {
-                const ct = upstream.headers.get('content-type') ?? 'application/json';
-                res.writeHead(upstream.status, { 'Content-Type': ct });
+                cleanup();
+                res.writeHead(upstream.status, forwardedHeaders);
                 res.end(text);
                 return;
             }
             lastStatus = upstream.status;
             lastBody = text;
-            lastContentType = upstream.headers.get('content-type') ?? 'application/json';
+            lastHeaders = forwardedHeaders;
         }
-        res.writeHead(lastStatus, { 'Content-Type': lastContentType });
+        cleanup();
+        res.writeHead(lastStatus, lastHeaders);
         res.end(lastBody);
     }
     const httpServer = createHttpServer((req, res) => {
-        res.setHeader('Access-Control-Allow-Origin', '*');
+        const origin = req.headers.origin;
+        if (typeof origin === 'string' && !isSafeLocalOrigin(origin, port)) {
+            // Origin is optional for native MCP clients. When a browser supplies
+            // one, only a literal loopback origin is safe for this local endpoint.
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(makeErrorResponse(null, -32600, 'Forbidden Origin'));
+            return;
+        }
+        if (typeof origin === 'string')
+            res.setHeader('Access-Control-Allow-Origin', origin);
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Accept, Mcp-Session-Id, MCP-Protocol-Version');
-        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, WWW-Authenticate');
+        const requestedHeaders = req.headers['access-control-request-headers'];
+        res.setHeader('Access-Control-Allow-Headers', corsAllowedHeaders(typeof requestedHeaders === 'string' ? requestedHeaders : undefined));
+        res.setHeader('Vary', 'Origin, Access-Control-Request-Headers');
+        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, WWW-Authenticate, MCP-Protocol-Version');
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
             res.end();
@@ -689,9 +2530,16 @@ export function createGateway(options) {
             return new Promise((resolve) => {
                 if (restartTimer)
                     clearTimeout(restartTimer);
+                for (const subscriptionId of [...subscriptions.keys()])
+                    closeSubscription(subscriptionId);
                 sessions.clear();
                 backend.onClose = null;
                 backend.close();
+                // A client can leave a keep-alive connection open after its final
+                // JSON-RPC response. Closing those sockets makes shutdown deterministic
+                // without waiting for the HTTP server's idle timeout.
+                httpServer.closeAllConnections();
+                httpServer.unref();
                 httpServer.close(() => { resolve(); });
             });
         },