@samanhappy/mcphub 1.1.9 → 1.1.11

package/dist/services/mcpService.js

@@ -1,18 +1,21 @@
+import { projectGroupToolName, assertValidGroupToolNames } from '../utils/groupToolNames.js';
 import { isSafePassthroughHeader } from '../utils/passthroughHeaders.js';
 import { observeToolCall, setMetricsServer } from './metricsService.js';
 import { hasPersonalOAuth, PersonalOAuthContext, personalOAuthContexts, personalAuthorizationRequired, } from './personalOAuthService.js';
 import { preserveListFreshness, combineListFreshness, remainingListTtl, } from '../utils/listFreshness.js';
 import { expandServerConfig, getServerEnvironment } from './serverConfigEnvironment.js';
 import { getMcpRequestGroup } from '../utils/mcpRequestGroup.js';
+import { revalidateUpstreamList } from './upstreamListRefresh.js';
 import { LegacyMcpClient } from '../clients/legacyMcpClient.js';
 import { getElicitationCapabilities, installElicitationRelay, isElicitationClientClosed, withElicitation, } from './elicitationService.js';
-import { LEGACY_PROTOCOL_VERSIONS } from '../utils/mcpProtocol.js';
+import { LEGACY_PROTOCOL_VERSIONS, resolveUpstreamProtocolMode } from '../utils/mcpProtocol.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash } from 'node:crypto';
 import { canAccessGroupRoute } from '../utils/groupAccess.js';
 import { canServeToolRequests } from '../utils/serverAvailability.js';
 import { assertToolCallArgumentsSafe, isToolCallGuardEnabled, ToolCallBlockedError, } from '../middlewares/toolCallGuard.js';
 import { applyHiddenParams, findToolConfig, removeHiddenArguments, } from '../utils/toolConfig.js';
+import { prepareCapabilitySnapshot, recordCapabilitySnapshot, flushCapabilitySnapshot, } from './capabilitySnapshotService.js';
 import { PrincipalRuntimeService } from './principalRuntimeService.js';
 import { UserContextService } from './userContextService.js';
 import { deleteCredentialBindings, missingCredentialError } from './credentialBindingService.js';
@@ -389,7 +392,7 @@ const getOrCreateIsolatedClient = async (sessionId, serverInfo, downstream) => {
         }
         const reservedClients = sessionIsolatedClients.get(sessionId);
         const transport = await createTransportFromConfig(serverInfo.name, serverConfig);
-        const client = createUpstreamMcpClient(serverInfo.name, () => serverInfo, downstream);
+        const client = createUpstreamMcpClient(serverInfo.name, () => serverInfo, serverConfig, downstream);
         try {
             await connectClientWithDiagnostics(client, transport, serverInfo.options || {});
         }
@@ -723,6 +726,8 @@ const createConnectGate = (limit) => {
 // result anywhere. See the `liveServerInfo` helper in that function.
 let initGeneration = 0;
 const principalServerScope = new AsyncLocalStorage();
+// Header-dependent discovery must never publish descriptors or embeddings globally.
+const requestDiscoveryInfos = new WeakSet();
 const getVisibleServerInfos = () => {
     return getDataService().filterData(principalServerScope.getStore() ?? serverInfos);
 };
@@ -825,6 +830,8 @@ export const setServerInfosForTest = (infos) => {
     serverInfos = infos;
 };
 export const updateServerToolsCache = (serverInfo, tools, options) => {
+    if (!options?.restored)
+        recordCapabilitySnapshot(serverInfo, tools);
     serverInfo.tools = preserveListFreshness(tools, tools.map((tool) => normalizeToolForCache(serverInfo.name, tool)));
     syncToolsAsVectorEmbeddings(serverInfo.name, serverInfo.tools, {
         reportProgress: options?.reportEmbeddingProgress === true,
@@ -838,15 +845,81 @@ const updateServerPromptsCache = (serverInfo, prompts) => {
 const updateServerResourcesCache = (serverInfo, resources) => {
     serverInfo.resources = preserveListFreshness(resources, resources.map(normalizeResourceForCache));
 };
+// Modern HTTP has no list-changed push stream. Refresh only the lists needed
+// by the current request; TTL and in-flight work are scoped to the live client.
+const refreshModernServerLists = async (info, fields) => {
+    const client = info.client;
+    if (!client ||
+        client.getProtocolEra?.() !== 'modern' ||
+        info.enabled === false ||
+        info.status !== 'connected')
+        return;
+    const capabilities = client.getServerCapabilities();
+    const current = () => info.client === client && info.enabled !== false && info.status === 'connected';
+    await Promise.all(fields.map(async (field) => {
+        if (!capabilities?.[field])
+            return;
+        await revalidateUpstreamList(client, field, async () => {
+            if (field === 'tools') {
+                const { tools } = await client.listTools({}, info.options || {});
+                if (!current())
+                    return;
+                if (hasPersonalAuthentication(info.config) || requestDiscoveryInfos.has(info)) {
+                    info.tools = preserveListFreshness(tools, tools.map((tool) => normalizeToolForCache(info.name, tool)));
+                    if (!requestDiscoveryInfos.has(info))
+                        recordCapabilitySnapshot(info, tools);
+                    if (!requestDiscoveryInfos.has(info))
+                        void syncCredentialServerToolEmbeddings(info.name, info.tools, {
+                            partial: true,
+                        }).catch(() => {
+                            logger.warn('[EMBED_SYNC_ERROR] Failed to sync personal tool embeddings');
+                        });
+                }
+                else {
+                    const previous = JSON.stringify(info.tools);
+                    updateServerToolsCache(info, tools);
+                    if (previous !== JSON.stringify(info.tools))
+                        broadcastToolListChanged();
+                }
+            }
+            else if (field === 'prompts') {
+                const { prompts } = await client.listPrompts({}, info.options || {});
+                if (current()) {
+                    const previous = JSON.stringify(info.prompts);
+                    updateServerPromptsCache(info, prompts);
+                    if (!hasPersonalAuthentication(info.config) &&
+                        !requestDiscoveryInfos.has(info) &&
+                        previous !== JSON.stringify(info.prompts))
+                        broadcastPromptListChanged();
+                }
+            }
+            else {
+                const { resources } = await client.listResources({}, info.options || {});
+                if (current()) {
+                    const previous = JSON.stringify(info.resources);
+                    updateServerResourcesCache(info, resources);
+                    if (!hasPersonalAuthentication(info.config) &&
+                        !requestDiscoveryInfos.has(info) &&
+                        previous !== JSON.stringify(info.resources))
+                        broadcastResourceListChanged();
+                }
+            }
+        });
+    }));
+};
 const logListChangedRefreshError = (listType) => {
     logger.warn(`Failed to refresh ${listType} list after upstream notification`);
 };
-const createUpstreamMcpClient = (name, getServerInfo, downstream) => {
+const createUpstreamMcpClient = (name, getServerInfo, serverConfig, downstream) => {
     const elicitation = getElicitationCapabilities(downstream);
+    // The existing relay only supports legacy server-to-client requests. Keep
+    // elicitation-enabled isolated clients legacy until an input_required bridge exists.
+    const mode = resolveUpstreamProtocolMode(serverConfig, Boolean(elicitation));
     const client = new LegacyMcpClient({
         name: `mcp-client-${name}`,
         version: '1.0.0',
     }, {
+        versionNegotiation: { mode },
         capabilities: { ...MCP_APPS_CAPABILITIES, ...(elicitation ? { elicitation } : {}) },
         jsonSchemaValidator: new ResilientJsonSchemaValidator(),
         listChanged: {
@@ -958,19 +1031,8 @@ export const cleanupAllServers = () => {
     for (const id of clientStates.keys())
         removeClientState(id);
     principalRuntimes.invalidate();
-    for (const serverInfo of serverInfos) {
-        try {
-            if (serverInfo.client) {
-                serverInfo.client.close();
-            }
-            if (serverInfo.transport) {
-                serverInfo.transport.close();
-            }
-        }
-        catch (error) {
-            logger.warn('Error closing server', { serverName: serverInfo.name, error });
-        }
-    }
+    for (const serverInfo of serverInfos)
+        closeServerRuntime(serverInfo);
     serverInfos = [];
     // Drain all per-session isolated upstream clients (perSessionClient: true),
     for (const sessionId of [...sessionIsolatedClients.keys()]) {
@@ -1374,6 +1436,38 @@ const withoutHiddenArguments = (serverInfo, toolName, args) => {
     const toolConfig = findToolConfig(serverInfo.config?.tools, serverInfo.name, runtimeName, (serverInfo.tools ?? []).map((candidate) => candidate.name));
     return removeHiddenArguments(args, tool?.inputSchema, toolConfig);
 };
+const failedCallRefreshes = new WeakMap();
+const refreshCapabilitiesAfterFailedCall = async (info) => {
+    if (!info.capabilityCache || !info.client || info.status !== 'connected')
+        return;
+    const pending = failedCallRefreshes.get(info);
+    if (pending)
+        return pending;
+    const refresh = (async () => {
+        try {
+            const { tools } = await info.client.listTools({}, info.options || {});
+            if (hasPersonalAuthentication(info.config)) {
+                info.tools = tools.map((tool) => normalizeToolForCache(info.name, tool));
+                recordCapabilitySnapshot(info, tools);
+            }
+            else {
+                updateServerToolsCache(info, tools);
+                broadcastToolListChanged();
+            }
+            await flushCapabilitySnapshot(info);
+        }
+        catch {
+            logger.warn('Unable to refresh capability snapshot after failed call');
+        }
+    })();
+    failedCallRefreshes.set(info, refresh);
+    try {
+        await refresh;
+    }
+    finally {
+        failedCallRefreshes.delete(info);
+    }
+};
 // Helper function to handle client.callTool with reconnection logic
 const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries = 1, isolated, extra) => {
     // Local, reassignable refs so a reconnect can swap in the new connection for
@@ -1390,19 +1484,37 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
         arguments: withoutHiddenArguments(serverInfo, toolParams.name, toolParams.arguments),
     };
     if (hasPersonalAuthentication(serverInfo.config)) {
-        return client.callTool(toolParams, options || {});
+        try {
+            const result = await client.callTool(toolParams, options || {});
+            if (result.isError)
+                await refreshCapabilitiesAfterFailedCall(serverInfo);
+            return result;
+        }
+        catch (error) {
+            await refreshCapabilitiesAfterFailedCall(serverInfo);
+            throw error;
+        }
     }
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             const currentClient = client;
             const result = await withElicitation(currentClient, extra?.mcpReq, options || {}, async (callOptions) => {
-                const result = await currentClient.callTool(toolParams, callOptions);
+                // Isolated clients do not own the refreshed discovery client's tool definitions.
+                const toolDefinition = isolated && currentClient.getProtocolEra?.() === 'modern'
+                    ? serverInfo.tools.find((tool) => normalizeToolNameForServer(serverInfo.name, tool.name) === toolParams.name)
+                    : undefined;
+                const result = await currentClient.callTool(toolParams, toolDefinition
+                    ? { ...callOptions, toolDefinition: toolDefinition }
+                    : callOptions);
                 checkAuthError(result);
                 return result;
             });
+            if (result.isError)
+                await refreshCapabilitiesAfterFailedCall(serverInfo);
             return result;
         }
         catch (error) {
+            await refreshCapabilitiesAfterFailedCall(serverInfo);
             if (isElicitationClientClosed(client)) {
                 closeIsolatedClient(serverInfo.name, client, transport);
                 throw error;
@@ -1427,7 +1539,7 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
                     // Match initial connection expansion before URL validation and transport creation.
                     const server = await expandServerConfig(rawConfig);
                     const newTransport = await createTransportFromConfig(serverInfo.name, server);
-                    const newClient = createUpstreamMcpClient(serverInfo.name, () => serverInfo);
+                    const newClient = createUpstreamMcpClient(serverInfo.name, () => serverInfo, server);
                     // Reconnect with new transport
                     await connectClientWithDiagnostics(newClient, newTransport, serverInfo.options || {});
                     if (isolated) {
@@ -1455,6 +1567,8 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
                             serverInfo.keepAliveIntervalId = undefined;
                         }
                         try {
+                            if (serverInfo.client)
+                                serverInfo.client.onclose = undefined;
                             serverInfo.client?.close();
                         }
                         catch {
@@ -1498,6 +1612,8 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
                     if (!isolated) {
                         serverInfo.status = 'disconnected';
                         serverInfo.error = `Failed to reconnect: ${formatErrorForLogging(reconnectError)}`;
+                        if (serverInfo.config)
+                            setupServerKeepAlive(serverInfo, serverInfo.config);
                     }
                     // If this was the last attempt, throw the original error
                     if (attempt === maxRetries) {
@@ -1506,7 +1622,17 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
                 }
             }
             else {
-                // Not an HTTP 40x error or no more retries, throw the original error
+                const status = error?.status ?? error?.response?.status ?? error?.code;
+                const connectionFailed = isUpstreamConnectionFailure(error) ||
+                    isUpstreamConnectionFailure(error?.cause) ||
+                    (error instanceof TypeError && error.message === 'fetch failed') ||
+                    (typeof status === 'number' && status >= 500 && status < 600);
+                if (!isolated && (isStreamableHttp || isSSE) && connectionFailed) {
+                    serverInfo.status = 'disconnected';
+                    serverInfo.error = formatErrorForLogging(error);
+                    if (serverInfo.config)
+                        setupServerKeepAlive(serverInfo, serverInfo.config);
+                }
                 throw error;
             }
         }
@@ -1515,16 +1641,22 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
     throw new Error('Unexpected error in callToolWithReconnect');
 };
 const setupServerKeepAlive = (serverInfo, serverConfig) => {
+    const client = serverInfo.client;
+    if (client &&
+        serverInfo.status === 'connected' &&
+        (serverInfo.transport instanceof SSEClientTransport ||
+            serverInfo.transport instanceof StreamableHTTPClientTransport)) {
+        client.onclose = () => {
+            const current = getServerByName(serverInfo.name);
+            if (current?.client !== client || current.status !== 'connected')
+                return;
+            current.status = 'disconnected';
+            current.error = 'Upstream connection closed';
+            setupServerKeepAlive(current, serverConfig);
+        };
+    }
     setupClientKeepAlive(serverInfo, serverConfig, {
-        reconnectServer: async (serverName) => {
-            try {
-                await reconnectServer(serverName);
-            }
-            catch (error) {
-                setupServerKeepAlive(serverInfo, serverConfig);
-                throw error;
-            }
-        },
+        reconnectServer,
     }).catch((error) => logger.warn('Keepalive setup failed', {
         serverName: serverInfo.name,
         error: summarizeErrorForLogging(error),
@@ -1602,6 +1734,7 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
             // connection) so the tool list stays visible to agents even while sleeping.
             if (expandedConf.startOnDemand === true && isStdioServer(expandedConf)) {
                 const existingOnDemand = existingServerInfos.find((s) => s.name === name);
+                const configChanged = JSON.stringify(existingOnDemand?.config) !== JSON.stringify(expandedConf);
                 // Active calls, spawn promises and idle callbacks must share the same
                 // runtime object across reloads, not copies of its mutable state.
                 const onDemandInfo = existingOnDemand ?? {
@@ -1620,6 +1753,14 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                     enabled: true,
                     config: expandedConf,
                 });
+                const cachedTools = await prepareCapabilitySnapshot(onDemandInfo, expandedConf);
+                if (cachedTools !== undefined) {
+                    if (!existingOnDemand || configChanged || onDemandInfo.tools.length === 0)
+                        updateServerToolsCache(onDemandInfo, cachedTools, { restored: true });
+                }
+                else if (configChanged || onDemandInfo.capabilityCache?.state === 'stale') {
+                    onDemandInfo.tools = [];
+                }
                 nextServerInfos.push(onDemandInfo);
                 logger.log(`Skipping startup connect for on-demand server: ${name}`);
                 continue;
@@ -1641,18 +1782,25 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
             if (existingServer &&
                 (isDifferentServer ||
                     (!serverName && (existingServer.status === 'connected' || hasInflightOAuthAuthorization)))) {
-                nextServerInfos.push({
-                    ...existingServer,
+                // Timer callbacks must keep owning the published runtime entry.
+                Object.assign(existingServer, {
                     owner: expandedConf.owner,
                     visibility: expandedConf.visibility,
                     sharedWithUsers: expandedConf.sharedWithUsers,
                     enabled: expandedConf.enabled === undefined ? true : expandedConf.enabled,
                 });
+                nextServerInfos.push(existingServer);
                 logger.log(hasInflightOAuthAuthorization
                     ? `Server '${name}' has an in-flight OAuth authorization; preserving existing state.`
                     : `Server '${name}' is already connected.`);
                 continue;
             }
+            if (existingServer?.keepAliveIntervalId) {
+                clearInterval(existingServer.keepAliveIntervalId);
+                existingServer.keepAliveIntervalId = undefined;
+            }
+            if (existingServer?.client)
+                existingServer.client.onclose = undefined;
             let transport;
             let openApiClient;
             if (expandedConf.type === 'openapi') {
@@ -1785,7 +1933,7 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                 }
             }
             const serverInfoRef = {};
-            const client = createUpstreamMcpClient(name, () => serverInfoRef.current);
+            const client = createUpstreamMcpClient(name, () => serverInfoRef.current, expandedConf);
             // Get request options from server configuration, with fallbacks
             const serverRequestOptions = expandedConf.options || {};
             const defaultRequestTimeout = Number(process.env.DEFAULT_REQUEST_TIMEOUT) || 60000;
@@ -1807,7 +1955,8 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                 visibility: expandedConf.visibility,
                 sharedWithUsers: expandedConf.sharedWithUsers,
                 status: 'connecting',
-                error: null,
+                recovery: existingServer?.recovery,
+                error: existingServer?.recovery ? existingServer.error : null,
                 tools: [],
                 prompts: [],
                 resources: [],
@@ -1821,6 +1970,7 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
             const pendingAuth = expandedConf.oauth?.pendingAuthorization;
             if (pendingAuth) {
                 serverInfo.status = 'oauth_required';
+                serverInfo.recovery = undefined;
                 serverInfo.error = null;
                 serverInfo.oauth = {
                     authorizationUrl: pendingAuth.authorizationUrl,
@@ -1828,19 +1978,8 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                 };
             }
             nextServerInfos.push(serverInfo);
-            // The connect below settles long after this loop returns. If another
-            // initialization pass has run by then, `serverInfo` may no longer be the
-            // object `serverInfos` holds for this server - even when the reuse guard
-            // "preserved" it, because preservation spreads the entry into a fresh
-            // object. Writing the result into a replaced object leaves the server
-            // stuck on 'connecting' for good while the log reports a successful
-            // connect and a full tool list.
-            //
-            // While this pass is still the newest one, `serverInfo` is the entry that
-            // will be published, so it is the right target even before the swap. Once
-            // a later pass has run, resolve the live entry by name and only apply the
-            // result if it still owns this client - which is exactly the case where
-            // the later pass preserved this server rather than reconnecting it.
+            // Before publication this pass owns the entry; after another pass, only
+            // publish connection results if the live runtime still owns this client.
             const liveServerInfo = () => {
                 if (generation === initGeneration)
                     return serverInfo;
@@ -1991,6 +2130,7 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                         info.status = 'oauth_required';
                     }
                     info.error = null;
+                    info.recovery = undefined;
                 }
                 else {
                     logger.error('Failed to connect client for server', {
@@ -2103,7 +2243,7 @@ export const getServersInfo = async (page, limit, user) => {
                     authorizationUrl: personal.authorizationUrl,
                 }
                 : undefined;
-            const lease = await principalRuntimes.acquire(info.name, principal);
+            const lease = await principalRuntimes.acquire(info.name, principal, true);
             try {
                 return { ...lease.info, config: info.config, ...(ownOAuth ? { oauth: ownOAuth } : {}) };
             }
@@ -2123,7 +2263,7 @@ export const getServersInfo = async (page, limit, user) => {
     }));
     const infos = presentedInfos
         .filter((info) => requestedServerNames.has(info.name)) // Only include requested servers
-        .map(({ name, version, packageVersion, latestVersion, updateAvailable, instructions, owner, visibility, status, tools, prompts, resources, createTime, error, oauth, }) => {
+        .map(({ name, version, client, packageVersion, latestVersion, updateAvailable, instructions, owner, visibility, status, tools, prompts, resources, createTime, capabilityCache, error, recovery, oauth, }) => {
         const serverConfig = allServers.find((server) => server.name === name);
         const enabled = serverConfig ? serverConfig.enabled !== false : true;
         const resolvedType = inferServerType(serverConfig);
@@ -2154,12 +2294,17 @@ export const getServersInfo = async (page, limit, user) => {
         return {
             name,
             version,
+            recovery: enabled ? recovery : undefined,
+            protocolVersion: enabled && status === 'connected' && resolvedType !== 'openapi'
+                ? client?.getNegotiatedProtocolVersion?.()
+                : undefined,
             instructions,
             owner,
             visibility,
             status,
             error,
             tools: toolsWithEnabled,
+            ...(capabilityCache ? { capabilityCache } : {}),
             prompts: promptsWithEnabled,
             resources: resourcesWithEnabled,
             createTime,
@@ -2238,6 +2383,7 @@ export const reconnectServer = async (serverName) => {
     }
     // Close existing connection if any
     if (serverInfo.client) {
+        serverInfo.client.onclose = undefined;
         try {
             serverInfo.client.close();
         }
@@ -2259,7 +2405,7 @@ export const reconnectServer = async (serverName) => {
     }
     // Reinitialize the server
     await initializeClientsFromSettings(false, serverName);
-    logger.log(`Successfully reconnected server: ${serverName}`);
+    logger.log(`Scheduled connection initialization for server: ${serverName}`);
 };
 /**
  * Resolve the installed package version for an npx/uvx stdio server and record
@@ -2519,6 +2665,9 @@ const clearIdleShutdown = (serverInfo) => {
 };
 const closeServerRuntime = (serverInfo) => {
     clearIdleShutdown(serverInfo);
+    if (serverInfo.client)
+        serverInfo.client.onclose = undefined;
+    serverInfo.recovery = undefined;
     if (serverInfo.keepAliveIntervalId) {
         clearInterval(serverInfo.keepAliveIntervalId);
         serverInfo.keepAliveIntervalId = undefined;
@@ -2646,10 +2795,11 @@ const ensureServerReady = async (serverInfo) => {
         if (expandedConf.type === 'openapi') {
             return;
         }
+        await prepareCapabilitySnapshot(serverInfo, expandedConf);
         const name = rawConfig.name;
         logger.log(`[${name}] Cold-starting on-demand server…`);
         const transport = await createTransportFromConfig(name, expandedConf);
-        const client = createUpstreamMcpClient(name, () => serverInfo);
+        const client = createUpstreamMcpClient(name, () => serverInfo, expandedConf);
         const serverRequestOptions = expandedConf.options || {};
         const defaultRequestTimeout = Number(process.env.DEFAULT_REQUEST_TIMEOUT) || 60000;
         const requestOptions = {
@@ -2687,6 +2837,11 @@ const ensureServerReady = async (serverInfo) => {
                 });
             }
         }
+        else {
+            updateServerToolsCache(serverInfo, []);
+            broadcastToolListChanged();
+        }
+        await flushCapabilitySnapshot(serverInfo);
         if (capabilities?.prompts) {
             try {
                 const prompts = await client.listPrompts({}, requestOptions);
@@ -2750,6 +2905,7 @@ const primeOnDemandServers = (gate) => {
         !hasPersonalAuthentication(si.config) &&
         isStdioServer(si.config) &&
         si.tools.length === 0 &&
+        si.capabilityCache?.state !== 'fresh' &&
         si.enabled !== false);
     if (targets.length === 0)
         return Promise.resolve();
@@ -2763,7 +2919,10 @@ const primeOnDemandServers = (gate) => {
             await run(() => ensureServerReady(si), 
             // A reload may replace this runtime or finish its discovery while it
             // waits for a slot. Neither needs another child from the old queue.
-            () => serverInfos.includes(si) && si.enabled !== false && si.tools.length === 0);
+            () => serverInfos.includes(si) &&
+                si.enabled !== false &&
+                si.tools.length === 0 &&
+                si.capabilityCache?.state !== 'fresh');
             // Sleep the child unless a tool call is using it; keep the cached tool list.
             shutdownOnDemandServer(si);
             logger.log('On-demand server tool cache primed');
@@ -3046,7 +3205,7 @@ const assertToolAvailableForRoute = (tool, appsRouteContext) => {
         throw new Error(`Tool '${tool.name}' is only available to MCP Apps`);
     }
 };
-const resolveToolInGroup = async (group, toolName) => {
+const resolveToolInGroup = async (group, toolName, appsRouteContext) => {
     const lookupGroup = getGroupLookupName(group);
     if (!lookupGroup) {
         return undefined;
@@ -3058,22 +3217,30 @@ const resolveToolInGroup = async (group, toolName) => {
     const allowRawName = !isSmartRoutingGroup(group) &&
         serverConfigsByName.size <= 1 &&
         filteredServerInfos.length === 1;
+    // Validate the full visible catalog before routing, even if the client skips tools/list.
+    const hasOriginalToolNames = [...serverConfigsByName.values()].some((config) => config.preserveToolNames);
+    if (hasOriginalToolNames) {
+        await listGroupTools(lookupGroup, filteredServerInfos, serverConfigsByName, appsRouteContext);
+    }
     for (const serverInfo of filteredServerInfos) {
         // An idle on-demand server is selected here and woken by the caller (#1029)
         if (!canServeToolRequests(serverInfo)) {
             continue;
         }
         const serverConfig = serverConfigsByName.get(serverInfo.name);
-        const internalToolName = resolveNameFromGroup(toolName, serverInfo.name, serverConfig);
+        const internalToolName = serverConfig?.preserveToolNames
+            ? `${serverInfo.name}${getNameSeparator()}${toolName}`
+            : resolveNameFromGroup(toolName, serverInfo.name, serverConfig);
         const tool = findToolOnServer(serverInfo, internalToolName, allowRawName, serverConfigsByName.size === 0);
-        if (!tool) {
+        if (!tool || (hasOriginalToolNames && !appsRouteContext.enabled && isAppOnlyTool(tool))) {
             continue;
         }
         const filteredTools = await filterToolsByGroup(lookupGroup, serverInfo.name, [tool], serverConfig);
         if (filteredTools.length === 0) {
             continue;
         }
-        return { serverInfo, toolName: internalToolName, tool };
+        // Retain the resolved identity when callers revalidate discovery after waking.
+        return { serverInfo, toolName: tool.name, tool };
     }
     return undefined;
 };
@@ -3127,7 +3294,7 @@ const projectToolForDownstream = (serverName, tool, appsRouteContext, serverConf
     // Group and aggregate routes keep qualified names, including single-member groups.
     return {
         ...projectedTool,
-        name: projectNameForGroup(projectedTool.name, serverName, serverConfig),
+        name: projectGroupToolName(projectedTool.name, serverName, serverConfig, getNameSeparator()),
     };
 };
 const listGroupTools = async (group, filteredServerInfos, serverConfigsByName, appsRouteContext) => {
@@ -3135,7 +3302,10 @@ const listGroupTools = async (group, filteredServerInfos, serverConfigsByName, a
     // so this list reflects the freshly cached tools instead of returning empty.
     // No wake is triggered from list itself; the prime handles that. See #1029.
     await Promise.allSettled(filteredServerInfos
-        .filter((si) => si.config?.startOnDemand === true && si.tools.length === 0 && si.spawningPromise)
+        .filter((si) => si.config?.startOnDemand === true &&
+        si.tools.length === 0 &&
+        si.capabilityCache?.state !== 'fresh' &&
+        si.spawningPromise)
         .map((si) => si.spawningPromise));
     const useRawName = !!group && !isSmartRoutingGroup(group) && !(await findRouteGroup(group));
     const allTools = [];
@@ -3162,6 +3332,9 @@ const listGroupTools = async (group, filteredServerInfos, serverConfigsByName, a
             }));
         }
     }
+    if ([...serverConfigsByName.values()].some((config) => config.preserveToolNames)) {
+        assertValidGroupToolNames(allTools);
+    }
     return allTools;
 };
 // Names the call handler always routes to a meta-tool on a Smart Routing session,
@@ -3351,7 +3524,7 @@ const handleCallToolRequestImpl = async (request, extra) => {
                 targetServerInfo = getVisibleServerByName(extra.server);
             }
             else if (getGroupLookupName(group)) {
-                const groupTool = await resolveToolInGroup(group, toolName);
+                const groupTool = await resolveToolInGroup(group, toolName, appsRouteContext);
                 if (groupTool) {
                     targetServerInfo = groupTool.serverInfo;
                     targetToolName = groupTool.toolName;
@@ -3376,6 +3549,8 @@ const handleCallToolRequestImpl = async (request, extra) => {
             if (targetServerInfo.config?.startOnDemand && targetServerInfo.status !== 'connected') {
                 await ensureServerReady(targetServerInfo);
                 // Re-read status from the mutated serverInfo after async spawn
+                // Routing may have captured a tool from the persisted directory before wake.
+                targetTool = undefined;
                 const freshStatus = targetServerInfo.status;
                 if (freshStatus !== 'connected') {
                     throw new Error(`Failed to start on-demand server '${targetServerInfo.name}' — check server logs`);
@@ -3549,13 +3724,13 @@ const handleCallToolRequestImpl = async (request, extra) => {
         // Apps support; keep legacy raw aggregate calls compatible.
         const singleServerAppsRoute = !getGroupLookupName(group) && !!appsRouteContext.serverInfo;
         const groupTool = !singleServerAppsRoute && lookupGroup
-            ? await resolveToolInGroup(group, request.params.name)
+            ? await resolveToolInGroup(group, request.params.name, appsRouteContext)
             : undefined;
         const serverInfo = singleServerAppsRoute
             ? appsRouteContext.serverInfo
             : (groupTool?.serverInfo ?? (lookupGroup ? undefined : getServerByTool(request.params.name)));
         const routeToolName = groupTool?.toolName ?? request.params.name;
-        const tool = groupTool?.tool ??
+        let tool = groupTool?.tool ??
             (serverInfo ? findToolOnServer(serverInfo, routeToolName, singleServerAppsRoute) : undefined);
         if (!serverInfo || !tool) {
             throw new ToolUnavailableError(`Tool not available: ${request.params.name}`, classifyUnavailableReason(request.params.name));
@@ -3568,6 +3743,10 @@ const handleCallToolRequestImpl = async (request, extra) => {
         releaseOnDemandToolCall = beginOnDemandToolCall(serverInfo);
         if (serverInfo.config?.startOnDemand && serverInfo.status !== 'connected') {
             await ensureServerReady(serverInfo);
+            tool = findToolOnServer(serverInfo, routeToolName, singleServerAppsRoute);
+            if (!tool)
+                throw new ToolUnavailableError(`Tool not available: ${request.params.name}`, 'tool-not-found');
+            assertToolAvailableForRoute(tool, appsRouteContext);
         }
         serverInfo.lastUsedAt = Date.now();
         // Handle OpenAPI servers differently
@@ -4118,10 +4297,41 @@ const handleReadResourceRequestImpl = async (request, extra) => {
         };
     }
 };
+// Preserve credential-safe errors for personal clients in every discovery scope.
+const personalClientMethods = new Set([
+    'callTool',
+    'getPrompt',
+    'readResource',
+    'listTools',
+    'listPrompts',
+    'listResources',
+    'listResourceTemplates',
+]);
+const protectPersonalClient = (client, info, resolvedConfig) => new Proxy(client, {
+    get(target, property) {
+        const value = Reflect.get(target, property);
+        if (typeof value !== 'function')
+            return value;
+        if (!personalClientMethods.has(String(property)))
+            return value.bind(target);
+        return async (...args) => {
+            try {
+                return await value.apply(target, args);
+            }
+            catch (error) {
+                if (isUpstreamConnectionFailure(error))
+                    info.status = 'disconnected';
+                const failure = createUpstreamRequestError(info.name, String(property), error, resolvedConfig);
+                logger.error(failure.message);
+                throw failure;
+            }
+        };
+    },
+});
 // Personal runtimes never enter serverInfos or config exports. Their tool list
 // is added to the rows under the server name, the index the reindex endpoint
 // rebuilds from every binding.
-const createPrincipalRuntime = async (name, resolvedConfig) => {
+const createPrincipalRuntime = async (name, resolvedConfig, scope, toolsOnly = false) => {
     const info = {
         name,
         owner: resolvedConfig.owner,
@@ -4137,41 +4347,22 @@ const createPrincipalRuntime = async (name, resolvedConfig) => {
         resources: [],
         createTime: Date.now(),
     };
-    const safeMethods = new Set([
-        'callTool',
-        'getPrompt',
-        'readResource',
-        'listTools',
-        'listPrompts',
-        'listResources',
-        'listResourceTemplates',
-    ]);
-    const protectClient = (client) => new Proxy(client, {
-        get(target, property) {
-            const value = Reflect.get(target, property);
-            if (typeof value !== 'function')
-                return value;
-            if (!safeMethods.has(String(property)))
-                return value.bind(target);
-            return async (...args) => {
-                try {
-                    return await value.apply(target, args);
-                }
-                catch (error) {
-                    if (isUpstreamConnectionFailure(error))
-                        info.status = 'disconnected';
-                    const failure = createUpstreamRequestError(name, String(property), error, resolvedConfig);
-                    logger.error(failure.message);
-                    throw failure;
-                }
-            };
-        },
-    });
+    const cachedTools = await prepareCapabilitySnapshot(info, resolvedConfig, scope);
+    if (toolsOnly) {
+        if (cachedTools === undefined)
+            return undefined;
+        info.tools = cachedTools.map((tool) => normalizeToolForCache(name, tool));
+        void syncCredentialServerToolEmbeddings(name, info.tools, { partial: true }).catch(() => {
+            logger.warn('[EMBED_SYNC_ERROR] Failed to sync personal tool embeddings');
+        });
+        info.status = 'disconnected';
+        return info;
+    }
     try {
         if (resolvedConfig.type === 'openapi') {
             const client = new OpenAPIClient(resolvedConfig);
             await client.initialize();
-            info.openApiClient = protectClient(client);
+            info.openApiClient = protectPersonalClient(client, info, resolvedConfig);
             info.tools = client.getTools().map((tool) => ({
                 ...tool,
                 name: `${name}${getNameSeparator()}${tool.name}`,
@@ -4181,17 +4372,23 @@ const createPrincipalRuntime = async (name, resolvedConfig) => {
         else {
             const transport = await createTransportFromConfig(name, resolvedConfig);
             const client = new LegacyMcpClient({ name: `mcp-client-${name}`, version: '1.0.0' }, {
+                versionNegotiation: { mode: resolveUpstreamProtocolMode(resolvedConfig) },
                 capabilities: MCP_APPS_CAPABILITIES,
                 jsonSchemaValidator: new ResilientJsonSchemaValidator(),
             });
             info.transport = transport;
-            info.client = protectClient(client);
+            info.client = protectPersonalClient(client, info, resolvedConfig);
             await client.connect(transport, resolvedConfig.options || {});
             const capabilities = client.getServerCapabilities();
             if (capabilities?.tools) {
                 const { tools } = await client.listTools({}, resolvedConfig.options);
                 info.tools = preserveListFreshness(tools, tools.map((tool) => normalizeToolForCache(name, tool)));
+                recordCapabilitySnapshot(info, tools);
             }
+            else {
+                recordCapabilitySnapshot(info, []);
+            }
+            await flushCapabilitySnapshot(info);
             if (capabilities?.prompts) {
                 const { prompts } = await client.listPrompts({}, resolvedConfig.options);
                 info.prompts = preserveListFreshness(prompts, prompts.map((prompt) => normalizePromptForCache(name, prompt)));
@@ -4226,7 +4423,7 @@ const createPrincipalRuntime = async (name, resolvedConfig) => {
         throw failure;
     }
 };
-const principalRuntimes = new PrincipalRuntimeService(createPrincipalRuntime, closeServerRuntime);
+const principalRuntimes = new PrincipalRuntimeService(async (name, config, scope) => (await createPrincipalRuntime(name, config, scope)), closeServerRuntime, (name, config, scope) => createPrincipalRuntime(name, config, scope, true));
 /**
  * Resolve the tools of a personal-credential server on behalf of an explicit
  * principal, outside any request context.
@@ -4243,12 +4440,112 @@ const principalRuntimes = new PrincipalRuntimeService(createPrincipalRuntime, cl
 export const getServerToolsForPrincipal = async (serverName, principal) => {
     const lease = await principalRuntimes.acquire(serverName, principal);
     try {
+        await refreshModernServerLists(lease.info, ['tools']);
         return lease.info.tools ?? [];
     }
     finally {
         lease.release();
     }
 };
+const withModernLists = (handler, fields) => async (request, extra) => {
+    if (!(principalServerScope.getStore() ?? serverInfos).some((info) => info.client?.getProtocolEra?.() === 'modern')) {
+        return handler(request, extra);
+    }
+    // Built-in content must not depend on an unrelated upstream being healthy.
+    if (fields[0] === 'prompts' && request.method === 'prompts/get' && !extra?.server) {
+        const builtin = await getBuiltinPromptDao().findByName(request.params?.name);
+        if (builtin && builtin.enabled !== false)
+            return handler(request, extra);
+    }
+    if (fields[0] === 'resources' && request.method === 'resources/read') {
+        const builtin = await getBuiltinResourceDao().findByUri(request.params?.uri);
+        if (builtin && builtin.enabled !== false)
+            return handler(request, extra);
+    }
+    const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(getGroupLookupName(getMcpRequestGroup(extra)));
+    const requestedName = ['call_tool', 'describe_tool'].includes(request?.params?.name)
+        ? request.params.arguments?.toolName
+        : request?.params?.name;
+    let selected = filteredServerInfos;
+    if (extra?.server) {
+        selected = selected.filter((info) => info.name === extra.server);
+    }
+    else if (typeof requestedName === 'string' &&
+        !(fields[0] === 'tools' &&
+            [...serverConfigsByName.values()].some((config) => config.preserveToolNames))) {
+        // Match the routing resolver's longest exposed prefix, including aliases.
+        const targets = selected
+            .map((info) => ({
+            info,
+            prefix: `${getExposedServerName(info.name, serverConfigsByName.get(info.name))}${getNameSeparator()}`,
+        }))
+            .filter(({ prefix }) => requestedName.startsWith(prefix))
+            .sort((a, b) => b.prefix.length - a.prefix.length);
+        if (targets.length)
+            selected = [targets[0].info];
+    }
+    const scoped = new Map((principalServerScope.getStore() ?? serverInfos).map((info) => [info.name, info]));
+    const requestClients = [];
+    try {
+        await Promise.all(selected.map(async (info) => {
+            try {
+                let discoveryInfo = info;
+                const serverConfig = info.config;
+                if (info.status === 'connected' &&
+                    info.client?.getProtocolEra?.() === 'modern' &&
+                    serverConfig?.passthroughHeaders?.some(isSafePassthroughHeader)) {
+                    // Reuse neither snapshots nor pending work across forwarded identities.
+                    // A disposable modern client also isolates SDK tool definitions and read caches.
+                    const transport = await createTransportFromConfig(info.name, serverConfig);
+                    const client = new LegacyMcpClient({ name: `mcp-client-${info.name}`, version: '1.0.0' }, {
+                        versionNegotiation: {
+                            mode: { pin: info.client.getNegotiatedProtocolVersion() },
+                        },
+                        capabilities: MCP_APPS_CAPABILITIES,
+                        jsonSchemaValidator: new ResilientJsonSchemaValidator(),
+                    });
+                    discoveryInfo = { ...info, client, transport, tools: [], prompts: [], resources: [] };
+                    if (hasPersonalAuthentication(serverConfig)) {
+                        discoveryInfo.client = protectPersonalClient(client, discoveryInfo, serverConfig);
+                    }
+                    requestClients.push(discoveryInfo.client);
+                    requestDiscoveryInfos.add(discoveryInfo);
+                    scoped.set(info.name, discoveryInfo);
+                    await connectClientWithDiagnostics(client, transport, info.options || {});
+                }
+                await refreshModernServerLists(discoveryInfo, fields);
+            }
+            catch {
+                // Exclude only this upstream for this request. Keep its shared state
+                // intact so later requests retry; disconnected projections force TTL zero.
+                scoped.set(info.name, {
+                    ...info,
+                    status: 'disconnected',
+                    client: undefined,
+                    tools: [],
+                    prompts: [],
+                    resources: [],
+                });
+                logger.warn('Failed to refresh upstream discovery for request', {
+                    serverName: info.name,
+                });
+            }
+        }));
+        return await principalServerScope.run([...scoped.values()], () => handler(request, extra));
+    }
+    finally {
+        await Promise.all([
+            ...new Set([
+                ...requestClients,
+                ...[...scoped.values()]
+                    .filter((info) => requestDiscoveryInfos.has(info))
+                    .flatMap((info) => (info.client ? [info.client] : [])),
+            ]),
+        ].map((client) => client.close().catch(() => {
+            logger.warn('Failed to close request discovery client');
+        })));
+    }
+};
 const withPrincipalServers = (handler, operation) => async (request, extra) => {
     if (!serverInfos.some((info) => hasPersonalAuthentication(info.config)))
         return handler(request, extra);
@@ -4274,7 +4571,10 @@ const withPrincipalServers = (handler, operation) => async (request, extra) => {
     if (extra?.server && !target && (operation === 'tool' || operation === 'prompt')) {
         throw new ToolUnavailableError(`Tool not available: ${requestedName}`, 'server-or-name-not-found');
     }
-    if (!extra?.server && typeof requestedName === 'string') {
+    if (!extra?.server &&
+        typeof requestedName === 'string' &&
+        !(operation === 'tool' &&
+            [...serverConfigsByName.values()].some((config) => config.preserveToolNames))) {
         let longestPrefix = 0;
         for (const info of candidates) {
             const exposedName = getExposedServerName(info.name, serverConfigsByName.get(info.name));
@@ -4303,7 +4603,7 @@ const withPrincipalServers = (handler, operation) => async (request, extra) => {
                     throw hasPersonalOAuth(info.config)
                         ? personalAuthorizationRequired(info.name)
                         : missingCredentialError(info.name);
-                const lease = await principalRuntimes.acquire(info.name, user);
+                const lease = await principalRuntimes.acquire(info.name, user, operation === 'tools-list');
                 releases.push(lease.release);
                 scoped.set(info.name, lease.info);
             }
@@ -4314,7 +4614,10 @@ const withPrincipalServers = (handler, operation) => async (request, extra) => {
             }
         }));
         const requiredTarget = target ||
-            (candidates.length === 1 && operation !== 'list' && requestedName !== 'search_tools'
+            (candidates.length === 1 &&
+                operation !== 'list' &&
+                operation !== 'tools-list' &&
+                requestedName !== 'search_tools'
                 ? templated[0]
                 : undefined);
         const failure = requiredTarget ? failures.get(requiredTarget.name) : undefined;
@@ -4443,14 +4746,16 @@ const withCacheHints = (handler, passthroughTtl = false, listField) => async (re
     // and capabilities. Shared caches must not reuse the gateway result across users.
     return { ...result, ttlMs, cacheScope: 'private' };
 };
-export const handleListToolsRequest = withPrincipalServers(withCacheHints(handleListToolsRequestImpl, false, 'tools'), 'list');
-const callToolWithPrincipal = withPrincipalServers(handleCallToolRequestImpl, 'tool');
+export const handleListToolsRequest = withPrincipalServers(withModernLists(withCacheHints(handleListToolsRequestImpl, false, 'tools'), ['tools']), 'tools-list');
+const callToolWithPrincipal = withPrincipalServers(withModernLists(handleCallToolRequestImpl, ['tools']), 'tool');
 export const handleCallToolRequest = (request, extra) => observeToolCall(() => callToolWithPrincipal(request, extra));
-export const handleGetPromptRequest = withPrincipalServers(handleGetPromptRequestImpl, 'prompt');
-export const handleListPromptsRequest = withPrincipalServers(withCacheHints(handleListPromptsRequestImpl, false, 'prompts'), 'list');
-export const handleListResourcesRequest = withPrincipalServers(withCacheHints(handleListResourcesRequestImpl, false, 'resources'), 'list');
+export const handleGetPromptRequest = withPrincipalServers(withModernLists(handleGetPromptRequestImpl, ['prompts']), 'prompt');
+export const handleListPromptsRequest = withPrincipalServers(withModernLists(withCacheHints(handleListPromptsRequestImpl, false, 'prompts'), ['prompts']), 'list');
+export const handleListResourcesRequest = withPrincipalServers(withModernLists(withCacheHints(handleListResourcesRequestImpl, false, 'resources'), [
+    'resources',
+]), 'list');
 export const handleListResourceTemplatesRequest = withPrincipalServers(withCacheHints(handleListResourceTemplatesRequestImpl, false, 'resourceTemplates'), 'list');
-export const handleReadResourceRequest = withPrincipalServers(withCacheHints(handleReadResourceRequestImpl, true), 'resource');
+export const handleReadResourceRequest = withPrincipalServers(withModernLists(withCacheHints(handleReadResourceRequestImpl, true), ['resources']), 'resource');
 export const createMcpServer = (name, version, options) => {
     const normalizedOptions = typeof options === 'string' ? { group: options } : (options ?? {});
     // Determine server name based on routing type