fix: migrate custom request parameters to _meta structure for SDK compatibility (#379)

MQ37 · web-flow · commit 6329c4c03d73 · 2026-01-05T09:13:36.000+01:00
- Move mcpSessionId, apifyToken, and userRentedActorIds into params._meta object
- Newer MCP SDK versions filter out unknown top-level parameters, so _meta is used as standard container
- Add ApifyRequestParams type definition for proper typing of _meta structure
- Update parameter extraction in tool handlers and task handlers to read from _meta
- Refactor parameter injection to use nullish coalescing assignment (??=) for clarity
- Allow _meta underscore in ESLint config as standard MCP protocol field
- Remove unnecessary parameter deletion after extraction since they're now in _meta
- Enable MCP Session ID error throwing since injection is now guaranteed

FIXES: Parameters being stripped by newer MCP SDK versions causing task store errors
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -47,6 +47,13 @@ export default [
                     ],
                 },
             ],
+            // Allow _meta as it's a standard MCP protocol field for metadata
+            'no-underscore-dangle': [
+                'error',
+                {
+                    allow: ['_meta'],
+                },
+            ],
         },
         languageOptions: {
             // Use ES modules (import/export syntax)
diff --git a/src/actor/server.ts b/src/actor/server.ts
@@ -15,6 +15,7 @@ import log from '@apify/log';
 
 import { ApifyClient } from '../apify-client.js';
 import { ActorsMcpServer } from '../mcp/server.js';
+import type { ApifyRequestParams } from '../types.js';
 import { parseBooleanFromString } from '../utils/generic.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
@@ -117,8 +118,9 @@ export function createExpressApp(
                 const msgRecord = message as Record<string, unknown>;
                 // Inject session ID into all requests with params
                 if (msgRecord.params) {
-                    const params = msgRecord.params as Record<string, unknown>;
-                    params.mcpSessionId = mcpSessionId;
+                    const params = msgRecord.params as ApifyRequestParams;
+                    params._meta ??= {};
+                    params._meta.mcpSessionId = mcpSessionId;
                 }
                 // Call the original onmessage handler
                 if (originalOnMessage) {
@@ -194,8 +196,9 @@ export function createExpressApp(
                 // Reuse existing transport
                 transport = transports[sessionId];
                 // Inject session ID into request params for existing sessions
-                if (req.body && req.body.params) {
-                    req.body.params.mcpSessionId = sessionId;
+                if (req.body?.params) {
+                    req.body.params._meta ??= {};
+                    req.body.params._meta.mcpSessionId = sessionId;
                 }
             } else if (!sessionId && isInitializeRequest(req.body)) {
                 // New initialization request
@@ -253,8 +256,9 @@ export function createExpressApp(
             }
 
             // Inject session ID into request params for all requests
-            if (req.body && req.body.params && sessionId) {
-                req.body.params.mcpSessionId = sessionId;
+            if (req.body?.params && sessionId) {
+                req.body.params._meta ??= {};
+                req.body.params._meta.mcpSessionId = sessionId;
             }
 
             // Handle the request with existing transport - no need to reconnect
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
@@ -57,6 +57,7 @@ import type {
     ActorMcpTool,
     ActorsMcpServerOptions,
     ActorTool,
+    ApifyRequestParams,
     HelperTool,
     TelemetryEnv,
     ToolCallTelemetryProperties,
@@ -525,8 +526,9 @@ export class ActorsMcpServer {
         // List tasks
         this.server.setRequestHandler(ListTasksRequestSchema, async (request) => {
             // mcpSessionId is injected at transport layer for session isolation in task stores
-            const params = (request.params || {}) as { cursor?: string; mcpSessionId?: string };
-            const { cursor, mcpSessionId } = params;
+            const params = (request.params || {}) as ApifyRequestParams & { cursor?: string };
+            const { cursor } = params;
+            const mcpSessionId = params._meta?.mcpSessionId;
             log.debug('[ListTasksRequestSchema] Listing tasks', { mcpSessionId });
             const result = await this.taskStore.listTasks(cursor, mcpSessionId);
             return { tasks: result.tasks, nextCursor: result.nextCursor };
@@ -535,8 +537,9 @@ export class ActorsMcpServer {
         // Get task status
         this.server.setRequestHandler(GetTaskRequestSchema, async (request) => {
             // mcpSessionId is injected at transport layer for session isolation in task stores
-            const params = (request.params || {}) as { taskId: string; mcpSessionId?: string };
-            const { taskId, mcpSessionId } = params;
+            const params = (request.params || {}) as ApifyRequestParams & { taskId: string };
+            const { taskId } = params;
+            const mcpSessionId = params._meta?.mcpSessionId;
             log.debug('[GetTaskRequestSchema] Getting task status', { taskId, mcpSessionId });
             const task = await this.taskStore.getTask(taskId, mcpSessionId);
             if (task) return task;
@@ -549,8 +552,9 @@ export class ActorsMcpServer {
         // Get task result payload
         this.server.setRequestHandler(GetTaskPayloadRequestSchema, async (request) => {
             // mcpSessionId is injected at transport layer for session isolation in task stores
-            const params = (request.params || {}) as { taskId: string; mcpSessionId?: string };
-            const { taskId, mcpSessionId } = params;
+            const params = (request.params || {}) as ApifyRequestParams & { taskId: string };
+            const { taskId } = params;
+            const mcpSessionId = params._meta?.mcpSessionId;
             log.debug('[GetTaskPayloadRequestSchema] Getting task result', { taskId, mcpSessionId });
             const task = await this.taskStore.getTask(taskId, mcpSessionId);
             if (!task) {
@@ -573,8 +577,9 @@ export class ActorsMcpServer {
         // Cancel task
         this.server.setRequestHandler(CancelTaskRequestSchema, async (request) => {
             // mcpSessionId is injected at transport layer for session isolation in task stores
-            const params = (request.params || {}) as { taskId: string; mcpSessionId?: string };
-            const { taskId, mcpSessionId } = params;
+            const params = (request.params || {}) as ApifyRequestParams & { taskId: string };
+            const { taskId } = params;
+            const mcpSessionId = params._meta?.mcpSessionId;
             log.debug('[CancelTaskRequestSchema] Cancelling task', { taskId, mcpSessionId });
 
             const task = await this.taskStore.getTask(taskId, mcpSessionId);
@@ -622,22 +627,19 @@ export class ActorsMcpServer {
          * @throws {McpError} - based on the McpServer class code from the typescript MCP SDK
          */
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const params = request.params as ApifyRequestParams & { name: string; arguments?: Record<string, unknown> };
             // eslint-disable-next-line prefer-const
-            let { name, arguments: args, _meta: meta } = request.params;
-            const { progressToken } = meta || {};
-            const apifyToken = (request.params.apifyToken || this.options.token || process.env.APIFY_TOKEN) as string;
-            const userRentedActorIds = request.params.userRentedActorIds as string[] | undefined;
+            let { name, arguments: args, _meta: meta } = params;
+            const progressToken = meta?.progressToken;
+            const metaApifyToken = meta?.apifyToken;
+            const apifyToken = (metaApifyToken || this.options.token || process.env.APIFY_TOKEN) as string;
+            const userRentedActorIds = meta?.userRentedActorIds;
             // mcpSessionId was injected upstream it is important and required for long running tasks as the store uses it and there is not other way to pass it
-            const mcpSessionId = typeof request.params.mcpSessionId === 'string' ? request.params.mcpSessionId : undefined;
+            const mcpSessionId = meta?.mcpSessionId;
             if (!mcpSessionId) {
                 log.error('MCP Session ID is missing in tool call request. This should never happen.');
-                // TEMP: do not throw for now as it causes issues with stdio transport
-                // throw new Error('MCP Session ID is required for tool calls');
+                throw new Error('MCP Session ID is required for tool calls');
             }
-            // Remove apifyToken from request.params just in case
-            delete request.params.apifyToken;
-            // Remove other custom params passed from apify-mcp-server
-            delete request.params.userRentedActorIds;
 
             // Validate token
             if (!apifyToken && !this.options.skyfireMode && !this.options.allowUnauthMode) {
@@ -690,7 +692,7 @@ Please provide the required arguments for this tool. Check the tool's input sche
             }
             // Decode dot property names in arguments before validation,
             // since validation expects the original, non-encoded property names.
-            args = decodeDotPropertyNames(args);
+            args = decodeDotPropertyNames(args as Record<string, unknown>) as Record<string, unknown>;
             log.debug('Validate arguments for tool', { toolName: tool.name, input: args });
             if (!tool.ajvValidate(args)) {
                 const errors = tool?.ajvValidate.errors || [];
diff --git a/src/stdio.ts b/src/stdio.ts
@@ -33,7 +33,7 @@ import { DEFAULT_TELEMETRY_ENV, TELEMETRY_ENV } from './const.js';
 import { processInput } from './input.js';
 import { ActorsMcpServer } from './mcp/server.js';
 import { getTelemetryEnv } from './telemetry.js';
-import type { Input, TelemetryEnv, ToolSelector } from './types.js';
+import type { ApifyRequestParams, Input, TelemetryEnv, ToolSelector } from './types.js';
 import { parseCommaSeparatedList } from './utils/generic.js';
 import { loadToolsFromInput } from './utils/tools-loader.js';
 
@@ -201,8 +201,9 @@ async function main() {
         // Inject session ID into all requests for task isolation and session tracking.
         // CRITICAL: Always create params object if missing (some requests like listTasks/getTasks don't have params),
         // otherwise mcpSessionId injection fails, breaking session isolation in multi-node setups.
-        const params = (msgRecord.params || {}) as Record<string, unknown>;
-        params.mcpSessionId = mcpSessionId;
+        const params = (msgRecord.params || {}) as ApifyRequestParams;
+        params._meta ??= {};
+        params._meta.mcpSessionId = mcpSessionId;
         msgRecord.params = params;
 
         // Call the original onmessage handler
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -206,10 +206,9 @@ Actor description: ${definition.description}`;
                 openWorldHint: true,
             },
             // Allow long running tasks for Actor tools, make it optional for now
-            // TEMP: disable for now as it causes issues with session id error for stdio transport
-            // execution: {
-            //     taskSupport: 'optional',
-            // },
+            execution: {
+                taskSupport: 'optional',
+            },
         });
     }
     return tools;
diff --git a/src/types.ts b/src/types.ts
@@ -411,3 +411,27 @@ export type StructuredActorCard = {
     modifiedAt?: string;
     isDeprecated: boolean;
 }
+
+/**
+ * MCP request parameters with Apify-specific extensions.
+ * Extends the standard MCP params object with Apify custom fields in the _meta object.
+ */
+export type ApifyRequestParams = {
+    /**
+     * Metadata object for MCP and Apify-specific fields.
+     */
+    _meta?: {
+        /** Session ID for tracking MCP requests across the Apify server */
+        mcpSessionId?: string;
+        /** Apify API token for authentication */
+        apifyToken?: string;
+        /** List of Actor IDs that the user has rented */
+        userRentedActorIds?: string[];
+        /** Progress token for out-of-band progress notifications (standard MCP) */
+        progressToken?: string | number;
+        /** Allow other metadata fields */
+        [key: string]: unknown;
+    };
+    /** Allow any other request parameters */
+    [key: string]: unknown;
+};
