feat: agentic payments v2

src/actor/server.ts

@@ -11,6 +11,7 @@ import express from 'express';
 
 import log from '@apify/log';
 
+import { ApifyClient } from '../apify-client.js';
 import { ActorsMcpServer } from '../mcp/server.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
@@ -69,13 +70,14 @@ export function createExpressApp(
                 rt: Routes.SSE,
                 tr: TransportType.SSE,
             });
-            const mcpServer = new ActorsMcpServer(false);
+            const mcpServer = new ActorsMcpServer({ setupSigintHandler: false });
             const transport = new SSEServerTransport(Routes.MESSAGE, res);
 
             // Load MCP server tools
             const apifyToken = process.env.APIFY_TOKEN as string;
             log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.SSE });
-            await mcpServer.loadToolsFromUrl(req.url, apifyToken);
+            const apifyClient = new ApifyClient({ token: apifyToken });
+            await mcpServer.loadToolsFromUrl(req.url, apifyClient);
 
             transportsSSE[transport.sessionId] = transport;
             mcpServers[transport.sessionId] = mcpServer;
@@ -152,12 +154,13 @@ export function createExpressApp(
                     sessionIdGenerator: () => randomUUID(),
                     enableJsonResponse: false, // Use SSE response mode
                 });
-                const mcpServer = new ActorsMcpServer(false);
+                const mcpServer = new ActorsMcpServer({ setupSigintHandler: false });
 
                 // Load MCP server tools
                 const apifyToken = process.env.APIFY_TOKEN as string;
                 log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.HTTP });
-                await mcpServer.loadToolsFromUrl(req.url, apifyToken);
+                const apifyClient = new ApifyClient({ token: apifyToken });
+                await mcpServer.loadToolsFromUrl(req.url, apifyClient);
 
                 // Connect the transport to the MCP server BEFORE handling the request
                 await mcpServer.connect(transport);

src/apify-client.ts

@@ -4,6 +4,11 @@ import type { AxiosRequestConfig } from 'axios';
 
 import { USER_AGENT_ORIGIN } from './const.js';
 
+interface ExtendedApifyClientOptions extends Omit<ApifyClientOptions, 'token'> {
+    token?: string | null | undefined;
+    skyfirePayId?: string;
+}
+
 /**
  * Adds a User-Agent header to the request config.
  * @param config
@@ -23,22 +28,37 @@ export function getApifyAPIBaseUrl(): string {
 }
 
 export class ApifyClient extends _ApifyClient {
-    constructor(options: ApifyClientOptions) {
+    constructor(options: ExtendedApifyClientOptions) {
         /**
          * In order to publish to DockerHub, we need to run their build task to validate our MCP server.
          * This was failing since we were sending this dummy token to Apify in order to build the Actor tools.
          * So if we encounter this dummy value, we remove it to use Apify client as unauthenticated, which is sufficient
          * for server start and listing of tools.
          */
-        if (options.token?.toLowerCase() === 'your-apify-token') {
+        if (options.token?.toLowerCase() === 'your-apify-token' || options.token === null) {
             // eslint-disable-next-line no-param-reassign
             delete options.token;
         }
 
+        const { skyfirePayId, ...clientOptions } = options;
+        const requestInterceptors = [addUserAgent];
+        /**
+         * Add skyfire-pay-id header if provided.
+         */
+        if (skyfirePayId) {
+            requestInterceptors.push((config) => {
+                const updatedConfig = { ...config };
+                updatedConfig.headers = updatedConfig.headers ?? {};
+                updatedConfig.headers['skyfire-pay-id'] = skyfirePayId;
+                return updatedConfig;
+            });
+        }
+
         super({
-            ...options,
+            // token null case is handled, we can assert type here
+            ...clientOptions as ApifyClientOptions,
             baseUrl: getApifyAPIBaseUrl(),
-            requestInterceptors: [addUserAgent],
+            requestInterceptors,
         });
     }
 }

src/const.ts

@@ -53,6 +53,13 @@ export const defaults = {
 };
 
 export const ACTOR_ADDITIONAL_INSTRUCTIONS = 'Never call/execute tool/Actor unless confirmed by the user.';
+export const SKYFIRE_MIN_CHARGE_USD = 0.005;
+
+export const SKYFIRE_TOOL_INSTRUCTIONS = `To run the Actor, you need to provide a Skyfire payment ID in the \`skyfire-pay-id\` input property. You first need to create the Skyfire PAY token by calling the \`create-pay-token\` tool from the Skyfire MCP server and then provide the created token in the \`skyfire-pay-id\` input property when calling Actor tool. The Skyfire PAY token is used for billing purposes and needs to be charged with at least ${SKYFIRE_MIN_CHARGE_USD} USD.`;
+
+export const SKYFIRE_PAY_ID_PROPERTY_DESCRIPTION = `Skyfire PAY token ID used for billing purposes.`;
+
+export const SKYFIRE_README_CONTENT = `The Apify MCP Server allows clients to interact with Apify Actors, storage, and documentation. Before running any Apify Actor, you need to set up a Skyfire PAY token for billing purposes. To set up the PAY token you need to use the create-pay-token tool from the Skyfire MCP server. The PAY token must be charged with a minimum of ${SKYFIRE_MIN_CHARGE_USD} USD to be valid.`;
 
 // Cache
 export const ACTOR_CACHE_MAX_SIZE = 500;

src/index-internals.ts

@@ -2,6 +2,7 @@
  This file provides essential internal functions for Apify MCP servers, serving as an internal library.
 */
 
+import { ApifyClient } from './apify-client.js';
 import { defaults, HelperTools } from './const.js';
 import { processParamsGetTools } from './mcp/utils.js';
 import { addTool } from './tools/helpers.js';
@@ -12,6 +13,7 @@ import { getExpectedToolNamesByCategories, getToolPublicFieldOnly } from './util
 import { TTLLRUCache } from './utils/ttl-lru.js';
 
 export {
+    ApifyClient,
     getExpectedToolNamesByCategories,
     TTLLRUCache,
     actorNameToToolName,

src/main.ts

@@ -9,6 +9,7 @@ import type { ActorCallOptions } from 'apify-client';
 import log from '@apify/log';
 
 import { createExpressApp } from './actor/server.js';
+import { ApifyClient } from './apify-client.js';
 import { processInput } from './input.js';
 import { callActorGetDataset } from './tools/index.js';
 import type { Input } from './types.js';
@@ -44,7 +45,9 @@ if (STANDBY_MODE) {
         await Actor.fail('If you need to debug a specific Actor, please provide the debugActor and debugActorInput fields in the input');
     }
     const options = { memory: input.maxActorMemoryBytes } as ActorCallOptions;
-    const callResult = await callActorGetDataset(input.debugActor!, input.debugActorInput!, process.env.APIFY_TOKEN, options);
+
+    const apifyClient = new ApifyClient({ token: process.env.APIFY_TOKEN });
+    const callResult = await callActorGetDataset(input.debugActor!, input.debugActorInput!, apifyClient, options);
 
     if (callResult && callResult.previewItems.length > 0) {
         await Actor.pushData(callResult.previewItems);

src/mcp/actors.ts

@@ -64,19 +64,3 @@ export async function getRealActorID(actorIdOrName: string, apifyToken: string):
 export async function getActorStandbyURL(realActorId: string, standbyBaseUrl = 'apify.actor'): Promise<string> {
     return `https://${realActorId}.${standbyBaseUrl}`;
 }
-
-export async function getActorDefinition(actorID: string, apifyToken: string): Promise<ActorDefinition> {
-    const apifyClient = new ApifyClient({ token: apifyToken });
-    const actor = apifyClient.actor(actorID);
-    const defaultBuildClient = await actor.defaultBuild();
-    const buildInfo = await defaultBuildClient.get();
-    if (!buildInfo) {
-        throw new Error(`Default build for Actor ${actorID} not found`);
-    }
-    const { actorDefinition } = buildInfo;
-    if (!actorDefinition) {
-        throw new Error(`Actor default build ${actorID} does not have Actor definition`);
-    }
-
-    return actorDefinition;
-}

src/mcp/server.ts

@@ -15,6 +15,7 @@ import {
     ListResourceTemplatesRequestSchema,
     ListToolsRequestSchema,
     McpError,
+    ReadResourceRequestSchema,
     ServerNotificationSchema,
     SetLevelRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
@@ -23,9 +24,13 @@ import { type ActorCallOptions, ApifyApiError } from 'apify-client';
 
 import log from '@apify/log';
 
+import { ApifyClient } from '../apify-client.js';
 import {
     SERVER_NAME,
     SERVER_VERSION,
+    SKYFIRE_PAY_ID_PROPERTY_DESCRIPTION,
+    SKYFIRE_README_CONTENT,
+    SKYFIRE_TOOL_INSTRUCTIONS,
 } from '../const.js';
 import { prompts } from '../prompts/index.js';
 import { callActorGetDataset, defaultTools, getActorsAsTools, toolCategories } from '../tools/index.js';
@@ -40,6 +45,14 @@ import { processParamsGetTools } from './utils.js';
 
 type ToolsChangedHandler = (toolNames: string[]) => void;
 
+interface ActorsMcpServerOptions {
+    setupSigintHandler?: boolean;
+    /**
+     * Switch to enable Skyfire agentic payment mode.
+     */
+    skyfireMode?: boolean;
+}
+
 /**
  * Create Apify MCP server
  */
@@ -49,8 +62,11 @@ export class ActorsMcpServer {
     private toolsChangedHandler: ToolsChangedHandler | undefined;
     private sigintHandler: (() => Promise<void>) | undefined;
     private currentLogLevel = 'info';
+    public readonly options: ActorsMcpServerOptions;
 
-    constructor(setupSigintHandler = true) {
+    constructor(options: ActorsMcpServerOptions = {}) {
+        this.options = options;
+        const { setupSigintHandler = true } = options;
         this.server = new Server(
             {
                 name: SERVER_NAME,
@@ -161,7 +177,7 @@ export class ActorsMcpServer {
     * @param toolNames - Array of tool names to ensure are loaded
     * @param apifyToken - Apify API token for authentication
     */
-    public async loadToolsByName(toolNames: string[], apifyToken: string) {
+    public async loadToolsByName(toolNames: string[], apifyClient: ApifyClient) {
         const loadedTools = this.listAllToolNames();
         const actorsToLoad: string[] = [];
         const toolsToLoad: ToolEntry[] = [];
@@ -186,7 +202,7 @@ export class ActorsMcpServer {
         }
 
         if (actorsToLoad.length > 0) {
-            await this.loadActorsAsTools(actorsToLoad, apifyToken);
+            await this.loadActorsAsTools(actorsToLoad, apifyClient);
         }
     }
 
@@ -197,8 +213,8 @@ export class ActorsMcpServer {
      * @param apifyToken - Apify API token for authentication
      * @returns Promise<ToolEntry[]> - Array of loaded tool entries
      */
-    public async loadActorsAsTools(actorIdsOrNames: string[], apifyToken: string): Promise<ToolEntry[]> {
-        const actorTools = await getActorsAsTools(actorIdsOrNames, apifyToken);
+    public async loadActorsAsTools(actorIdsOrNames: string[], apifyClient: ApifyClient): Promise<ToolEntry[]> {
+        const actorTools = await getActorsAsTools(actorIdsOrNames, apifyClient);
         if (actorTools.length > 0) {
             this.upsertTools(actorTools, true);
         }
@@ -212,8 +228,8 @@ export class ActorsMcpServer {
      *
      * Used primarily for SSE.
      */
-    public async loadToolsFromUrl(url: string, apifyToken: string) {
-        const tools = await processParamsGetTools(url, apifyToken);
+    public async loadToolsFromUrl(url: string, apifyClient: ApifyClient) {
+        const tools = await processParamsGetTools(url, apifyClient);
         if (tools.length > 0) {
             log.debug('Loading tools from query parameters');
             this.upsertTools(tools, false);
@@ -307,10 +323,44 @@ export class ActorsMcpServer {
 
     private setupResourceHandlers(): void {
         this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-            // No resources available, return empty response
+            /**
+             * Return the usage guide resource only if Skyfire mode is enabled. No resources otherwise for normal mode.
+             */
+            if (this.options.skyfireMode) {
+                return {
+                    resources: [
+                        {
+                            uri: 'file://readme.md',
+                            name: 'readme',
+                            description: `Apify MCP Server usage guide. Read this to understand how to use the server, especially in Skyfire mode before interacting with it.`,
+                            mimeType: 'text/markdown',
+                        },
+                    ],
+                };
+            }
             return { resources: [] };
         });
 
+        if (this.options.skyfireMode) {
+            this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+                const { uri } = request.params;
+                if (uri === 'file://readme.md') {
+                    return {
+                        contents: [{
+                            uri: 'file://readme.md',
+                            mimeType: 'text/markdown',
+                            text: SKYFIRE_README_CONTENT,
+                        }],
+                    };
+                }
+                return {
+                    contents: [{
+                        uri, mimeType: 'text/plain', text: `Resource ${uri} not found`,
+                    }],
+                };
+            });
+        }
+
         this.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
             // No resource templates available, return empty response
             return { resourceTemplates: [] };
@@ -368,6 +418,24 @@ export class ActorsMcpServer {
          * @returns {object} - The response object containing the tools.
          */
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            /**
+             * Hack for the Skyfire agentic payments, we check if Skyfire mode is enabled we ad-hoc add
+             * the `skyfire-pay-id` input property to all Actor tools and `call-actor` tool.
+             */
+            if (this.options.skyfireMode) {
+                for (const toolEntry of this.tools.values()) {
+                    if (toolEntry.type === 'actor' || (toolEntry.type === 'internal' && toolEntry.tool.name === 'call-actor')) {
+                        if (toolEntry.tool.inputSchema && 'properties' in toolEntry.tool.inputSchema) {
+                            (toolEntry.tool.inputSchema.properties as Record<string, unknown>)['skyfire-pay-id'] = {
+                                type: 'string',
+                                description: SKYFIRE_PAY_ID_PROPERTY_DESCRIPTION,
+                            };
+                        }
+                        // Update description to include Skyfire instructions
+                        toolEntry.tool.description += `\n\n${SKYFIRE_TOOL_INSTRUCTIONS}`;
+                    }
+                }
+            }
             const tools = Array.from(this.tools.values()).map((tool) => getToolPublicFieldOnly(tool.tool));
             return { tools };
         });
@@ -391,7 +459,7 @@ export class ActorsMcpServer {
             delete request.params.userRentedActorIds;
 
             // Validate token
-            if (!apifyToken) {
+            if (!apifyToken && !this.options.skyfireMode) {
                 const msg = 'APIFY_TOKEN is required. It must be set in the environment variables or passed as a parameter in the body.';
                 log.error(msg);
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
@@ -516,19 +584,38 @@ export class ActorsMcpServer {
 
                 // Handle actor tool
                 if (tool.type === 'actor') {
+                    if (this.options.skyfireMode
+                        && args['skyfire-pay-id'] === undefined
+                    ) {
+                        return {
+                            content: [{
+                                type: 'text',
+                                text: SKYFIRE_TOOL_INSTRUCTIONS,
+                            }],
+                        };
+                    }
+
                     const actorTool = tool.tool as ActorTool;
 
                     // Create progress tracker if progressToken is available
                     const progressTracker = createProgressTracker(progressToken, extra.sendNotification);
 
                     const callOptions: ActorCallOptions = { memory: actorTool.memoryMbytes };
 
+                    /**
+                     * Create Apify token, for Skyfire mode use `skyfire-pay-id` and for normal mode use `apifyToken`.
+                     */
+                    const { 'skyfire-pay-id': skyfirePayId, ...actorArgs } = args as Record<string, unknown>;
+                    const apifyClient = this.options.skyfireMode && typeof skyfirePayId === 'string'
+                        ? new ApifyClient({ skyfirePayId })
+                        : new ApifyClient({ token: apifyToken });
+
                     try {
-                        log.info('Calling Actor', { actorName: actorTool.actorFullName, input: args });
+                        log.info('Calling Actor', { actorName: actorTool.actorFullName, input: actorArgs });
                         const callResult = await callActorGetDataset(
                             actorTool.actorFullName,
-                            args,
-                            apifyToken as string,
+                            actorArgs,
+                            apifyClient,
                             callOptions,
                             progressTracker,
                             extra.signal,

src/mcp/utils.ts

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { parse } from 'node:querystring';
 
+import type { ApifyClient } from 'apify-client';
+
 import { processInput } from '../input.js';
 import type { Input } from '../types.js';
 import { loadToolsFromInput } from '../utils/tools-loader.js';
@@ -39,9 +41,9 @@ export function getProxyMCPServerToolName(url: string, toolName: string): string
  * @param url
  * @param apifyToken
  */
-export async function processParamsGetTools(url: string, apifyToken: string) {
+export async function processParamsGetTools(url: string, apifyClient: ApifyClient) {
     const input = parseInputParamsFromUrl(url);
-    return await loadToolsFromInput(input, apifyToken);
+    return await loadToolsFromInput(input, apifyClient);
 }
 
 export function parseInputParamsFromUrl(url: string): Input {