@ni-c/mcp-hub 0.10.0 → 0.11.1

package/dist/hub.js

@@ -1,11 +1,118 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, CLIENT_CAPABILITIES_META_KEY } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { VERSION } from './version.js';
-import { ABSOLUTE_CALL_OPTIONS, assertForwardedResultSize } from './mcp-limits.js';
+import { forwardToolCall } from './forward.js';
 import { loggableToolName, toolAllowed } from './tool-filter.js';
-function text(value) {
-    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+import { booleanEnv } from './mcp-limits.js';
+import { REFUSAL_REASON, decidePassthrough } from './elicitation.js';
+import { REVISION } from './proxy.js';
+/**
+ * A meta-tool answer, in both channels at once.
+ *
+ * `structuredContent` is the machine-readable half and the reason the tools
+ * declare an `outputSchema` at all; the text block stays because the SDK does
+ * NOT synthesize one for an object-shaped value, and a client that only reads
+ * `content` would otherwise get an empty answer. Both carry the same object —
+ * the specification's rule is that the two are the same information in two
+ * presentations, and the cheapest way to keep that true is to serialise the one
+ * value twice rather than to build two.
+ */
+function structured(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        structuredContent: value
+    };
 }
+/**
+ * Every value `ServerState` has, as a schema.
+ *
+ * Written as a `Record` keyed by the type rather than as a bare list on
+ * purpose: a state added to the supervisor and forgotten here would make this
+ * schema refuse a perfectly correct answer, and the SDK turns a refused answer
+ * into an error result. Keyed this way the omission is a compile error instead.
+ */
+const SERVER_STATES = {
+    starting: true,
+    up: true,
+    down: true,
+    stopped: true,
+    sleeping: true,
+    unauthorized: true
+};
+const serverStatus = z
+    .enum(Object.keys(SERVER_STATES))
+    .describe('What the hub is currently doing with this server.');
+/**
+ * A JSON Schema, or a child's annotations: an object whose contents are not
+ * ours to describe.
+ *
+ * `looseObject` and not a stricter shape, because both are somebody else's
+ * document. Note that this stays right even under SEP-2106, which lets an
+ * `outputSchema` describe a non-object *instance*: the schema itself is still
+ * a JSON object — `{"type": "array", …}` — so it is the instance root that got
+ * freer, not the document.
+ *
+ * The `meta` is not decoration. Left to itself zod writes "accepts anything" as
+ * `"additionalProperties": {}` — an empty schema, which is legal and means
+ * exactly the same as `true`, but is the spelling some MCP clients refuse or
+ * mishandle. `meta` is merged into the emitted JSON Schema and nothing else, so
+ * the wire says `true` while the runtime stays as permissive as it has to be.
+ */
+const foreignDocument = z.looseObject({}).meta({ additionalProperties: true });
+const listServersOutput = z.object({
+    servers: z.array(z.object({
+        name: z.string().describe('Name to pass to the other tools.'),
+        description: z.string().describe("The child's own title, empty if it has never connected."),
+        status: serverStatus,
+        toolCount: z.number().int().describe('Tools this server offers through the hub, after its filter.'),
+        hidden: z
+            .literal(true)
+            .optional()
+            .describe('Present only for a server whose tools are served by its own endpoint alone.')
+    }))
+});
+const listToolsOutput = z.object({
+    server: z.string(),
+    tools: z.array(z.object({
+        name: z.string(),
+        description: z.string().describe('First line only, capped at 120 characters.'),
+        annotations: foreignDocument.optional().describe("The child's own annotations, verbatim; absent if it declared none."),
+        hasOutputSchema: z
+            .literal(true)
+            .optional()
+            .describe('Present when the tool declares an output schema, which get_tool_schema returns.')
+    }))
+});
+const getToolSchemaOutput = z.object({
+    server: z.string(),
+    name: z.string(),
+    description: z.string().describe('The full description, untruncated.'),
+    inputSchema: foreignDocument.describe('JSON Schema for the arguments of call_tool.'),
+    outputSchema: foreignDocument
+        .optional()
+        .describe('JSON Schema the structuredContent of a call conforms to; absent if the tool declares none.'),
+    annotations: foreignDocument.optional()
+});
+const describeConnectionOutput = z.object({
+    era: z.enum(['modern', 'legacy']).describe('Which protocol era this very call arrived on.'),
+    revision: z.string().describe('The revision string that era puts on the wire.'),
+    hubVersion: z.string(),
+    caller: z.object({
+        declaresElicitation: z
+            .boolean()
+            .describe('Whether this request carried an elicitation capability. Only the 2026 era can carry one at all.')
+    }),
+    elicitation: z.object({
+        wouldForward: z
+            .boolean()
+            .optional()
+            .describe('Whether a question from the named server would reach you. Absent when no server was named and the answer depends on one.'),
+        reason: z.string().optional().describe('Why not, or what the answer still depends on. Absent when a question would be carried.'),
+        server: z.string().optional().describe('The server this answer was computed for, if one was named.')
+    })
+});
+const wakeServerOutput = z.object({ name: z.string(), status: serverStatus, toolCount: z.number().int() });
+const sleepServerOutput = z.object({ name: z.string(), status: serverStatus });
 function toolError(message) {
     return { content: [{ type: 'text', text: message }], isError: true };
 }
@@ -15,6 +122,38 @@ function firstLine(description) {
     const line = description.split('\n', 1)[0].trim();
     return line.length > 120 ? `${line.slice(0, 117)}...` : line;
 }
+/**
+ * The four hints the three reading meta-tools carry.
+ *
+ * Written out rather than left to the defaults, because the defaults are not
+ * neutral: the specification gives `destructiveHint` and `openWorldHint` a
+ * default of **true**, so a tool that says nothing announces itself as a
+ * destructive tool in an open world. `list_servers`, `list_tools` and
+ * `get_tool_schema` only read the hub's own snapshot, and they said nothing.
+ *
+ * `openWorldHint: false` is right even though the *children* reach all sorts of
+ * places: these three do not call them. `call_tool` does, and says so.
+ */
+const READS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+/**
+ * A lifecycle switch: it changes nothing a person put there, and doing it twice
+ * leaves the same world.
+ */
+const LIFECYCLE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+/**
+ * The child's own annotations, passed on verbatim.
+ *
+ * Verbatim, and not condensed into a kind/asks pair, because a summary would be
+ * a statement *by the hub* about the child's claim. The specification is blunt
+ * about what these are worth — "clients MUST consider tool annotations to be
+ * untrusted unless they come from trusted servers" — and the hub is in no
+ * position to vouch for a child it merely forwards to. It says what it was
+ * told, and hub-tools.md says whose word it is.
+ *
+ * Omitted entirely when the child declared none. An empty object here would
+ * read as "all four defaults", which is a claim the child did not make.
+ */
+const passThrough = (tool) => tool.annotations === undefined ? {} : { annotations: tool.annotations };
 /**
  * The /hub aggregate: one connector exposing every hub-enabled server through
  * six meta-tools, so a client's context holds 6 tool schemas instead of 9×N.
@@ -34,7 +173,16 @@ const requireAllowedTool = (managed, tool, server) => {
     console.warn(`[${managed.name}] refused "${loggableToolName(tool)}": not permitted by allowTools/denyTools`);
     return toolError(`Unknown tool "${tool}" on server "${server}". Use list_tools to see available tools.`);
 };
-export function buildHubServer(supervisor) {
+/**
+ * The aggregate, built for the era it will serve.
+ *
+ * `era` is not decoration: both entry points already construct one instance per
+ * era — `createMcpHandler` per request, `serveStdio` per connection — and the
+ * SDK hands the era to the factory precisely so a server can vary by it. The
+ * only thing that varies here is `describe_connection`, which would otherwise
+ * have to guess the one fact it exists to report.
+ */
+export function buildHubServer(supervisor, secret, era) {
     const hub = new McpServer({ name: 'mcp-hub', version: VERSION });
     const findServer = (name) => supervisor.get(name);
     /**
@@ -76,18 +224,24 @@ export function buildHubServer(supervisor) {
         title: 'List MCP servers',
         description: 'List all MCP servers available through this hub, with their status. Call this first to see what is available. ' +
             'Servers marked "hidden" serve their tools only via their own endpoint, but wake_server/sleep_server still manage them.',
-        inputSchema: {}
-    }, async () => text([...supervisor.servers.values()].map(s => ({
-        name: s.name,
-        description: s.serverInfo?.title ?? s.serverInfo?.name ?? '',
-        status: s.state,
-        toolCount: s.tools.length,
-        ...(s.config.hub ? {} : { hidden: true })
-    }))));
+        inputSchema: z.object({}),
+        outputSchema: listServersOutput,
+        annotations: READS
+    }, async () => structured({
+        servers: [...supervisor.servers.values()].map(s => ({
+            name: s.name,
+            description: s.serverInfo?.title ?? s.serverInfo?.name ?? '',
+            status: s.state,
+            toolCount: s.tools.length,
+            ...(s.config.hub ? {} : { hidden: true })
+        }))
+    }));
     hub.registerTool('list_tools', {
         title: 'List tools of a server',
         description: 'List the tools of one MCP server with one-line descriptions. Use get_tool_schema before calling a tool for the first time.',
-        inputSchema: { server: z.string().describe('Server name from list_servers') }
+        inputSchema: z.object({ server: z.string().describe('Server name from list_servers') }),
+        outputSchema: listToolsOutput,
+        annotations: READS
     }, async ({ server }) => {
         const managed = findServer(server);
         if (!managed)
@@ -100,15 +254,32 @@ export function buildHubServer(supervisor) {
         const failed = await prepare(managed);
         if (failed)
             return failed;
-        return text(managed.tools.map(t => ({ name: t.name, description: firstLine(t.description) })));
+        return structured({
+            server: managed.name,
+            tools: managed.tools.map(t => ({
+                name: t.name,
+                description: firstLine(t.description),
+                ...passThrough(t),
+                // A marker, not the schema itself: this list exists to stay small,
+                // and a page of JSON Schema per tool is what get_tool_schema is for.
+                // Omitted rather than false, for passThrough's reason.
+                //
+                // It stays a marker now that every server this family ships declares
+                // one. A hub runs whatever its config names, and a child written by
+                // somebody else is the ordinary case here, not the odd one.
+                ...(t.outputSchema === undefined ? {} : { hasOutputSchema: true })
+            }))
+        });
     });
     hub.registerTool('get_tool_schema', {
         title: 'Get the full schema of a tool',
         description: 'Get the full description and JSON input schema of one tool, needed to construct arguments for call_tool.',
-        inputSchema: {
+        inputSchema: z.object({
             server: z.string().describe('Server name from list_servers'),
             tool: z.string().describe('Tool name from list_tools')
-        }
+        }),
+        outputSchema: getToolSchemaOutput,
+        annotations: READS
     }, async ({ server, tool }) => {
         const managed = findServer(server);
         if (!managed)
@@ -128,17 +299,48 @@ export function buildHubServer(supervisor) {
         const found = managed.tools.find(t => t.name === tool);
         if (!found)
             return toolError(`Unknown tool "${tool}" on server "${server}". Use list_tools to see available tools.`);
-        return text({ name: found.name, description: found.description ?? '', inputSchema: found.inputSchema });
+        return structured({
+            server: managed.name,
+            name: found.name,
+            description: found.description ?? '',
+            inputSchema: found.inputSchema,
+            // The reason this tool exists twice over: call_tool hands back the
+            // child's structuredContent, and until this line the caller had no way
+            // to learn what shape it was promised. Verbatim and omitted-when-absent,
+            // exactly as annotations are.
+            ...(found.outputSchema === undefined ? {} : { outputSchema: found.outputSchema }),
+            ...passThrough(found)
+        });
     });
     hub.registerTool('call_tool', {
         title: 'Call a tool on a server',
         description: 'Call a tool on one of the MCP servers. Arguments must match the schema from get_tool_schema.',
-        inputSchema: {
+        inputSchema: z.object({
             server: z.string().describe('Server name from list_servers'),
             tool: z.string().describe('Tool name from list_tools'),
-            arguments: z.record(z.string(), z.unknown()).optional().describe('Tool arguments matching its input schema')
-        }
-    }, async ({ server, tool, arguments: args }) => {
+            // `meta` for the same reason as `foreignDocument`: say `true` on the
+            // wire rather than the empty schema zod would write by itself.
+            arguments: z
+                .record(z.string(), z.unknown())
+                .meta({ additionalProperties: true })
+                .optional()
+                .describe('Tool arguments matching its input schema')
+        }),
+        // No outputSchema, and the only tool here without one. That is a
+        // construction rather than an omission: this tool answers with a child's
+        // result, so the shape is the child's own and changes with the `tool`
+        // argument. A schema here could say no more than "an object", which is
+        // less than the caller can already have — get_tool_schema returns the
+        // child's own outputSchema, and call_tool hands the matching
+        // structuredContent back verbatim.
+        //
+        // The one place the hub cannot know the answer, so it gives the strongest
+        // one. Whatever the named tool does, call_tool does — it may delete, it
+        // may reach the whole internet, and forwarding is not the same as
+        // vouching. Read the child's own annotations from list_tools for what a
+        // particular call would do.
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
+    }, async ({ server, tool, arguments: args }, ctx) => {
         const managed = findServer(server);
         if (!managed)
             return toolError(`Unknown server "${server}". Use list_servers to see available servers.`);
@@ -151,6 +353,10 @@ export function buildHubServer(supervisor) {
         const filtered = requireAllowedTool(managed, tool, server);
         if (filtered)
             return filtered;
+        // The wake stays here rather than being left to the forward, which would
+        // do it too: this endpoint answers with tool results, and "failed to
+        // start" is a different thing for a caller to read than "tool call
+        // failed". Once it is up the forward's own wake is a no-op.
         if (managed.onDemand && (managed.state !== 'up' || !managed.client)) {
             try {
                 await managed.wake();
@@ -161,19 +367,34 @@ export function buildHubServer(supervisor) {
         }
         if (managed.state !== 'up' || !managed.client)
             return toolError(`Server "${server}" is ${managed.state}, try again later.`);
-        managed.markUsed();
         try {
-            const result = await managed.client.callTool({ name: tool, arguments: (args ?? {}) }, undefined, ABSOLUTE_CALL_OPTIONS);
-            return assertForwardedResultSize(result);
+            // Same forwarding rules as the per-server path, from the same code: a
+            // child that asks something reaches the person through this door too.
+            // `via: 'hub'` binds the sealed request state to this endpoint — the
+            // same tool is reachable both ways, and resuming one call through the
+            // other door is not something a caller should be able to do.
+            return await forwardToolCall({
+                managed,
+                tool,
+                params: { name: tool, arguments: (args ?? {}) },
+                ctx,
+                secret,
+                via: 'hub'
+            });
         }
         catch (error) {
+            // Aggregate semantics: every failure here is a tool result, never a
+            // protocol error, because six meta-tools stand in for every server and
+            // one unreachable child must not look like a broken hub.
             return toolError(`Tool call failed: ${error.message}`);
         }
     });
     hub.registerTool('wake_server', {
         title: 'Wake a sleeping server',
         description: 'Start an on-demand server now so its first tool call is fast. No-op if it is already running.',
-        inputSchema: { server: z.string().describe('Server name from list_servers') }
+        inputSchema: z.object({ server: z.string().describe('Server name from list_servers') }),
+        outputSchema: wakeServerOutput,
+        annotations: LIFECYCLE
     }, async ({ server }) => {
         const managed = findServer(server);
         if (!managed)
@@ -187,12 +408,14 @@ export function buildHubServer(supervisor) {
             return toolError(`Server "${server}" failed to start: ${error.message}`);
         }
         managed.markUsed();
-        return text({ name: managed.name, status: managed.state, toolCount: managed.tools.length });
+        return structured({ name: managed.name, status: managed.state, toolCount: managed.tools.length });
     });
     hub.registerTool('sleep_server', {
         title: 'Put a server to sleep',
         description: 'Stop an on-demand server immediately instead of waiting for its idle timeout. It restarts automatically on the next tool call.',
-        inputSchema: { server: z.string().describe('Server name from list_servers') }
+        inputSchema: z.object({ server: z.string().describe('Server name from list_servers') }),
+        outputSchema: sleepServerOutput,
+        annotations: LIFECYCLE
     }, async ({ server }) => {
         const managed = findServer(server);
         if (!managed)
@@ -200,8 +423,65 @@ export function buildHubServer(supervisor) {
         if (!managed.onDemand)
             return toolError(`Server "${server}" is always running.`);
         await managed.sleep();
-        return text({ name: managed.name, status: managed.state });
+        return structured({ name: managed.name, status: managed.state });
     });
+    /**
+     * The seventh tool, off unless an operator asks for it.
+     *
+     * Off by default because every tool a client can see costs context in every
+     * conversation that client has, and "six meta-tools instead of N×tools" is
+     * the whole argument for the aggregate. This one answers a question most
+     * deployments never ask. It is not off for safety: it reports only what the
+     * caller's own request already contains, and says nothing about any other
+     * client — which is exactly why it exists instead of a tool that hands out
+     * the hub's log.
+     *
+     * Read here rather than at module load so a test can set it per case, and
+     * because this function runs once per request anyway.
+     */
+    if (booleanEnv('MCP_DIAGNOSTICS', false)) {
+        hub.registerTool('describe_connection', {
+            title: 'Describe this connection',
+            description: 'Report how you are connected to this hub right now: the protocol era, and whether a server could ask you a question mid-call. ' +
+                'Name a server to include its own switch and era in the answer.',
+            inputSchema: z.object({
+                server: z.string().optional().describe('Server name from list_servers. Omit to ask about the connection alone.')
+            }),
+            outputSchema: describeConnectionOutput,
+            annotations: READS
+        }, async ({ server }, ctx) => {
+            const managed = server === undefined ? undefined : findServer(server);
+            if (server !== undefined && !managed) {
+                return toolError(`Unknown server "${server}". Use list_servers to see available servers.`);
+            }
+            // Exactly what forwardToolCall reads, from exactly the same place.
+            const envelope = ctx.mcpReq.envelope;
+            const declared = envelope?.[CLIENT_CAPABILITIES_META_KEY]?.elicitation;
+            // A sleeping child has negotiated no era, and asking here must not wake
+            // one: this tool reports, it does not act.
+            const childEra = managed?.state === 'up' ? managed.client?.getProtocolEra() : undefined;
+            const decision = decidePassthrough({ config: managed?.config, declaredElicitation: declared, childEra });
+            // Without a named server the first two conditions still hold for every
+            // server there is — an operator's global switch and the caller's own
+            // capability do not vary by child. The last two do, so an answer that
+            // stopped there is reported as "depends", not as a refusal the caller
+            // could act on.
+            const dependsOnAServer = managed === undefined && (decision.refusal === 'child-asleep' || decision.refusal === 'child-era');
+            return structured({
+                era,
+                revision: REVISION[era],
+                hubVersion: VERSION,
+                caller: { declaresElicitation: declared !== undefined },
+                elicitation: dependsOnAServer
+                    ? { reason: 'you could be asked; whether a given server may ask depends on that server — name one to find out' }
+                    : {
+                        wouldForward: decision.forward,
+                        ...(decision.refusal ? { reason: REFUSAL_REASON[decision.refusal] } : {}),
+                        ...(managed ? { server: managed.name } : {})
+                    }
+            });
+        });
+    }
     return hub;
 }
 //# sourceMappingURL=hub.js.map

package/dist/index.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import express from 'express';
-import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { requireBearerAuth } from '@modelcontextprotocol/express';
 import { loadConfig, ConfigWatcher, warnMutableDockerImages } from './config.js';
 import { Supervisor, UpstreamAuthRegistry } from './supervisor.js';
 import { ToolCache } from './tool-cache.js';
 import { warnSingleFileMount } from './mount-check.js';
-import { serverRequestHandler, handleMcpRequest } from './proxy.js';
+import { serverRequestHandler, handleMcpRequest, createRoute } from './proxy.js';
 import { buildHubServer } from './hub.js';
 import { AuthStore, DEFAULT_CLIENT_LIMITS } from './auth/store.js';
 import { CimdResolver } from './auth/cimd.js';
-import { HubOAuthProvider } from './auth/provider.js';
-import { createAuthRoutes } from './auth/routes.js';
+import { createOidcInteractionRoutes } from './auth/oidc/interactions.js';
+import { mountOidcProvider } from './auth/oidc/mount.js';
+import { buildOidcProvider } from './auth/oidc/provider.js';
+import { OidcTokenVerifier } from './auth/oidc/verifier.js';
+import { authSecurityHeaders } from './auth/headers.js';
+import { createProtectedResourceRoutes } from './auth/protected-resource.js';
+import { createRegistrationManagementRoutes } from './auth/registration.js';
 import { createUpstreamRoutes } from './upstream/routes.js';
 import { healthHandler } from './health.js';
 import { installFileLogging } from './logfile.js';
@@ -19,6 +24,7 @@ import { canonicalResourceUrl, resourceUrlForRoute } from './auth/resource.js';
 import { ClientRequestGate } from './limits.js';
 import { runStdio } from './stdio.js';
 import { isMainModule } from './main-module.js';
+import { IDLE_TIMEOUT_MS } from './timings.js';
 /** How often the hub looks for registrations that have aged out. The windows
  *  are a day and three months, so this only has to be far below those. */
 const CLIENT_PRUNE_INTERVAL_MS = 15 * 60_000;
@@ -60,8 +66,10 @@ export async function createHub(options) {
     const idleTimeoutMinutes = options.idleTimeoutMinutes ?? 60;
     if (!Number.isSafeInteger(idleTimeoutMinutes) || idleTimeoutMinutes < 0)
         throw new Error('idleTimeoutMinutes must be a non-negative integer');
+    // IDLE_TIMEOUT_MS is the sub-minute sibling of the documented knob; see timings.ts.
+    const idleTimeoutMs = IDLE_TIMEOUT_MS || idleTimeoutMinutes * 60_000;
     const cache = new ToolCache(options.toolCachePath ?? path.join(options.dataPath, 'tool-cache.json'));
-    if (idleTimeoutMinutes > 0) {
+    if (idleTimeoutMs > 0) {
         cache.load();
         if (!cache.probeWritable()) {
             console.warn(`mcp-hub: tool cache ${cache.filePath} is not writable — on-demand servers warm-start at every boot instead of sleeping through it`);
@@ -85,12 +93,22 @@ export async function createHub(options) {
         }
     }
     const upstreamAuth = new UpstreamAuthRegistry(store, externalUrl);
-    const supervisor = new Supervisor(config, { idleTimeoutMinutes, cache, upstreamAuth });
+    const supervisor = new Supervisor(config, { idleTimeoutMinutes, idleTimeoutMs, cache, upstreamAuth });
     // start() before reapOrphans(): reaping spares the container of any server
     // that is not asleep, so it must see the boot states. Deliberately not
     // awaited: an unreachable Docker endpoint must not hold up the HTTP listener
     // or the stdio children. Children come up (or hydrate into `sleeping`) in
     // the background; paths answer 503 until then.
+    // One long-lived route for the aggregate, because the handler inside owns the
+    // open subscription streams. /hub carries tools and nothing else, so the only
+    // change worth relaying is a child's tool list moving; the supervisor
+    // publishes those here.
+    const hubRoute = createRoute(era => buildHubServer(supervisor, store.cookieSecret, era).server, {
+        label: '/hub',
+        // Every child, because the aggregate's tool list spans all of them.
+        onDemandChange: () => supervisor.reconcileAll()
+    });
+    supervisor.hubSubscriptions = hubRoute.registry;
     supervisor.start();
     void supervisor
         .reapOrphans()
@@ -112,13 +130,6 @@ export async function createHub(options) {
     const cimd = mechanisms.includes('cimd')
         ? new CimdResolver({ allowedOrigins: options.cimdAllowedOrigins, allowPrivateAddresses: options.cimdAllowPrivateAddresses })
         : undefined;
-    const provider = new HubOAuthProvider(store, externalUrl, {
-        requireResource,
-        resolveResource: resource => canonicalResourceUrl(resource, origin, watcher.current),
-        defaultResource: options.defaultResource !== undefined ? resourceUrlForRoute(origin, options.defaultResource) : undefined,
-        cimd,
-        allowDynamicRegistration: mechanisms.includes('dcr')
-    });
     const app = express();
     if (!options.trustedProxies?.length) {
         // Without this every request behind a proxy reports the proxy's address,
@@ -127,14 +138,65 @@ export async function createHub(options) {
     }
     app.set('trust proxy', options.trustedProxies ?? false);
     app.disable('x-powered-by');
+    /**
+     * A TRUSTED_PROXIES list that never matches is worse than an empty one,
+     * because the empty one is announced above and this is silent.
+     *
+     * The list is compared against the address the connection actually came from,
+     * and the easiest way to get that wrong is also the least visible: a proxy
+     * configured as `proxy_pass http://localhost:…` on a dual-stack host connects
+     * over `::1`, which `127.0.0.1` does not cover. Every forwarded header is
+     * then ignored, `req.ip` becomes the proxy for every request, per-caller rate
+     * limiting collapses into one global counter and every fail2ban line names
+     * the proxy — the exact failure the warning above exists for, with nothing
+     * said about it.
+     *
+     * Diagnosed rather than assumed: a forwarded header arrived and was not
+     * believed, which is the observable half of the mistake. Said once.
+     */
+    if (options.trustedProxies?.length) {
+        let warnedAboutProxy = false;
+        app.use((req, _res, next) => {
+            if (!warnedAboutProxy && req.headers['x-forwarded-for'] !== undefined && req.ip === req.socket.remoteAddress) {
+                warnedAboutProxy = true;
+                console.warn(`mcp-hub: a request from ${req.socket.remoteAddress} carried X-Forwarded-For but that address is not in TRUSTED_PROXIES ` +
+                    `(${options.trustedProxies?.join(', ')}), so the header was ignored — check for the 127.0.0.1 vs ::1 mismatch. ` +
+                    'Until it matches, per-caller rate limiting and the fail2ban log lines see only the proxy.');
+            }
+            next();
+        });
+    }
     // A liveness check intentionally carries no topology. Detailed child state
     // lives behind OAuth at /health.
     app.get('/livez', (_req, res) => res.status(200).json({ status: 'ok' }));
-    app.use(createAuthRoutes({ provider, store, externalUrl, passwordHash: options.passwordHash, password: options.password, cimd }));
+    // The resource server's own discovery document, independent of whichever
+    // authorization server is mounted below.
+    app.use(createProtectedResourceRoutes({ externalUrl }));
+    const oidc = buildOidcProvider(store, {
+        externalUrl,
+        requireResource,
+        resolveResource: resource => canonicalResourceUrl(resource, origin, watcher.current),
+        defaultResource: options.defaultResource !== undefined ? resourceUrlForRoute(origin, options.defaultResource) : undefined,
+        allowDynamicRegistration: mechanisms.includes('dcr'),
+        cimd
+    });
+    app.use(createOidcInteractionRoutes({
+        provider: oidc,
+        store,
+        externalUrl,
+        password: options.password,
+        passwordHash: options.passwordHash,
+        cimd
+    }));
+    // Ahead of the mount, so the hub's stricter RFC 7592 handlers win the
+    // /register/:id route over oidc-provider's.
+    if (mechanisms.includes('dcr'))
+        app.use(createRegistrationManagementRoutes({ store, externalUrl }));
+    mountOidcProvider(app, oidc, store, { externalUrl, common: [authSecurityHeaders] });
     // The upstream callback and the hub's own client metadata document. Mounted
     // after the auth routes so it inherits nothing from them but sits ahead of
     // the /:name catch-all.
-    app.use(createUpstreamRoutes({ store, provider, registry: upstreamAuth, supervisor, watcher, externalUrl }));
+    app.use(createUpstreamRoutes({ store, registry: upstreamAuth, supervisor, watcher, externalUrl }));
     // Registrations age out on a clock, not on traffic, so this cannot wait for
     // the next write to state.json — an idle hub would never clean up at all.
     // The first pass runs at boot, which is also what gives clients from a state
@@ -153,11 +215,27 @@ export async function createHub(options) {
     sweepClients();
     const pruneTimer = setInterval(sweepClients, CLIENT_PRUNE_INTERVAL_MS);
     pruneTimer.unref(); // never a reason to keep the process alive
-    const stopMaintenance = () => clearInterval(pruneTimer);
+    const stopMaintenance = () => {
+        clearInterval(pruneTimer);
+        // The aggregate's handler holds whatever listen streams are open on /hub;
+        // nothing else closes it, because it is not owned by a ManagedServer.
+        void hubRoute.close().catch(() => { });
+    };
     // Bearer auth for the MCP endpoints, advertising the path-scoped RFC 9728
     // metadata document in WWW-Authenticate so clients discover the AS.
+    const verifier = new OidcTokenVerifier(store, {
+        externalUrl,
+        requireResource,
+        resolveResource: resource => canonicalResourceUrl(resource, origin, watcher.current)
+    });
+    // From @modelcontextprotocol/express, not the frozen server-legacy copy the
+    // codemod reaches for by default. That copy exists for projects still running
+    // the SDK's own authorization server; the hub replaced its own with
+    // oidc-provider first, precisely so this dependency never had to be taken on.
+    // The one thing the maintained middleware needs in return is that the
+    // verifier throws v2's OAuthError -- see OidcTokenVerifier.
     const bearer = (req, res, next) => requireBearerAuth({
-        verifier: provider,
+        verifier,
         resourceMetadataUrl: `${origin}/.well-known/oauth-protected-resource${req.path === '/' ? '' : req.path}`
     })(req, res, next);
     // A bound token may only reach the resource it was issued for. An unbound one
@@ -187,7 +265,7 @@ export async function createHub(options) {
     const parseMcpJson = express.json({ limit: options.mcpBodyLimit ?? '1mb' });
     const dispatch = (name) => async (req, res, next) => {
         if (name === 'hub') {
-            await handleMcpRequest(() => buildHubServer(supervisor).server, req, res);
+            await handleMcpRequest(hubRoute, req, res);
             return;
         }
         const managed = supervisor.get(name);
@@ -195,10 +273,14 @@ export async function createHub(options) {
             next(); // fall through to 404
             return;
         }
-        await serverRequestHandler(managed)(req, res);
+        await serverRequestHandler(managed, store.cookieSecret)(req, res);
     };
     for (const route of ['/:name', '/:name/mcp']) {
-        app.all(route, bearer, gate.middleware, requireRouteResource, parseMcpJson, (req, res, next) => void dispatch(String(req.params.name))(req, res, next).catch(next));
+        // parseMcpJson ahead of the gate, which is a change of order: the gate has
+        // to tell a `subscriptions/listen` POST from an ordinary one, and that only
+        // shows in the parsed body. Authorization still runs first, so the parse is
+        // bounded by mcpBodyLimit and only ever done for a caller allowed to be here.
+        app.all(route, bearer, requireRouteResource, parseMcpJson, gate.middleware, (req, res, next) => void dispatch(String(req.params.name))(req, res, next).catch(next));
     }
     // Express only recognises a four-argument middleware as an error handler.
     // Without it a throw out of the proxy path would escape as an unhandled
@@ -215,7 +297,7 @@ export async function createHub(options) {
         }
         res.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' }, id: null });
     });
-    return { app, supervisor, watcher, provider, store, upstreamAuth, stopMaintenance };
+    return { app, supervisor, watcher, verifier, store, upstreamAuth, stopMaintenance };
 }
 function requireEnv(name) {
     const value = process.env[name];