@apify/actors-mcp-server 0.9.20 → 0.9.21-beta.0

package/dist/mcp/server.d.ts

@@ -5,7 +5,8 @@ import type { TaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/int
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { ApifyClient } from '../apify_client.js';
-import type { ActorsMcpServerOptions, ActorStore, ServerMode, ToolEntry } from '../types.js';
+import type { ActorsMcpServerOptions, ActorStore, Input, ToolEntry } from '../types.js';
+import { ServerMode } from '../types.js';
 /**
  * Create Apify MCP server
  */
@@ -18,17 +19,33 @@ export declare class ActorsMcpServer {
     readonly options: ActorsMcpServerOptions;
     readonly taskStore: TaskStore;
     readonly actorStore?: ActorStore;
-    /** Resolved server mode — normalized once at construction from options.uiMode. */
-    readonly serverMode: ServerMode;
-    /** Mode-specific executor for direct actor tools (`type: 'actor'`). */
-    private readonly actorExecutor;
+    /**
+     * Resolved server mode. Preliminary value at construction (`'auto'` → `DEFAULT`).
+     * Finalized inside the `initialize` request handler (see constructor) once the
+     * client's capabilities are known. Effectively set-once per connection.
+     */
+    serverMode: ServerMode;
+    /** Mode-specific executor for direct actor tools (`type: 'actor'`). Finalized with `serverMode`. */
+    private actorExecutor;
+    /**
+     * Raw option captured from `options.serverMode` (or the legacy `uiMode`). Re-resolved
+     * inside the initialize handler when set to `'auto'`; explicit `'default'`/`'apps'`
+     * values bypass auto-detect.
+     */
+    private readonly serverModeOption;
+    /** True once mode is final. False for `'auto'` until the initialize handler resolves client capabilities. */
+    private serverModeResolved;
+    /**
+     * Tool requests queued before mode is final. Actor tools are upserted immediately
+     * (mode-agnostic); we also capture the exact actor-tool slice fetched for each
+     * request so the flush composes every entry against *its own* actor list rather
+     * than the accumulated union across unrelated requests.
+     */
+    private pendingToolsAfterModeResolved;
     private telemetryEnabled;
     private telemetryEnv;
     private availableWidgets;
-    /**
-     * Whether the connected client advertises MCP Apps UI support (`io.modelcontextprotocol/ui` extension).
-     * NOTE: This is currently informational only (logged for observability) and does not yet gate widget behavior.
-     */
+    /** Set in the initialize handler once client capabilities are known. */
     clientSupportsUi: boolean;
     constructor(options?: ActorsMcpServerOptions);
     /**
@@ -36,10 +53,16 @@ export declare class ActorsMcpServer {
      */
     private setupTelemetry;
     /**
-     * Detects MCP Apps UI support from client capabilities after initialization.
-     * Checks for the `io.modelcontextprotocol/ui` extension with `text/html;profile=mcp-app` MIME type.
+     * Override the SDK's `initialize` request handler to run mode resolution and
+     * pending-source flush before `InitializeResult` is sent. Delegates boilerplate
+     * (protocolVersion, capabilities, instructions) to the SDK's captured `_oninitialize`.
+     *
+     * Not using `server.oninitialized`: the SDK dispatches notification handlers
+     * fire-and-forget (separate microtask), so a follow-up `tools/list` can race past them.
+     * The request handler guarantees tools are final before the response and the first `tools/list`.
      */
-    private setupCapabilityNegotiation;
+    private setupInitializeHandler;
+    private updateToolsAfterServerModeResolved;
     /**
      * Returns an array of tool names.
      * @returns {string[]} - An array of tool names.
@@ -94,14 +117,18 @@ export declare class ActorsMcpServer {
      * @returns Promise<ToolEntry[]> - Array of loaded tool entries
      */
     loadActorsAsTools(actorIdsOrNames: string[], apifyClient: ApifyClient): Promise<ToolEntry[]>;
+    /** Load tools from URL params. Used by SSE and HTTP entry points. */
+    loadToolsFromUrl(url: string, apifyClient: ApifyClient): Promise<void>;
     /**
-     * Loads tools from URL params.
-     *
-     * This method also handles enabling of Actor autoloading via the processParamsGetTools.
+     * Two-phase: getActors (async, mode-agnostic Apify fetch) then getToolsForServerMode
+     * (sync, mode-dependent compose). When mode is unresolved, queue actorTools and let
+     * the initialize handler compose them later.
      *
-     * Used primarily for SSE.
+     * Don't move the getActors await into the initialize handler — clients time out
+     * waiting for InitializeResult. The queue buffers already-fetched data, not network
+     * work. See #721.
      */
-    loadToolsFromUrl(url: string, apifyClient: ApifyClient): Promise<void>;
+    loadToolsFromInput(input: Input, apifyClient: ApifyClient): Promise<void>;
     /** Delete tools from the server and notify the handler.
      */
     removeToolsByName(toolNames: string[], shouldNotifyToolsChangedHandler?: boolean): string[];

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4DAA4D,CAAC;AAE5F,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AA0B/E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsBjD,OAAO,KAAK,EAER,sBAAsB,EACtB,UAAU,EAGV,UAAU,EAGV,SAAS,EAEZ,MAAM,aAAa,CAAC;AAsBrB;;GAEG;AACH,qBAAa,eAAe;IACxB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9C,OAAO,CAAC,mBAAmB,CAAkC;IAC7D,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,eAAe,CAAU;IACjC,SAAgB,OAAO,EAAE,sBAAsB,CAAC;IAChD,SAAgB,SAAS,EAAE,SAAS,CAAC;IACrC,SAAgB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxC,kFAAkF;IAClF,SAAgB,UAAU,EAAE,UAAU,CAAC;IACvC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAG9C,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,YAAY,CAAuC;IAG3D,OAAO,CAAC,gBAAgB,CAA2C;IAEnE;;;OAGG;IACI,gBAAgB,UAAS;gBAEpB,OAAO,GAAE,sBAA2B;IA+DhD;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAalC;;;OAGG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;;;MAOE;IACK,2BAA2B,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI;IAOzE;;;MAGE;IACK,6BAA6B;IAOpC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAM7B;;;OAGG;IACI,kBAAkB,IAAI,MAAM,EAAE;IAMrC;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;OAGG;IACI,gBAAgB,IAAI,MAAM,EAAE;IAInC;;;;;MAKE;IACW,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW;IA6B1E;;;;;;OAMG;IACU,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQzG;;;;;;OAMG;IACU,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW;IAQnE;OACG;IACI,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,+BAA+B,UAAQ,GAAG,MAAM,EAAE;IAahG;;;;;OAKG;IACI,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,+BAA+B,UAAQ;IAS9E,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,kBAAkB;IAyB1B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyC3B;;QAEI;IACJ,OAAO,CAAC,iBAAiB;IAyFzB,OAAO,CAAC,iBAAiB;IAubzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAiC/B;;;;;;;;;;;OAWG;YAEW,wBAAwB;YA8PxB,oBAAoB;IAiClC;;OAEG;YACW,cAAc;IA4CtB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAoB/B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.js

@@ -1,12 +1,14 @@
 /**
  * Model Context Protocol (MCP) server for Apify Actors
  */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="374f6a13-0750-5a19-ac52-42edce3f2308")}catch(e){}}();
 import { randomUUID } from 'node:crypto';
+// The ext-apps package exposes `./server` via conditional exports only (no `./server/index.js`
+// wildcard), so we can't satisfy the `import/extensions` rule on this subpath.
+// eslint-disable-next-line import/extensions
+import { getUiCapability, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, CallToolResultSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, ServerNotificationSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, CallToolResultSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, ServerNotificationSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import dedent from 'dedent';
 import log from '@apify/log';
 import { parseBooleanOrNull } from '@apify/utilities';
@@ -15,12 +17,13 @@ import { ALLOWED_TASK_TOOL_EXECUTION_MODES, APIFY_MCP_URL, DEFAULT_TELEMETRY_ENA
 import { prepareToolCallContext } from '../payments/helpers.js';
 import { prompts } from '../prompts/index.js';
 import { createResourceService } from '../resources/resource_service.js';
-import { resolveAvailableWidgets, RESOURCE_MIME_TYPE } from '../resources/widgets.js';
+import { resolveAvailableWidgets } from '../resources/widgets.js';
 import { getTelemetryEnv, trackToolCall } from '../telemetry.js';
+import { appsActorExecutor } from '../tools/apps/actor_executor.js';
 import { defaultActorExecutor } from '../tools/default/actor_executor.js';
-import { getActorsAsTools, getCategoryTools, getDefaultTools } from '../tools/index.js';
-import { openaiActorExecutor } from '../tools/openai/actor_executor.js';
+import { getActorsAsTools } from '../tools/index.js';
 import { decodeDotPropertyNames, legacyToolNameToNew } from '../tools/utils.js';
+import { parseServerMode, resolveServerMode, ServerMode } from '../types.js';
 import { getHttpStatusCode, logHttpError } from '../utils/logging.js';
 import { buildMCPResponse, getToolCallErrorUserText } from '../utils/mcp.js';
 import { buildPaymentRequiredResponse } from '../utils/payment_errors.js';
@@ -28,22 +31,35 @@ import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
 import { classifyFailureCategory, extractAjvErrorDetails, extractToolTelemetry, getToolStatusFromError } from '../utils/tool_status.js';
 import { buildActorFields, extractActorId, extractActorName, getToolFullName, getToolPublicFieldOnly } from '../utils/tools.js';
+import { getActors, getToolsForServerMode, toolNamesToInput, } from '../utils/tools_loader.js';
 import { getUserInfoCached } from '../utils/userid_cache.js';
 import { getPackageVersion } from '../utils/version.js';
 import { connectMCPClient } from './client.js';
 import { EXTERNAL_TOOL_CALL_TIMEOUT_MSEC, LOG_LEVEL_MAP } from './const.js';
-import { isTaskCancelled, processParamsGetTools } from './utils.js';
+import { isTaskCancelled, parseInputParamsFromUrl } from './utils.js';
 /** Mode → actor executor. Add new modes here. */
 const actorExecutorsByMode = {
-    default: defaultActorExecutor,
-    openai: openaiActorExecutor,
+    [ServerMode.DEFAULT]: defaultActorExecutor,
+    [ServerMode.APPS]: appsActorExecutor,
 };
+/**
+ * Returns true when the initialize request advertises the MCP Apps UI extension
+ * with the widget MIME type. Used to resolve `'auto'` server mode.
+ *
+ * Uses {@link getUiCapability} from `@modelcontextprotocol/ext-apps/server` to
+ * read the `io.modelcontextprotocol/ui` extension from client capabilities — the
+ * canonical way per the MCP Apps spec.
+ */
+function isUiSupportedByClient(request) {
+    var _a, _b, _c;
+    const uiCap = getUiCapability((_a = request === null || request === void 0 ? void 0 : request.params) === null || _a === void 0 ? void 0 : _a.capabilities);
+    return (_c = (_b = uiCap === null || uiCap === void 0 ? void 0 : uiCap.mimeTypes) === null || _b === void 0 ? void 0 : _b.includes(RESOURCE_MIME_TYPE)) !== null && _c !== void 0 ? _c : false;
+}
 /**
  * Create Apify MCP server
  */
 export class ActorsMcpServer {
     constructor(options = {}) {
-        var _a;
         Object.defineProperty(this, "server", {
             enumerable: true,
             configurable: true,
@@ -92,20 +108,54 @@ export class ActorsMcpServer {
             writable: true,
             value: void 0
         });
-        /** Resolved server mode — normalized once at construction from options.uiMode. */
+        /**
+         * Resolved server mode. Preliminary value at construction (`'auto'` → `DEFAULT`).
+         * Finalized inside the `initialize` request handler (see constructor) once the
+         * client's capabilities are known. Effectively set-once per connection.
+         */
         Object.defineProperty(this, "serverMode", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** Mode-specific executor for direct actor tools (`type: 'actor'`). */
+        /** Mode-specific executor for direct actor tools (`type: 'actor'`). Finalized with `serverMode`. */
         Object.defineProperty(this, "actorExecutor", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Raw option captured from `options.serverMode` (or the legacy `uiMode`). Re-resolved
+         * inside the initialize handler when set to `'auto'`; explicit `'default'`/`'apps'`
+         * values bypass auto-detect.
+         */
+        Object.defineProperty(this, "serverModeOption", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** True once mode is final. False for `'auto'` until the initialize handler resolves client capabilities. */
+        Object.defineProperty(this, "serverModeResolved", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Tool requests queued before mode is final. Actor tools are upserted immediately
+         * (mode-agnostic); we also capture the exact actor-tool slice fetched for each
+         * request so the flush composes every entry against *its own* actor list rather
+         * than the accumulated union across unrelated requests.
+         */
+        Object.defineProperty(this, "pendingToolsAfterModeResolved", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
         // Telemetry configuration (resolved from options and env vars in setupTelemetry)
         Object.defineProperty(this, "telemetryEnabled", {
             enumerable: true,
@@ -126,10 +176,7 @@ export class ActorsMcpServer {
             writable: true,
             value: new Map()
         });
-        /**
-         * Whether the connected client advertises MCP Apps UI support (`io.modelcontextprotocol/ui` extension).
-         * NOTE: This is currently informational only (logged for observability) and does not yet gate widget behavior.
-         */
+        /** Set in the initialize handler once client capabilities are known. */
         Object.defineProperty(this, "clientSupportsUi", {
             enumerable: true,
             configurable: true,
@@ -148,7 +195,20 @@ export class ActorsMcpServer {
             throw new Error('Task store must be provided for non-stdio transport types');
         }
         this.actorStore = options.actorStore;
-        this.serverMode = (_a = options.uiMode) !== null && _a !== void 0 ? _a : 'default';
+        // Constructor is an ingestion boundary for programmatic callers. Normalize via
+        // parseServerMode so that runtime-invalid values ('openai' alias, stray strings)
+        // and the legacy `uiMode` field name are accepted gracefully during the transition
+        // to the canonical `serverMode` API. Remove the `uiMode` fallback once internal
+        // consumers have migrated (see apify-mcp-server-internal#454).
+        const legacyUiMode = options.uiMode;
+        const rawServerMode = options.serverMode;
+        this.serverModeOption = rawServerMode !== undefined
+            ? parseServerMode(rawServerMode)
+            : parseServerMode(legacyUiMode);
+        // Preliminary resolution — re-resolved inside the initialize handler once
+        // client capabilities are known (only for 'auto').
+        this.serverMode = resolveServerMode(this.serverModeOption, false);
+        this.serverModeResolved = this.serverModeOption !== 'auto';
         this.actorExecutor = actorExecutorsByMode[this.serverMode];
         const { setupSigintHandler = true } = options;
         this.server = new Server({
@@ -178,10 +238,10 @@ export class ActorsMcpServer {
                 prompts: {},
                 logging: {},
             },
-            instructions: getServerInstructions(this.serverMode),
+            instructions: getServerInstructions(),
         });
         this.setupTelemetry();
-        this.setupCapabilityNegotiation();
+        this.setupInitializeHandler();
         this.setupLoggingProxy();
         this.tools = new Map();
         this.setupErrorHandling(setupSigintHandler);
@@ -213,18 +273,59 @@ export class ActorsMcpServer {
         }
     }
     /**
-     * Detects MCP Apps UI support from client capabilities after initialization.
-     * Checks for the `io.modelcontextprotocol/ui` extension with `text/html;profile=mcp-app` MIME type.
+     * Override the SDK's `initialize` request handler to run mode resolution and
+     * pending-source flush before `InitializeResult` is sent. Delegates boilerplate
+     * (protocolVersion, capabilities, instructions) to the SDK's captured `_oninitialize`.
+     *
+     * Not using `server.oninitialized`: the SDK dispatches notification handlers
+     * fire-and-forget (separate microtask), so a follow-up `tools/list` can race past them.
+     * The request handler guarantees tools are final before the response and the first `tools/list`.
      */
-    setupCapabilityNegotiation() {
-        const MCP_APPS_EXTENSION_ID = 'io.modelcontextprotocol/ui';
-        this.server.oninitialized = () => {
-            var _a, _b, _c;
-            const caps = this.server.getClientCapabilities();
-            const uiCap = (_a = caps === null || caps === void 0 ? void 0 : caps.extensions) === null || _a === void 0 ? void 0 : _a[MCP_APPS_EXTENSION_ID];
-            this.clientSupportsUi = (_c = (_b = uiCap === null || uiCap === void 0 ? void 0 : uiCap.mimeTypes) === null || _b === void 0 ? void 0 : _b.includes(RESOURCE_MIME_TYPE)) !== null && _c !== void 0 ? _c : false;
-            log.info('Client MCP Apps UI support', { clientSupportsUi: this.clientSupportsUi });
-        };
+    setupInitializeHandler() {
+        // Capture the SDK's default initialize handler installed in its constructor.
+        // Private-field access on the SDK Server — verified against
+        // @modelcontextprotocol/sdk ^1.25.x (see package.json). On SDK bumps, re-check
+        // `@modelcontextprotocol/sdk/shared/protocol.js` for a still-named `_oninitialize`;
+        // if renamed or made non-delegable, rebuild the InitializeResult shape here
+        // (protocolVersion, serverInfo, capabilities, instructions) instead of delegating.
+        // The capability-gating unit tests construct a server and act as a canary.
+        // eslint-disable-next-line no-underscore-dangle
+        const sdkInitHandler = this.server._oninitialize.bind(this.server);
+        this.server.setRequestHandler(InitializeRequestSchema, async (request) => {
+            this.clientSupportsUi = isUiSupportedByClient(request);
+            if (this.serverModeOption === 'auto') {
+                const resolved = resolveServerMode('auto', this.clientSupportsUi);
+                if (resolved !== this.serverMode) {
+                    this.serverMode = resolved;
+                    this.actorExecutor = actorExecutorsByMode[this.serverMode];
+                }
+                this.serverModeResolved = true;
+            }
+            this.options.initializeRequestData = request;
+            log.info('Resolved server mode for connection', {
+                serverMode: this.serverMode,
+                serverModeOption: this.serverModeOption,
+                clientSupportsUi: this.clientSupportsUi,
+            });
+            this.updateToolsAfterServerModeResolved();
+            await this.resolveWidgets();
+            const result = await sdkInitHandler(request);
+            result.instructions = getServerInstructions(this.serverMode);
+            return result;
+        });
+    }
+    updateToolsAfterServerModeResolved() {
+        if (this.pendingToolsAfterModeResolved.length === 0)
+            return;
+        const tools = this.pendingToolsAfterModeResolved.flatMap(({ input, actorTools }) => getToolsForServerMode(input, actorTools, this.serverMode));
+        this.pendingToolsAfterModeResolved = [];
+        // Notify after the flush so shared-state handlers (e.g. Redis recovery) see
+        // the final tool set, including mode-specific helpers added here. Pre-init,
+        // `loadToolsByName` may have fired `upsertTools(actorTools, true)` with actor
+        // tools only (helpers still queued), and `loadToolsFromUrl` / `loadToolsFromInput`
+        // don't notify at all — this call reconciles both paths to the complete set.
+        if (tools.length > 0)
+            this.upsertTools(tools, true);
     }
     /**
      * Returns an array of tool names.
@@ -300,31 +401,21 @@ export class ActorsMcpServer {
     * @param apifyClient
     */
     async loadToolsByName(toolNames, apifyClient) {
-        const loadedTools = this.listAllToolNames();
-        const actorsToLoad = [];
-        const toolsToLoad = [];
-        const internalToolMap = new Map([
-            ...getDefaultTools(this.serverMode),
-            ...Object.values(getCategoryTools(this.serverMode)).flat(),
-        ].map((tool) => [tool.name, tool]));
-        for (const tool of toolNames) {
-            // Skip if the tool is already loaded
-            if (loadedTools.includes(tool))
-                continue;
-            // Load internal tool
-            if (internalToolMap.has(tool)) {
-                toolsToLoad.push(internalToolMap.get(tool));
-                // Load Actor
-            }
-            else {
-                actorsToLoad.push(tool);
-            }
+        const loadedTools = new Set(this.listAllToolNames());
+        const missingToolNames = toolNames.filter((toolName) => !loadedTools.has(toolName));
+        if (missingToolNames.length === 0)
+            return;
+        const restoreInput = toolNamesToInput(missingToolNames);
+        const actorTools = await getActors(restoreInput, apifyClient, this.actorStore);
+        if (!this.serverModeResolved) {
+            this.pendingToolsAfterModeResolved.push({ input: restoreInput, actorTools });
+            if (actorTools.length > 0)
+                this.upsertTools(actorTools, true);
+            return;
         }
+        const toolsToLoad = getToolsForServerMode(restoreInput, actorTools, this.serverMode);
         if (toolsToLoad.length > 0) {
-            this.upsertTools(toolsToLoad);
-        }
-        if (actorsToLoad.length > 0) {
-            await this.loadActorsAsTools(actorsToLoad, apifyClient);
+            this.upsertTools(toolsToLoad, actorTools.length > 0);
         }
     }
     /**
@@ -341,20 +432,45 @@ export class ActorsMcpServer {
         }
         return actorTools;
     }
-    /**
-     * Loads tools from URL params.
-     *
-     * This method also handles enabling of Actor autoloading via the processParamsGetTools.
-     *
-     * Used primarily for SSE.
-     */
+    /** Load tools from URL params. Used by SSE and HTTP entry points. */
     async loadToolsFromUrl(url, apifyClient) {
-        const tools = await processParamsGetTools(url, apifyClient, this.serverMode, this.actorStore);
+        const input = parseInputParamsFromUrl(url);
+        const actorTools = await getActors(input, apifyClient, this.actorStore);
+        if (!this.serverModeResolved) {
+            this.pendingToolsAfterModeResolved.push({ input, actorTools });
+            if (actorTools.length > 0) {
+                log.debug('Loading actor tools from query parameters before mode resolution');
+                this.upsertTools(actorTools, false);
+            }
+            return;
+        }
+        const tools = getToolsForServerMode(input, actorTools, this.serverMode);
         if (tools.length > 0) {
             log.debug('Loading tools from query parameters');
             this.upsertTools(tools, false);
         }
     }
+    /**
+     * Two-phase: getActors (async, mode-agnostic Apify fetch) then getToolsForServerMode
+     * (sync, mode-dependent compose). When mode is unresolved, queue actorTools and let
+     * the initialize handler compose them later.
+     *
+     * Don't move the getActors await into the initialize handler — clients time out
+     * waiting for InitializeResult. The queue buffers already-fetched data, not network
+     * work. See #721.
+     */
+    async loadToolsFromInput(input, apifyClient) {
+        const actorTools = await getActors(input, apifyClient, this.actorStore);
+        if (!this.serverModeResolved) {
+            this.pendingToolsAfterModeResolved.push({ input, actorTools });
+            if (actorTools.length > 0)
+                this.upsertTools(actorTools);
+            return;
+        }
+        const tools = getToolsForServerMode(input, actorTools, this.serverMode);
+        if (tools.length > 0)
+            this.upsertTools(tools);
+    }
     /** Delete tools from the server and notify the handler.
      */
     removeToolsByName(toolNames, shouldNotifyToolsChangedHandler = false) {
@@ -452,7 +568,7 @@ export class ActorsMcpServer {
     setupResourceHandlers() {
         const resourceService = createResourceService({
             paymentProvider: this.options.paymentProvider,
-            mode: this.serverMode,
+            getMode: () => this.serverMode,
             getAvailableWidgets: () => this.availableWidgets,
         });
         this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
@@ -1271,7 +1387,7 @@ export class ActorsMcpServer {
      * Resolves widgets and determines which ones are ready to be served.
      */
     async resolveWidgets() {
-        if (this.serverMode !== 'openai') {
+        if (this.serverMode !== ServerMode.APPS) {
             return;
         }
         try {
@@ -1333,5 +1449,4 @@ export class ActorsMcpServer {
         await this.server.close();
     }
 }
-//# sourceMappingURL=server.js.map
-//# debugId=374f6a13-0750-5a19-ac52-42edce3f2308
+//# sourceMappingURL=server.js.map