@ni-c/mcp-hub 0.9.2 → 0.11.0

package/dist/supervisor.js

@@ -1,21 +1,63 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
+import { Client, StreamableHTTPClientTransport, SSEClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
+import { ListToolsResultSchema } from '@modelcontextprotocol/core';
 import { VERSION } from './version.js';
 import { MAX_TOOL_LIST_PAGES, MAX_TOOLS, MAX_TOOL_METADATA_BYTES, jsonSize } from './mcp-limits.js';
-import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { BACKOFF_INITIAL_MS, BACKOFF_MAX_MS, BACKOFF_RESET_AFTER_MS, IDLE_SWEEP_INTERVAL_MS, MAX_UNUSED_RESTARTS, PING_INTERVAL_MS, PING_TIMEOUT_MS, WAKE_TIMEOUT_MS } from './timings.js';
 import { SocketTransport } from './transports/socket.js';
 import { DockerTransport } from './transports/docker.js';
 import { DockerClient, parseSandboxDockerHost } from './sandbox/docker-client.js';
+import { UpstreamAuth, UpstreamLoginRequiredError } from './upstream/auth.js';
+import { credentialFingerprint } from './upstream/provider.js';
 import { ToolCache } from './tool-cache.js';
+import { filterTools, hasToolFilter, unmatchedPatterns } from './tool-filter.js';
+import { subscriptionsAllowed } from './subscriptions.js';
+/**
+ * Whether a failure is one a restart could fix.
+ *
+ * Only two things mean "a human has to act": our own manager saying there is no
+ * usable credential, and the SDK giving up on authorization. Everything else —
+ * DNS, a 5xx, a timeout — is transient and must keep its backoff, or an
+ * upstream that would have recovered on its own would need manual attention.
+ */
+function classifyAuthFailure(error) {
+    return error instanceof UpstreamLoginRequiredError || error instanceof UnauthorizedError ? 'unauthorized' : 'restart';
+}
+/**
+ * Whether this connection's protocol revision still has `ping`.
+ *
+ * `2026-07-28` removed it. Asked on that era the SDK refuses rather than
+ * sending anything, so a liveness probe there is not a failed ping — it is a
+ * question that no longer exists. Everything older has it.
+ *
+ * Read from the connection rather than from the config, because the era is not
+ * a property of the server we configured: it is the outcome of the opening
+ * exchange with the server that actually answered.
+ */
+function eraHasPing(client) {
+    const era = client.getNegotiatedProtocolVersion?.();
+    // Undefined means the SDK has not recorded one, which is every revision that
+    // predates the negotiation API. Those all have ping.
+    return era === undefined || era < '2026-07-28';
+}
 /**
  * Remote upstreams get their configured headers on EVERY request via a fetch
  * wrapper — requestInit alone does not cover the SSE stream GET.
  */
-function buildRemoteTransport(config) {
+function buildRemoteTransport(config, auth) {
     const url = new URL(config.url);
     const headers = config.headers;
+    if (auth) {
+        // Deliberately no `requestInit`: the transport merges those headers *after*
+        // the OAuth Authorization header, so a static one would win — and the SDK
+        // would carry them to the authorization server as well, because the fetch
+        // it uses for tokens is the same object. The auth manager's own fetch adds
+        // the configured headers to upstream requests only.
+        const guarded = auth.createFetch();
+        return config.transport === 'sse'
+            ? new SSEClientTransport(url, { authProvider: auth.provider(), fetch: guarded })
+            : new StreamableHTTPClientTransport(url, { authProvider: auth.provider(), fetch: guarded });
+    }
     const fetchWithHeaders = (input, init) => {
         const merged = new Headers(init?.headers);
         for (const [key, value] of Object.entries(headers)) {
@@ -41,14 +83,25 @@ export function dockerClient() {
 export function setDockerClient(client) {
     sharedDockerClient = client;
 }
-const BACKOFF_INITIAL_MS = 1_000;
-const BACKOFF_MAX_MS = 5 * 60_000;
-const BACKOFF_RESET_AFTER_MS = 5 * 60_000;
-const PING_INTERVAL_MS = 60_000;
-const PING_TIMEOUT_MS = 30_000;
-const WAKE_TIMEOUT_MS = 120_000;
-const MAX_UNUSED_RESTARTS = 5;
-const IDLE_SWEEP_INTERVAL_MS = 60_000;
+/** Whether two upstream listen filters ask for the same thing. */
+function sameFilter(a, b) {
+    if (!a)
+        return false;
+    // JSON rather than a joined string: with a plain separator, ['a b'] and
+    // ['a', 'b'] compare equal, and the hub would skip a reconcile it owed.
+    const uris = (filter) => JSON.stringify([...(filter.resourceSubscriptions ?? [])].sort());
+    return ((a.toolsListChanged ?? false) === (b.toolsListChanged ?? false) &&
+        (a.promptsListChanged ?? false) === (b.promptsListChanged ?? false) &&
+        (a.resourcesListChanged ?? false) === (b.resourcesListChanged ?? false) &&
+        uris(a) === uris(b));
+}
+/** Whether a filter asks for nothing at all, in which case nothing is held upstream. */
+function emptyFilter(filter) {
+    return (!filter.toolsListChanged &&
+        !filter.promptsListChanged &&
+        !filter.resourcesListChanged &&
+        (filter.resourceSubscriptions?.length ?? 0) === 0);
+}
 export async function listAllTools(client) {
     const tools = [];
     let cursor;
@@ -58,7 +111,15 @@ export async function listAllTools(client) {
     do {
         if (++pages > MAX_TOOL_LIST_PAGES)
             throw new Error(`tools/list exceeded ${MAX_TOOL_LIST_PAGES} pages`);
-        const page = await client.listTools({ cursor });
+        // `request` rather than `listTools`, deliberately. SDK v2's `listTools()`
+        // walks the whole pagination itself whenever no cursor is given -- which is
+        // every first call -- and hands back one merged result. That would collapse
+        // this loop into a single iteration and take all three budgets below with
+        // it, leaving only the SDK's own page cap and no limit on tool count or
+        // metadata size at all. The budgets exist because a hostile child's tool
+        // list is a way to exhaust the hub's memory, and with it every other
+        // server's availability. One page per request is what makes them apply.
+        const page = await client.request({ method: 'tools/list', params: { cursor } }, ListToolsResultSchema);
         metadataBytes += jsonSize(page.tools);
         if (metadataBytes > MAX_TOOL_METADATA_BYTES)
             throw new Error(`tools/list metadata exceeded ${MAX_TOOL_METADATA_BYTES} bytes`);
@@ -82,10 +143,35 @@ export class ManagedServer {
     serverInfo;
     capabilities;
     tools = [];
+    /**
+     * How many tools the filter removed, for /health, and which entries matched
+     * nothing. Both stay `undefined` until the server has actually listed its
+     * tools: a snapshot restored from tool-cache.json is *already* filtered, so
+     * neither can be recomputed from it — every denyTools entry would look
+     * unmatched. `undefined` means "not measured yet", and /health omits it
+     * rather than reporting a zero it did not earn.
+     */
+    toolsHidden;
+    filterUnmatched;
     restarts = 0;
     lastError;
     /** Last time a request was actually forwarded; the idle sweep measures from here. */
     lastUsedAt = 0;
+    /**
+     * What the clients on this server's route are listening for. Created by the
+     * proxy, which owns the route's handler; the supervisor only publishes into
+     * it and reads its merged demand.
+     *
+     * Deliberately not consulted by the idle sweep: an open subscription is an
+     * intent, not a reason to keep a child process running. A sleeping child
+     * emits nothing, and the resync on the next wake is what makes that gap
+     * recoverable instead of silent.
+     */
+    channel;
+    /** The lease book of this server's route, or nothing if no client ever asked. */
+    get subscriptions() {
+        return this.channel?.registry;
+    }
     backoffMs;
     startedAt = 0;
     restartTimer;
@@ -101,6 +187,13 @@ export class ManagedServer {
      * kill the new child.
      */
     generation = 0;
+    /** The one upstream listen stream carrying this route's whole demand (modern era). */
+    upstream;
+    upstreamFilter;
+    /** URIs the child was told about one at a time (2025 era). */
+    upstreamUris = new Set();
+    reconciling = false;
+    reconcileQueued = false;
     constructor(name, config, options = {}) {
         this.name = name;
         this.config = config;
@@ -121,7 +214,10 @@ export class ManagedServer {
     hydrate(entry) {
         this.serverInfo = entry.serverInfo;
         this.capabilities = entry.capabilities;
-        this.tools = entry.tools;
+        // Filtered again although the cache fingerprint covers the whole
+        // ServerConfig: "managed.tools only ever holds allowed tools" should hold
+        // however the array arrived, including a hand-seeded tool-cache.json.
+        this.tools = filterTools(this.config, entry.tools);
         this.state = 'sleeping';
     }
     markUsed() {
@@ -138,6 +234,11 @@ export class ManagedServer {
             return Promise.resolve();
         if (this.state === 'stopped')
             return Promise.reject(new Error(`Server "${this.name}" is stopped`));
+        // Without this the request would sit in a waiter nothing can resolve until
+        // the wake timeout, two minutes later.
+        if (this.state === 'unauthorized') {
+            return Promise.reject(new Error(`Server "${this.name}" needs an upstream login`));
+        }
         const timeoutMs = this.options.wakeTimeoutMs ?? WAKE_TIMEOUT_MS;
         const promise = new Promise((resolve, reject) => {
             const waiter = {
@@ -184,7 +285,7 @@ export class ManagedServer {
     buildTransport() {
         switch (this.config.kind) {
             case 'remote':
-                return buildRemoteTransport(this.config);
+                return buildRemoteTransport(this.config, this.options.auth);
             case 'socket':
                 return new SocketTransport(this.config);
             case 'docker':
@@ -215,14 +316,45 @@ export class ManagedServer {
         this.stopping = false;
         this.state = 'starting';
         const generation = ++this.generation;
+        if (this.options.auth) {
+            // Getting a token is the one part of connecting that a restart cannot
+            // fix, so it happens first and its failure is classified separately.
+            try {
+                await this.options.auth.prepare();
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return;
+                this.onExit(`upstream authorization: ${error.message}`, generation, classifyAuthFailure(error));
+                return;
+            }
+        }
         const transport = this.buildTransport();
-        const client = new Client({ name: 'mcp-hub', version: VERSION }, { capabilities: {} });
+        const client = new Client({ name: 'mcp-hub', version: VERSION }, {
+            // Still nothing. The hub is not the one who can answer an elicitation —
+            // the person at the far end is — so declaring the capability on this
+            // shared connection would be a promise the hub cannot keep. What it
+            // declares per forwarded request is a different matter.
+            capabilities: {},
+            // 'auto' probes with server/discover and falls back to the 2025
+            // sequence when the child does not answer it, so a legacy child
+            // connects exactly as before. What it buys is the modern era where the
+            // child supports it: there, input_required comes back as a *result*
+            // the hub can forward, instead of a server→client request it would
+            // have nowhere to put.
+            versionNegotiation: { mode: 'auto' },
+            // The client would otherwise answer an input_required itself — from
+            // handlers the hub never registered, so every elicitation would be
+            // silently declined on the caller's behalf. A gateway has to hand the
+            // question on, not answer it.
+            inputRequired: { autoFulfill: false }
+        });
         transport.onclose = () => this.onExit(this.exitReason(), generation);
         try {
             await client.connect(transport);
         }
         catch (error) {
-            this.onExit(`failed to start: ${error.message}`, generation);
+            this.onExit(`failed to start: ${error.message}`, generation, classifyAuthFailure(error));
             return;
         }
         if (generation !== this.generation) {
@@ -242,15 +374,178 @@ export class ManagedServer {
         console.log(`[${this.name}] up (${this.serverInfo?.name ?? 'unknown'} ${this.serverInfo?.version ?? ''})`.trim());
         this.resolveWakeWaiters();
         if (this.capabilities?.tools) {
-            client.setNotificationHandler(ToolListChangedNotificationSchema, () => void this.refreshTools());
+            client.setNotificationHandler('notifications/tools/list_changed', () => {
+                void this.refreshTools();
+                this.publishUpstream({ kind: 'tools_list_changed' });
+            });
             await this.refreshTools();
         }
         else {
             this.options.persist?.(this);
         }
+        this.watchUpstream(client);
+        // A subscription taken while this child was asleep is an intent, not a
+        // connection: nothing was held upstream, so it has to be re-established
+        // here rather than at the moment the client asked. The same is true after
+        // a crash — shutdown() throws the client away and every subscription with
+        // it. Without this a subscription is silently dead from the first nap on.
+        this.reconcileSubscriptions();
+        // And because nothing was held, the hub cannot know what changed while the
+        // child was gone. Telling the listeners to read everything again is the
+        // only honest answer.
+        this.subscriptions?.resync();
+        // The aggregate's tool list spans this child, so its listeners have the
+        // same gap: whatever changed while the child was away is invisible to them
+        // too. One re-read tells them so.
+        if (this.options.aggregateWantsTools?.() === true)
+            this.options.onUpstreamEvent?.({ kind: 'tools_list_changed' });
         this.pingTimer = setInterval(() => void this.checkAlive(), PING_INTERVAL_MS);
         this.pingTimer.unref();
     }
+    /** One change event to this route's listeners and to the /hub aggregate. */
+    publishUpstream(event) {
+        this.subscriptions?.publish(event);
+        this.options.onUpstreamEvent?.(event);
+    }
+    /**
+     * Route the child's change notifications to the clients waiting for them.
+     *
+     * The same four handlers serve both eras. On a 2025 connection the child
+     * sends these unsolicited; on 2026-07-28 they arrive on the listen stream
+     * that `reconcileSubscriptions` opens, and the SDK dispatches them to these
+     * very registrations. So the era difference is confined to *asking*, not to
+     * receiving — which is the whole reason this is one code path.
+     *
+     * Gated on the declared capability for the same reason the handlers below
+     * are only registered for what the child said it has: a handler for a
+     * notification the child cannot send is a claim nobody checked.
+     */
+    watchUpstream(client) {
+        if (this.capabilities?.prompts) {
+            client.setNotificationHandler('notifications/prompts/list_changed', () => this.publishUpstream({ kind: 'prompts_list_changed' }));
+        }
+        if (this.capabilities?.resources) {
+            client.setNotificationHandler('notifications/resources/list_changed', () => this.publishUpstream({ kind: 'resources_list_changed' }));
+            client.setNotificationHandler('notifications/resources/updated', notification => this.publishUpstream({ kind: 'resource_updated', uri: notification.params.uri }));
+        }
+    }
+    /**
+     * Bring what the child is told to watch in line with what the clients want.
+     *
+     * Fire-and-forget with a single-flight guard: it is called from lease
+     * acquire/release, which happen on the request path and must not wait for an
+     * upstream round trip. A change arriving mid-reconcile queues exactly one
+     * more pass, so the last caller's demand always wins without a backlog.
+     */
+    reconcileSubscriptions() {
+        if (this.reconciling) {
+            this.reconcileQueued = true;
+            return;
+        }
+        this.reconciling = true;
+        void this.runReconcile()
+            .catch(error => console.error(`[${this.name}] could not update subscriptions: ${error.message}`))
+            .finally(() => {
+            this.reconciling = false;
+            if (!this.reconcileQueued)
+                return;
+            this.reconcileQueued = false;
+            this.reconcileSubscriptions();
+        });
+    }
+    async runReconcile() {
+        const client = this.client;
+        const registry = this.subscriptions;
+        // Asleep, down, or nobody listening: there is nothing to hold. State is not
+        // dropped — it lives in the leases, and start() replays it.
+        if (!client || this.state !== 'up')
+            return;
+        if (!subscriptionsAllowed(this.config))
+            return;
+        const demand = registry?.demand() ?? { toolsListChanged: false, promptsListChanged: false, resourcesListChanged: false, uris: [] };
+        // The union spans both books: this route's leases and the aggregate's.
+        const wantsTools = demand.toolsListChanged || this.options.aggregateWantsTools?.() === true;
+        // A child that never advertised `subscribe` cannot be asked for resource
+        // updates; asking anyway earns a -32601 per URI and nothing else.
+        const canSubscribe = this.capabilities?.resources?.subscribe === true;
+        const uris = canSubscribe ? demand.uris : [];
+        if (client.getProtocolEra() === 'modern') {
+            await this.reconcileModern(client, {
+                toolsListChanged: wantsTools && this.capabilities?.tools?.listChanged === true,
+                promptsListChanged: demand.promptsListChanged && this.capabilities?.prompts?.listChanged === true,
+                resourcesListChanged: demand.resourcesListChanged && this.capabilities?.resources?.listChanged === true,
+                resourceSubscriptions: uris
+            });
+            return;
+        }
+        await this.reconcileLegacy(client, uris);
+    }
+    /**
+     * One listen stream carries the whole route's demand.
+     *
+     * A filter cannot be widened in place, so any change to the union means
+     * closing the stream and opening a new one. That is a real gap — a
+     * notification landing between the two is lost — which is why the reopen is
+     * followed by nothing: the client that just subscribed gets its resync from
+     * the acquire path, and the ones already listening were not affected by
+     * whatever the new lease added.
+     */
+    async reconcileModern(client, filter) {
+        if (sameFilter(this.upstreamFilter, filter))
+            return;
+        const previous = this.upstream;
+        this.upstream = undefined;
+        this.upstreamFilter = undefined;
+        if (previous)
+            await previous.close().catch(() => { });
+        if (emptyFilter(filter))
+            return;
+        const subscription = await client.listen(filter);
+        // A close() racing the await above already cleared the field; honour that
+        // rather than installing a stream nobody wants.
+        if (this.client !== client) {
+            await subscription.close().catch(() => { });
+            return;
+        }
+        this.upstream = subscription;
+        this.upstreamFilter = filter;
+    }
+    /**
+     * The 2025 era asks per URI and gets list_changed unsolicited, so only the
+     * resource set is negotiated — as a diff, because re-subscribing a URI the
+     * child already holds is a round trip that buys nothing.
+     */
+    async reconcileLegacy(client, uris) {
+        const wanted = new Set(uris);
+        for (const uri of wanted) {
+            if (this.upstreamUris.has(uri))
+                continue;
+            await client.subscribeResource({ uri });
+            this.upstreamUris.add(uri);
+        }
+        // Snapshotted before the loop, which removes from the very set it reads.
+        const stale = [...this.upstreamUris].filter(uri => !wanted.has(uri));
+        for (const uri of stale) {
+            await client.unsubscribeResource({ uri }).catch(() => { });
+            this.upstreamUris.delete(uri);
+        }
+    }
+    /**
+     * Says what the filter did, at the one moment the operator is looking: a
+     * filter edit bounces this server, so this prints seconds later. That is why
+     * an unmatched entry need not be fatal here, unlike in the ni-c servers where
+     * the tool names are known before anything starts.
+     */
+    reportToolFilter(upstream) {
+        if (!hasToolFilter(this.config))
+            return;
+        this.toolsHidden = upstream.length - this.tools.length;
+        this.filterUnmatched = unmatchedPatterns(this.config, upstream);
+        console.log(`[${this.name}] tool filter: ${this.tools.length} of ${upstream.length} tools exposed`);
+        for (const pattern of this.filterUnmatched) {
+            console.warn(`[${this.name}] tool filter: no tool matches "${pattern}"`);
+        }
+    }
     async refreshTools() {
         // Hold the client locally: onExit() clears this.client, and a paged list
         // spans awaits, so re-reading it per page could hit undefined mid-loop.
@@ -258,7 +553,13 @@ export class ManagedServer {
         if (!client)
             return;
         try {
-            this.tools = await listAllTools(client);
+            // Filtered AFTER listAllTools, never inside it: that function enforces the
+            // MAX_TOOLS and metadata-byte budgets against the raw upstream, and
+            // filtering earlier would let an upstream bury payload in tools it knows
+            // are filtered.
+            const upstream = await listAllTools(client);
+            this.tools = filterTools(this.config, upstream);
+            this.reportToolFilter(upstream);
             this.options.persist?.(this);
         }
         catch (error) {
@@ -276,6 +577,24 @@ export class ManagedServer {
         const client = this.client;
         if (this.state !== 'up' || !client)
             return;
+        // `ping` does not exist on 2026-07-28: the revision removed it, and the SDK
+        // refuses to send one rather than inventing an RPC the far end never had.
+        // Without this check the refusal reads as a dead child and the supervisor
+        // restarts a server that is perfectly healthy — forever, with the backoff
+        // climbing. Seen in production the morning after 0.11.0 went out: two
+        // remote children that happened to speak the modern era flapped every
+        // interval while the rest of the hub was fine.
+        //
+        // Nothing replaces it. On that era liveness is the transport's business,
+        // which is where it always was for a stdio child: the process exits, the
+        // transport closes, onExit restarts it. What an HTTP child on the modern
+        // era loses is the *active* probe — a server that stops answering without
+        // closing is noticed at the next real call rather than within a minute.
+        // Sending some other request as a substitute heartbeat would be worse: it
+        // would be a call the operator never asked for, against a server that
+        // charges for it or logs it, every interval, forever.
+        if (!eraHasPing(client))
+            return;
         try {
             await client.ping({ timeout: PING_TIMEOUT_MS });
         }
@@ -286,7 +605,7 @@ export class ManagedServer {
             await client.close().catch(() => { });
         }
     }
-    onExit(reason, generation = this.generation) {
+    onExit(reason, generation = this.generation, outcome = 'restart') {
         // A callback from a transport that sleep()/stop()/a newer start() already
         // left behind must not touch the current child.
         if (generation !== this.generation)
@@ -295,7 +614,7 @@ export class ManagedServer {
         // calls us as well. Without this guard the second call would overwrite
         // restartTimer without clearing it, so two children would be spawned and
         // one of them left unreferenced — never pinged, never stopped.
-        if (this.state === 'down' || this.state === 'stopped' || this.state === 'sleeping')
+        if (this.state === 'down' || this.state === 'stopped' || this.state === 'sleeping' || this.state === 'unauthorized')
             return;
         clearInterval(this.pingTimer);
         this.client = undefined;
@@ -303,6 +622,16 @@ export class ManagedServer {
             this.state = 'stopped';
             return;
         }
+        if (outcome === 'unauthorized') {
+            // Restarting cannot help: the upstream wants a human. Sitting in a
+            // five-minute retry loop forever would only hammer it and hide the reason
+            // behind a state that looks like an ordinary outage.
+            this.state = 'unauthorized';
+            this.lastError = reason;
+            this.rejectWakeWaiters(new Error(`Server "${this.name}" needs an upstream login`));
+            console.error(`[${this.name}] unauthorized (${reason}); run: mcp-hub-admin upstream login ${this.name}`);
+            return;
+        }
         this.state = 'down';
         this.lastError = reason;
         if (this.startedAt > 0 && Date.now() - this.startedAt > BACKOFF_RESET_AFTER_MS) {
@@ -325,6 +654,20 @@ export class ManagedServer {
         this.restartTimer.unref();
         this.backoffMs = Math.min(this.backoffMs * 2, BACKOFF_MAX_MS);
     }
+    /**
+     * Try again now that a credential may exist — called after the callback route
+     * completed a login, or by the admin CLI's refresh. Does nothing unless the
+     * server is actually waiting for one.
+     */
+    reauthorize() {
+        if (this.state !== 'unauthorized')
+            return;
+        this.backoffMs = this.options.backoffInitialMs ?? BACKOFF_INITIAL_MS;
+        // onExit() ignores a report while the state is already terminal, so it has
+        // to be left before the next attempt can report anything.
+        this.state = 'down';
+        void this.start();
+    }
     async shutdown() {
         this.stopping = true;
         // Bump the generation first: the onclose this close() is about to trigger
@@ -332,6 +675,14 @@ export class ManagedServer {
         this.generation++;
         clearTimeout(this.restartTimer);
         clearInterval(this.pingTimer);
+        // The upstream subscription belongs to the connection that is going away.
+        // Forgetting it here is what makes the next start() reconcile from scratch
+        // instead of believing a stream it no longer holds is still open. The
+        // leases themselves are untouched — they are the clients' intent, and they
+        // outlive any one child process.
+        this.upstream = undefined;
+        this.upstreamFilter = undefined;
+        this.upstreamUris.clear();
         this.rejectWakeWaiters(new Error(`Server "${this.name}" is shutting down`));
         // Same local-client rule as checkAlive(). This path happens to be safe
         // today because the member access precedes the await, but Supervisor.stop()
@@ -346,6 +697,11 @@ export class ManagedServer {
     async stop() {
         await this.shutdown();
         this.state = 'stopped';
+        // Unlike sleep(), this server is not coming back: the route's handler holds
+        // open listen streams and would otherwise outlive everything it serves.
+        const channel = this.channel;
+        this.channel = undefined;
+        await channel?.close().catch(() => { });
     }
     /** Same teardown as stop(), but the server stays wakeable. */
     async sleep() {
@@ -356,6 +712,41 @@ export class ManagedServer {
         this.stopping = false;
     }
 }
+/**
+ * One credential manager per server name, outliving the ManagedServer.
+ *
+ * applyDiff() throws the ManagedServer away and builds a new one for any config
+ * change at all — a header edit included — so a manager held there would lose
+ * its in-flight refresh and its single-flight guarantee whenever the config file
+ * was touched. Keyed by name and rebuilt only when the credential fingerprint
+ * actually changes.
+ */
+export class UpstreamAuthRegistry {
+    store;
+    externalUrl;
+    managers = new Map();
+    constructor(store, externalUrl) {
+        this.store = store;
+        this.externalUrl = externalUrl;
+    }
+    for(name, config) {
+        if (!config.oauth)
+            return undefined;
+        const auth = new UpstreamAuth(name, config, this.store, this.externalUrl);
+        const fingerprint = credentialFingerprint(auth.identity);
+        const existing = this.managers.get(name);
+        if (existing?.fingerprint === fingerprint)
+            return existing.auth;
+        this.managers.set(name, { fingerprint, auth });
+        return auth;
+    }
+    get(name) {
+        return this.managers.get(name)?.auth;
+    }
+    forget(name) {
+        this.managers.delete(name);
+    }
+}
 export class Supervisor {
     config;
     options;
@@ -369,15 +760,63 @@ export class Supervisor {
     get idleTimeoutMinutes() {
         return this.options.idleTimeoutMinutes ?? 0;
     }
+    /** The global idle timeout as one number, whichever unit the caller gave it in. */
+    get idleTimeoutMs() {
+        return this.options.idleTimeoutMs || this.idleTimeoutMinutes * 60_000;
+    }
+    /**
+     * What the clients on the /hub route are listening for.
+     *
+     * /hub exposes tools and nothing else, so the only change worth relaying is
+     * "some child's tool list moved, re-read mine". Set by the proxy, which owns
+     * that route's handler.
+     */
+    hubSubscriptions;
+    /**
+     * Relay a child's change event to the /hub aggregate.
+     *
+     * Only the tool list crosses: /hub does not aggregate resources or prompts,
+     * so a resources/list_changed from one child describes nothing a /hub client
+     * can read. Sending it anyway would be the same kind of empty promise the
+     * capability table exists to prevent.
+     */
+    onChildEvent(cfg, event) {
+        if (event.kind !== 'tools_list_changed')
+            return;
+        if (cfg.hub === false || !subscriptionsAllowed(cfg))
+            return;
+        this.hubSubscriptions?.publish(event);
+    }
+    /**
+     * Bring every child's upstream subscription in line.
+     *
+     * Called when the /hub aggregate's demand moves, because that one book is
+     * shared by all of them — unlike a per-server route, where only its own
+     * child is affected.
+     */
+    reconcileAll() {
+        for (const server of this.servers.values())
+            server.reconcileSubscriptions();
+    }
+    aggregateWantsTools(cfg) {
+        if (cfg.hub === false || !subscriptionsAllowed(cfg))
+            return false;
+        return this.hubSubscriptions?.demand().toolsListChanged === true;
+    }
     buildManaged(name, cfg) {
-        if ((cfg.kind !== 'stdio' && cfg.kind !== 'docker') || cfg.keepAlive || this.idleTimeoutMinutes <= 0) {
-            return new ManagedServer(name, cfg);
+        const onUpstreamEvent = (event) => this.onChildEvent(cfg, event);
+        const aggregateWantsTools = () => this.aggregateWantsTools(cfg);
+        if ((cfg.kind !== 'stdio' && cfg.kind !== 'docker') || cfg.keepAlive || this.idleTimeoutMs <= 0) {
+            const auth = cfg.kind === 'remote' ? this.options.upstreamAuth?.for(name, cfg) : undefined;
+            return new ManagedServer(name, cfg, { onUpstreamEvent, aggregateWantsTools, ...(auth ? { auth } : {}) });
         }
         return new ManagedServer(name, cfg, {
             onDemand: true,
-            idleMs: (cfg.idleMinutes ?? this.idleTimeoutMinutes) * 60_000,
+            idleMs: cfg.idleMinutes !== undefined ? cfg.idleMinutes * 60_000 : this.idleTimeoutMs,
             wakeTimeoutMs: this.options.wakeTimeoutMs,
-            persist: server => this.persist(server)
+            persist: server => this.persist(server),
+            onUpstreamEvent,
+            aggregateWantsTools
         });
     }
     persist(server) {
@@ -416,7 +855,7 @@ export class Supervisor {
         this.startIdleSweep();
     }
     startIdleSweep() {
-        if (this.idleTimeoutMinutes <= 0 || this.sweepTimer)
+        if (this.idleTimeoutMs <= 0 || this.sweepTimer)
             return;
         this.sweepTimer = setInterval(() => this.sweepIdle(), this.options.sweepIntervalMs ?? IDLE_SWEEP_INTERVAL_MS);
         this.sweepTimer.unref();
@@ -477,6 +916,11 @@ export class Supervisor {
                 this.servers.delete(name);
             }
             this.options.cache?.delete(name);
+            // Only for servers that are gone. A `changed` one keeps its manager
+            // unless the credential fingerprint moved, so editing a header does not
+            // discard a perfectly good refresh token.
+            if (diff.removed.includes(name))
+                this.options.upstreamAuth?.forget(name);
         }
         await Promise.all([...diff.added, ...diff.changed].map(name => {
             const cfg = config.get(name);