@samanhappy/mcphub 1.0.26 → 1.0.28

package/dist/services/mcpService.js

@@ -11,6 +11,7 @@ import { StreamableHTTPClientTransport, } from '@modelcontextprotocol/sdk/client
 import { normalizeHeaders } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { createFetchWithProxy, getProxyConfigFromEnv } from './proxy.js';
 import { assertSafeUrl, createRedirectValidatingFetch } from '../utils/ssrf.js';
+import { ResilientJsonSchemaValidator } from '../utils/jsonSchemaValidator.js';
 import { getUserDao } from '../dao/index.js';
 import { expandEnvVars, replaceEnvVars, getNameSeparator } from '../config/index.js';
 import config from '../config/index.js';
@@ -28,6 +29,7 @@ import { getActivityLoggingService } from './activityLoggingService.js';
 import { maybeCompressToolResult } from './toolResultCompressionService.js';
 import { assertHostedToolAllowed, filterHostedTools, reserveHostedToolCall, settleHostedToolCall, } from './hostedAuthService.js';
 import { formatErrorForLogging, sanitizeStringForLogging, summarizeErrorForLogging, } from '../utils/serialization.js';
+import { addStdioErrorContext, observeStdioStderr } from '../utils/stdioDiagnostics.js';
 import { MCP_APPS_CAPABILITIES, filterModelVisibleTools, hasMcpAppsCapability, isAppOnlyTool, stripMcpAppsMetadata, } from '../utils/mcpApps.js';
 import { supportsCacheRefresh, injectRefreshFlag, clearRunnerCache } from '../utils/cacheUtils.js';
 const servers = {};
@@ -336,7 +338,7 @@ const getOrCreateIsolatedClient = async (sessionId, serverInfo) => {
         const transport = await createTransportFromConfig(serverInfo.name, serverConfig);
         const client = createUpstreamMcpClient(serverInfo.name, () => serverInfo);
         try {
-            await client.connect(transport, serverInfo.options || {});
+            await connectClientWithDiagnostics(client, transport, serverInfo.options || {});
         }
         catch (connectError) {
             // Connect failed — close the client/transport and kill any spawned
@@ -500,6 +502,14 @@ let serverInfos = [];
 const sessionIsolatedClients = new Map();
 // Locks to prevent concurrent creation of the same isolated client
 const isolatedClientCreationLocks = new Map();
+export const connectClientWithDiagnostics = async (client, transport, options) => {
+    try {
+        await client.connect(transport, options);
+    }
+    catch (error) {
+        throw addStdioErrorContext(error, transport);
+    }
+};
 // Track servers pending a cache-refresh reinstall.
 // Consumed once by createTransportFromConfig on the next reconnect.
 const pendingReinstalls = new Set();
@@ -534,6 +544,7 @@ const createUpstreamMcpClient = (name, getServerInfo) => {
         version: '1.0.0',
     }, {
         capabilities: MCP_APPS_CAPABILITIES,
+        jsonSchemaValidator: new ResilientJsonSchemaValidator(),
         listChanged: {
             tools: {
                 onChanged: (error, tools) => {
@@ -873,6 +884,17 @@ export const createRequestContextAwareFetch = (baseFetch, passthroughHeaderNames
     };
 };
 // Helper function to create transport based on server configuration
+/**
+ * Remove any Authorization header (case-insensitive) from a headers map.
+ *
+ * Used when an OAuth authProvider manages authentication for a transport. The
+ * MCP SDK injects the OAuth Bearer token first and then spreads the configured
+ * requestInit headers on top, so a leftover static Authorization value would
+ * override the valid OAuth access token and produce 401 authentication loops.
+ */
+const stripAuthorizationHeader = (headers) => {
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== 'authorization'));
+};
 export const createTransportFromConfig = async (name, conf) => {
     let transport;
     const env = {
@@ -893,29 +915,44 @@ export const createTransportFromConfig = async (name, conf) => {
     }
     if (conf.type === 'streamable-http') {
         const options = {};
-        const headers = conf.headers ? replaceEnvVars(conf.headers, env) : {};
+        let headers = conf.headers ? replaceEnvVars(conf.headers, env) : {};
         const baseFetch = createFetchWithProxy(getProxyConfigFromEnv(env));
         const requestAwareFetch = createRedirectValidatingFetch(createRequestContextAwareFetch(baseFetch, conf.passthroughHeaders), allowInternal);
-        if (Object.keys(headers).length > 0) {
-            options.requestInit = {
-                headers,
-            };
-        }
         // Create OAuth provider if configured - SDK will handle authentication automatically
         const authProvider = await createOAuthProvider(name, conf);
         if (authProvider) {
             options.authProvider = authProvider;
+            // When the OAuth provider is active, strip any static Authorization
+            // header before passing the configured headers to the SDK. The SDK's
+            // transport builds common headers by adding the OAuth Bearer token first
+            // and then spreading requestInit headers on top, so a stale static
+            // Authorization value would override the valid access token and cause
+            // 401 re-authorization loops.
+            headers = stripAuthorizationHeader(headers);
             console.log(`OAuth provider configured for server: ${name}`);
         }
+        if (Object.keys(headers).length > 0) {
+            options.requestInit = {
+                headers,
+            };
+        }
         options.fetch = requestAwareFetch;
         transport = new StreamableHTTPClientTransport(new URL(conf.url || ''), options);
     }
     else if (conf.url) {
         // SSE transport
         const options = {};
-        const headers = conf.headers ? replaceEnvVars(conf.headers, env) : {};
+        let headers = conf.headers ? replaceEnvVars(conf.headers, env) : {};
         const baseFetch = createFetchWithProxy(getProxyConfigFromEnv(env));
         const requestAwareFetch = createRedirectValidatingFetch(createRequestContextAwareFetch(baseFetch, conf.passthroughHeaders), allowInternal);
+        // Create OAuth provider if configured - SDK will handle authentication automatically
+        const authProvider = await createOAuthProvider(name, conf);
+        if (authProvider) {
+            options.authProvider = authProvider;
+            // Drop static Authorization header when OAuth manages auth (see above).
+            headers = stripAuthorizationHeader(headers);
+            console.log(`OAuth provider configured for server: ${name}`);
+        }
         if (Object.keys(headers).length > 0) {
             options.eventSourceInit = {
                 headers,
@@ -930,12 +967,6 @@ export const createTransportFromConfig = async (name, conf) => {
                 fetch: requestAwareFetch,
             };
         }
-        // Create OAuth provider if configured - SDK will handle authentication automatically
-        const authProvider = await createOAuthProvider(name, conf);
-        if (authProvider) {
-            options.authProvider = authProvider;
-            console.log(`OAuth provider configured for server: ${name}`);
-        }
         options.fetch = requestAwareFetch;
         transport = new SSEClientTransport(new URL(conf.url), options);
     }
@@ -975,9 +1006,14 @@ export const createTransportFromConfig = async (name, conf) => {
             env: env,
             stderr: 'pipe',
         });
-        transport.stderr?.on('data', (data) => {
-            console.log(`[${name}] [child] ${data}`);
-        });
+        if (transport.stderr) {
+            observeStdioStderr(transport, transport.stderr, (message) => {
+                console.log('Upstream server stderr', {
+                    serverName: name,
+                    message,
+                });
+            });
+        }
     }
     else {
         throw new Error(`Unable to create transport for server: ${name}`);
@@ -1016,7 +1052,7 @@ const callToolWithReconnect = async (serverInfo, toolParams, options, maxRetries
                     const newTransport = await createTransportFromConfig(serverInfo.name, server);
                     const newClient = createUpstreamMcpClient(serverInfo.name, () => serverInfo);
                     // Reconnect with new transport
-                    await newClient.connect(newTransport, serverInfo.options || {});
+                    await connectClientWithDiagnostics(newClient, newTransport, serverInfo.options || {});
                     if (isolated) {
                         // Isolated path: close only this session's stale connection and
                         // replace its entry in the per-session map. Never touch the shared
@@ -1135,6 +1171,32 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                 });
                 continue;
             }
+            // On-demand stdio servers: skip startup connect; spawn lazily on first
+            // tool call. startOnDemand is a stdio-only optimisation - HTTP/SSE and
+            // OpenAPI servers have no deferred child process, so they connect normally.
+            // Preserve existing runtime state (tools/prompts populated from a previous
+            // 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);
+                nextServerInfos.push({
+                    // Carry over cached tools/prompts/resources if the server was previously connected
+                    ...(existingOnDemand ?? {
+                        name,
+                        status: 'disconnected',
+                        error: null,
+                        tools: [],
+                        prompts: [],
+                        resources: [],
+                        createTime: Date.now(),
+                    }),
+                    owner: expandedConf.owner,
+                    visibility: expandedConf.visibility,
+                    enabled: true,
+                    config: expandedConf,
+                });
+                console.log(`Skipping startup connect for on-demand server: ${name}`);
+                continue;
+            }
             // Reuse this server's existing runtime state instead of reconnecting when:
             // - a targeted reload/reconnect (serverName) was requested for a
             //   *different* server — preserve its current state regardless of
@@ -1302,12 +1364,10 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
                 serverInfo.oauth = {
                     authorizationUrl: pendingAuth.authorizationUrl,
                     state: pendingAuth.state,
-                    codeVerifier: pendingAuth.codeVerifier,
                 };
             }
             nextServerInfos.push(serverInfo);
-            client
-                .connect(transport, initRequestOptions || requestOptions)
+            connectClientWithDiagnostics(client, transport, initRequestOptions || requestOptions)
                 .then(() => {
                 console.log(`Successfully connected client for server: ${name}`);
                 const serverVersion = client.getServerVersion?.();
@@ -1416,6 +1476,19 @@ export const initializeClientsFromSettings = async (isInit, serverName, options)
         throw error;
     }
     serverInfos = nextServerInfos;
+    // Populate the tool cache for on-demand stdio servers so their tools are
+    // visible to agents, then put them back to sleep. Running here (rather than
+    // only at startup) also covers servers added/enabled/reloaded after startup.
+    const primePromise = primeOnDemandServers();
+    // At full startup (no serverName) keep prime fire-and-forget so a slow or
+    // broken on-demand server does not block init. For a targeted reload/edit
+    // (serverName set), await it so the caller - and the dashboard refresh that
+    // follows the HTTP response - sees the cached tools immediately instead of an
+    // empty list that only fills in after the fire-and-forget prime completes and
+    // the next poll picks it up. See #1032.
+    if (serverName) {
+        await primePromise;
+    }
     return serverInfos;
 };
 // Register all MCP tools
@@ -1492,6 +1565,14 @@ export const getServersInfo = async (page, limit, user) => {
                 enabled: promptConfig?.enabled !== false, // Default to true if not explicitly disabled
             };
         });
+        const resourcesWithEnabled = resources.map((resource) => {
+            const resourceConfig = serverConfig?.resources?.[resource.uri];
+            return {
+                ...resource,
+                description: resolveDescriptionOverride(resource.description, resourceConfig),
+                enabled: resourceConfig?.enabled !== false,
+            };
+        });
         return {
             name,
             version,
@@ -1502,7 +1583,7 @@ export const getServersInfo = async (page, limit, user) => {
             error,
             tools: toolsWithEnabled,
             prompts: promptsWithEnabled,
-            resources,
+            resources: resourcesWithEnabled,
             createTime,
             enabled,
             oauth: oauth || oauthConnected
@@ -1511,6 +1592,7 @@ export const getServersInfo = async (page, limit, user) => {
                         ? {
                             authorizationUrl: oauth.authorizationUrl,
                             state: oauth.state,
+                            ...(oauth.clientIdConfigured ? { clientIdConfigured: true } : {}),
                             // Don't expose codeVerifier to frontend for security
                         }
                         : {}),
@@ -1631,7 +1713,7 @@ const filterToolsByConfig = async (serverName, tools) => {
 };
 // Get server by tool name
 const getServerByTool = (toolName) => {
-    return serverInfos.find((serverInfo) => serverInfo.tools.some((tool) => tool.name === toolName));
+    return serverInfos.find((serverInfo) => serverInfo.enabled !== false && serverInfo.tools.some((tool) => tool.name === toolName));
 };
 // Add new server
 export const addServer = async (name, config) => {
@@ -1752,6 +1834,198 @@ function closeServer(name) {
         closeServerRuntime(serverInfo);
     }
 }
+// ---------------------------------------------------------------------------
+// On-demand spawning helpers
+// ---------------------------------------------------------------------------
+/**
+ * Shuts down an on-demand stdio server without removing it from serverInfos.
+ * The tool/prompt/resource lists are preserved so agents can still see what
+ * the server offers and trigger a cold-start on the next tool call.
+ */
+const shutdownOnDemandServer = (serverInfo) => {
+    if (serverInfo.idleTimeoutId) {
+        clearTimeout(serverInfo.idleTimeoutId);
+        serverInfo.idleTimeoutId = undefined;
+    }
+    // Close runtime (kills process) but intentionally keep tools/prompts/resources
+    closeServerRuntime(serverInfo);
+    serverInfo.status = 'disconnected';
+    console.log(`[${serverInfo.name}] On-demand server shut down after idle; ` +
+        `${serverInfo.tools.length} tools cached for next wake-up`);
+};
+/**
+ * Resets (or starts) the idle-shutdown timer for an on-demand server.
+ * Call this after every successful tool invocation.
+ */
+const scheduleIdleShutdown = (serverInfo) => {
+    if (!serverInfo.config?.startOnDemand)
+        return;
+    if (serverInfo.idleTimeoutId) {
+        clearTimeout(serverInfo.idleTimeoutId);
+    }
+    const idleMs = serverInfo.config.idleTimeoutMs ?? 300000; // default 5 minutes
+    serverInfo.idleTimeoutId = setTimeout(() => {
+        if (serverInfo.status === 'connected') {
+            shutdownOnDemandServer(serverInfo);
+        }
+    }, idleMs);
+};
+/**
+ * Ensures an on-demand server is connected before a tool call proceeds.
+ *
+ * Performs a direct, awaited wake-up that mutates the existing `serverInfo`
+ * in place (preserving the reference callers hold), rather than going through
+ * `reconnectServer` -> `initializeClientsFromSettings`. The latter skips the
+ * connect for on-demand servers, resolves before the fire-and-forget handshake
+ * completes, and rebuilds `serverInfos` (leaving callers with a stale object) -
+ * so it could never actually wake a sleeping server. See #1029.
+ *
+ * Concurrent callers coalesce on `spawningPromise` so only one spawn runs.
+ */
+const ensureServerReady = async (serverInfo) => {
+    if (serverInfo.status === 'connected')
+        return;
+    // Another call is already spawning - wait for it
+    if (serverInfo.spawningPromise) {
+        await serverInfo.spawningPromise;
+        return;
+    }
+    const spawnStart = Date.now();
+    const spawnPromise = (async () => {
+        // Load the config fresh from the DAO for the expanded transport config and
+        // to read the server name. See #1029.
+        const rawConfig = await getServerDao().findById(serverInfo.name);
+        if (!rawConfig) {
+            throw new Error('Server configuration not found for on-demand wake');
+        }
+        if (rawConfig.enabled === false) {
+            throw new Error(`Cannot start disabled on-demand server: ${rawConfig.name}`);
+        }
+        const expandedConf = replaceEnvVars(rawConfig);
+        // startOnDemand is a stdio-only optimisation; OpenAPI/HTTP servers have no
+        // deferred process to spawn, so there is nothing to wake.
+        if (expandedConf.type === 'openapi') {
+            return;
+        }
+        const name = rawConfig.name;
+        console.log(`[${name}] Cold-starting on-demand server…`);
+        const transport = await createTransportFromConfig(name, expandedConf);
+        const client = createUpstreamMcpClient(name, () => serverInfo);
+        const serverRequestOptions = expandedConf.options || {};
+        const defaultRequestTimeout = Number(process.env.DEFAULT_REQUEST_TIMEOUT) || 60000;
+        const requestOptions = {
+            timeout: serverRequestOptions.timeout || defaultRequestTimeout,
+            resetTimeoutOnProgress: serverRequestOptions.resetTimeoutOnProgress ?? true,
+            maxTotalTimeout: serverRequestOptions.maxTotalTimeout,
+        };
+        await connectClientWithDiagnostics(client, transport, requestOptions);
+        // Mutate in place so every holder of this serverInfo (resolution paths,
+        // the caller about to invoke the tool) sees the live client/status.
+        serverInfo.client = client;
+        serverInfo.transport = transport;
+        serverInfo.options = requestOptions;
+        serverInfo.version = client.getServerVersion?.()?.version;
+        serverInfo.instructions = client.getInstructions?.();
+        serverInfo.config = expandedConf;
+        serverInfo.status = 'connected';
+        serverInfo.error = null;
+        let toolCount = 0;
+        let promptCount = 0;
+        let resourceCount = 0;
+        const capabilities = client.getServerCapabilities?.();
+        if (capabilities?.tools) {
+            try {
+                const tools = await client.listTools({}, requestOptions);
+                toolCount = tools.tools.length;
+                updateServerToolsCache(serverInfo, tools.tools);
+                broadcastToolListChanged();
+            }
+            catch (error) {
+                console.warn(`[${name}] Failed to list tools during wake`, {
+                    error: summarizeErrorForLogging(error),
+                });
+            }
+        }
+        if (capabilities?.prompts) {
+            try {
+                const prompts = await client.listPrompts({}, requestOptions);
+                promptCount = prompts.prompts.length;
+                updateServerPromptsCache(serverInfo, prompts.prompts);
+            }
+            catch (error) {
+                console.warn(`[${name}] Failed to list prompts during wake`, {
+                    error: summarizeErrorForLogging(error),
+                });
+            }
+        }
+        if (capabilities?.resources) {
+            try {
+                const resources = await client.listResources({}, requestOptions);
+                resourceCount = resources.resources.length;
+                updateServerResourcesCache(serverInfo, resources.resources);
+            }
+            catch (error) {
+                console.warn(`[${name}] Failed to list resources during wake`, {
+                    error: summarizeErrorForLogging(error),
+                });
+            }
+        }
+        // No-op for stdio transports; only SSE/streamable-http opt in via enableKeepAlive.
+        setupServerKeepAlive(serverInfo, expandedConf);
+        console.log(`[${name}] On-demand server ready in ${Date.now() - spawnStart}ms` +
+            ` (${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources)`);
+    })();
+    serverInfo.spawningPromise = spawnPromise;
+    try {
+        await spawnPromise;
+    }
+    catch (error) {
+        serverInfo.status = 'disconnected';
+        serverInfo.error = `Failed to start on-demand server: ${formatErrorForLogging(error)}`;
+        throw error;
+    }
+    finally {
+        serverInfo.spawningPromise = undefined;
+    }
+};
+// stdio servers are the only ones that benefit from deferred spawning; HTTP/SSE
+// and OpenAPI servers have no long-lived child process to skip.
+const isStdioServer = (conf) => !!conf && (conf.type === 'stdio' || (!conf.type && !!conf.command));
+/**
+ * Connects each on-demand stdio server once to populate its tool cache, then
+ * shuts the child back down (keeping the cache). Run after startup init so the
+ * tools are advertised immediately and a later `tools/call` can wake the server.
+ *
+ * Returns a promise so a targeted reload/edit can await it (via
+ * initializeClientsFromSettings) and surface the populated tool cache before
+ * the HTTP response - otherwise the dashboard refresh that follows the edit
+ * sees an empty list until the next poll. At full startup the caller still
+ * ignores the promise (fire-and-forget) so a slow or broken on-demand server
+ * does not block init. Each server is isolated so one failure does not affect
+ * the others. See #1029 / #1032.
+ */
+const primeOnDemandServers = () => {
+    const targets = serverInfos.filter((si) => si.config?.startOnDemand === true &&
+        isStdioServer(si.config) &&
+        si.tools.length === 0 &&
+        si.enabled !== false);
+    if (targets.length === 0)
+        return Promise.resolve();
+    console.log(`Priming ${targets.length} on-demand server(s) for tool discovery…`);
+    return Promise.allSettled(targets.map(async (si) => {
+        try {
+            await ensureServerReady(si);
+            // Sleep the child but keep the cached tool list visible to agents.
+            shutdownOnDemandServer(si);
+            console.log('On-demand server primed and asleep');
+        }
+        catch (error) {
+            console.warn('Failed to prime on-demand server', {
+                error: summarizeErrorForLogging(error),
+            });
+        }
+    })).then(() => undefined);
+};
 export const resetServerOAuthConnection = (name) => {
     const serverInfo = serverInfos.find((serverInfo) => serverInfo.name === name);
     if (!serverInfo) {
@@ -1881,14 +2155,19 @@ const getMcpAppsRouteContext = async (sessionId, group) => {
         return { enabled: false };
     }
     const { filteredServerInfos } = await getFilteredServerInfosForGroup(group);
-    if (filteredServerInfos.length !== 1 ||
-        filteredServerInfos[0].status !== 'connected' ||
-        !filteredServerInfos[0].client) {
+    const connectedServerInfos = filteredServerInfos.filter((serverInfo) => serverInfo.status === 'connected' && !!serverInfo.client);
+    if (connectedServerInfos.length === 0) {
         return { enabled: false };
     }
+    if (connectedServerInfos.length === 1) {
+        return {
+            enabled: true,
+            serverInfo: connectedServerInfos[0],
+        };
+    }
     return {
         enabled: true,
-        serverInfo: filteredServerInfos[0],
+        serverInfos: connectedServerInfos,
     };
 };
 const normalizeToolNameForServer = (serverName, toolName) => {
@@ -1939,7 +2218,11 @@ const resolveToolInGroup = async (group, toolName, allowRawName) => {
     }
     const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(lookupGroup);
     for (const serverInfo of filteredServerInfos) {
-        if (serverInfo.status !== 'connected' || serverInfo.enabled === false) {
+        // A disconnected on-demand server may still have a cached tool list from a
+        // previous wake-up; allow it through so it can be selected and woken by the
+        // caller. Other disconnected servers cannot serve the request. See #1029.
+        if ((serverInfo.status !== 'connected' && !serverInfo.config?.startOnDemand) ||
+            serverInfo.enabled === false) {
             continue;
         }
         const serverConfig = serverConfigsByName.get(serverInfo.name);
@@ -1985,11 +2268,19 @@ const projectToolForDownstream = (serverName, tool, appsRouteContext, serverConf
         return undefined;
     }
     const projectedTool = appsRouteContext.enabled ? tool : stripMcpAppsMetadata(tool);
+    // Single connected server: keep the existing raw (unqualified) name so
+    // widgets that call back with the bare tool name continue to work.
+    if (appsRouteContext.serverInfo) {
+        return {
+            ...projectedTool,
+            name: normalizeToolNameForServer(serverName, projectedTool.name),
+        };
+    }
+    // Multiple connected servers (Apps-enabled) or Apps disabled: qualify the
+    // name so it can still be routed to the right server unambiguously.
     return {
         ...projectedTool,
-        name: appsRouteContext.enabled
-            ? normalizeToolNameForServer(serverName, projectedTool.name)
-            : projectNameForGroup(projectedTool.name, serverName, serverConfig),
+        name: projectNameForGroup(projectedTool.name, serverName, serverConfig),
     };
 };
 export const handleListToolsRequest = async (_, extra) => {
@@ -2003,6 +2294,14 @@ export const handleListToolsRequest = async (_, extra) => {
     }
     const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(group);
     const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
+    // If the startup prime of an on-demand server is still in flight, wait for it
+    // 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)
+        .map((si) => si.spawningPromise));
     const allTools = [];
     for (const serverInfo of filteredServerInfos) {
         if (serverInfo.tools && serverInfo.tools.length > 0) {
@@ -2084,17 +2383,22 @@ export const handleCallToolRequest = async (request, extra) => {
                 throw new Error('toolName parameter is required');
             }
             const { arguments: toolArgs } = request.params.arguments || {};
+            // A single connected server on an Apps-enabled route is addressed by
+            // its raw (unqualified) tool name, same as before. A multi-server
+            // Apps-enabled route falls through to qualified-name group
+            // resolution below, same as an ordinary (non-Apps) group route.
+            const singleServerAppsRoute = !!appsRouteContext.serverInfo;
             let targetServerInfo;
             let targetToolName = toolName;
             let targetTool;
-            if (appsRouteContext.enabled) {
+            if (singleServerAppsRoute) {
                 targetServerInfo = appsRouteContext.serverInfo;
             }
             else if (extra && extra.server) {
                 targetServerInfo = getServerByName(extra.server);
             }
             else if (getGroupLookupName(group)) {
-                const groupTool = await resolveToolInGroup(group, toolName, appsRouteContext.enabled);
+                const groupTool = await resolveToolInGroup(group, toolName, false);
                 if (groupTool) {
                     targetServerInfo = groupTool.serverInfo;
                     targetToolName = groupTool.toolName;
@@ -2102,16 +2406,30 @@ export const handleCallToolRequest = async (request, extra) => {
                 }
             }
             else {
-                // Find the first server that has this tool
-                targetServerInfo = serverInfos.find((serverInfo) => serverInfo.status === 'connected' &&
-                    serverInfo.enabled !== false &&
+                // Find the first server that has this tool.
+                // On-demand servers may be sleeping (disconnected) but still advertise
+                // their cached tool list — include them as candidates.
+                targetServerInfo = serverInfos.find((serverInfo) => serverInfo.enabled !== false &&
+                    (serverInfo.status === 'connected' || serverInfo.config?.startOnDemand === true) &&
                     serverInfo.tools.some((tool) => tool.name === toolName));
             }
             if (!targetServerInfo) {
                 throw new Error(`No available servers found with tool: ${toolName}`);
             }
+            // If the target is an on-demand server that is not yet running, wake it up now.
+            // Concurrent callers are serialised via ensureServerReady's singleton promise.
+            if (targetServerInfo.config?.startOnDemand && targetServerInfo.status !== 'connected') {
+                await ensureServerReady(targetServerInfo);
+                // Re-read status from the mutated serverInfo after async spawn
+                const freshStatus = targetServerInfo.status;
+                if (freshStatus !== 'connected') {
+                    throw new Error(`Failed to start on-demand server '${targetServerInfo.name}' — check server logs`);
+                }
+            }
+            // Record activity timestamp for on-demand servers
+            targetServerInfo.lastUsedAt = Date.now();
             // Check if the tool exists on the server
-            const tool = targetTool ?? findToolOnServer(targetServerInfo, targetToolName, appsRouteContext.enabled);
+            const tool = targetTool ?? findToolOnServer(targetServerInfo, targetToolName, singleServerAppsRoute);
             if (!tool) {
                 throw new Error(`Tool '${toolName}' not found on server '${targetServerInfo.name}'`);
             }
@@ -2227,6 +2545,8 @@ export const handleCallToolRequest = async (request, extra) => {
                 toolName: cleanToolName,
                 result: summarizeToolResultForLogging(result),
             });
+            // Reset idle-shutdown timer for on-demand servers after each successful call
+            scheduleIdleShutdown(targetServerInfo);
             // Log successful activity
             const duration = Date.now() - startTime;
             await activityLogger.logToolCall({
@@ -2251,22 +2571,36 @@ export const handleCallToolRequest = async (request, extra) => {
         }
         // Regular tool handling
         const lookupGroup = getGroupLookupName(group);
-        const groupTool = !appsRouteContext.enabled && lookupGroup
-            ? await resolveToolInGroup(lookupGroup, request.params.name, appsRouteContext.enabled)
+        // A single connected server on an Apps-enabled route is addressed
+        // directly, using its raw (unqualified) tool name, same as before. A
+        // multi-server Apps-enabled route resolves via the qualified-name
+        // group lookup below, same as an ordinary (non-Apps) group route,
+        // just without stripping Apps metadata or hiding app-only tools
+        // (assertToolAvailableForRoute below still gates on appsRouteContext.enabled).
+        const singleServerAppsRoute = !!appsRouteContext.serverInfo;
+        const groupTool = !singleServerAppsRoute && lookupGroup
+            ? await resolveToolInGroup(lookupGroup, request.params.name, false)
             : undefined;
-        const serverInfo = appsRouteContext.enabled
+        const serverInfo = singleServerAppsRoute
             ? appsRouteContext.serverInfo
             : (groupTool?.serverInfo ??
                 (lookupGroup ? undefined : getServerByTool(request.params.name)));
         const routeToolName = groupTool?.toolName ?? request.params.name;
         const tool = groupTool?.tool ??
             (serverInfo
-                ? findToolOnServer(serverInfo, routeToolName, appsRouteContext.enabled)
+                ? findToolOnServer(serverInfo, routeToolName, singleServerAppsRoute)
                 : undefined);
         if (!serverInfo || !tool) {
             throw new Error(`Server not found: ${request.params.name}`);
         }
         assertToolAvailableForRoute(tool, appsRouteContext);
+        // Wake the on-demand server before invoking the tool. It may be asleep with
+        // a cached tool list (visible above) but no live client. Mirrors the
+        // $smart call_tool path. See #1029.
+        if (serverInfo.config?.startOnDemand && serverInfo.status !== 'connected') {
+            await ensureServerReady(serverInfo);
+        }
+        serverInfo.lastUsedAt = Date.now();
         // Handle OpenAPI servers differently
         if (serverInfo.openApiClient) {
             // For OpenAPI servers, use the OpenAPI client
@@ -2366,6 +2700,8 @@ export const handleCallToolRequest = async (request, extra) => {
             toolName: cleanToolName,
             result: summarizeToolResultForLogging(result),
         });
+        // Reset idle-shutdown timer for on-demand servers after each successful call
+        scheduleIdleShutdown(serverInfo);
         // Log successful activity
         const duration = Date.now() - startTime;
         await activityLogger.logToolCall({
@@ -2657,15 +2993,44 @@ export const handleReadResourceRequest = async (request, extra) => {
                 break;
             }
         }
-        if (!server && appsRouteContext.enabled && uri.startsWith('ui://')) {
-            server = appsRouteContext.serverInfo;
+        let result;
+        if (server?.client) {
+            result = await server.client.readResource({ uri });
+            if (!result || !Array.isArray(result.contents)) {
+                throw new Error(`Failed to read resource: ${uri}`);
+            }
         }
-        if (!server?.client) {
-            throw new Error(`Resource not found: ${uri}`);
+        else if (appsRouteContext.enabled && uri.startsWith('ui://')) {
+            // Not pre-registered in resources/list — common for MCP Apps servers
+            // that generate ui:// resources dynamically at tool-call time. A
+            // single-server route goes straight to that server. A multi-server
+            // route has no way to know which upstream owns the URI up front, so
+            // probe each connected candidate in turn and use the first one that
+            // answers.
+            const candidates = appsRouteContext.serverInfo
+                ? [appsRouteContext.serverInfo]
+                : (appsRouteContext.serverInfos ?? []);
+            for (const candidate of candidates) {
+                if (!candidate.client) {
+                    continue;
+                }
+                try {
+                    const candidateResult = await candidate.client.readResource({ uri });
+                    if (candidateResult && Array.isArray(candidateResult.contents)) {
+                        result = candidateResult;
+                        break;
+                    }
+                }
+                catch {
+                    // This candidate doesn't own the resource; try the next one.
+                }
+            }
+            if (!result) {
+                throw new Error(`Resource not found: ${uri}`);
+            }
         }
-        const result = await server.client.readResource({ uri });
-        if (!result || !Array.isArray(result.contents)) {
-            throw new Error(`Failed to read resource: ${uri}`);
+        else {
+            throw new Error(`Resource not found: ${uri}`);
         }
         return appsRouteContext.enabled
             ? result