@apify/actors-mcp-server 0.9.18-beta.0 → 0.9.18-beta.10

package/README.md

@@ -23,7 +23,7 @@ The Apify Model Context Protocol (MCP) server at [**mcp.apify.com**](https://mcp
 >
 > For the best experience, connect your AI assistant to our hosted server at **[`https://mcp.apify.com`](https://mcp.apify.com)**. The hosted server supports the latest features - including output schema inference for structured Actor results - that are not available when running locally via stdio.
 
-💰 The server also supports [Skyfire agentic payments](#-skyfire-agentic-payments), allowing AI agents to pay for Actor runs without an API token.
+💰 The server also supports [agentic payments](#-agentic-payments) via [x402](#-x402) and [Skyfire](#-skyfire), allowing AI agents to pay for Actor runs without an API token.
 
 Apify MCP Server is compatible with `Claude Code, Claude.ai, Cursor, VS Code` and any client that adheres to the Model Context Protocol.
 Check out the [MCP clients section](#-mcp-clients) for more details or visit the [MCP configuration page](https://mcp.apify.com).
@@ -36,11 +36,16 @@ Check out the [MCP clients section](#-mcp-clients) for more details or visit the
 - [⚠️ SSE transport deprecation](#%EF%B8%8F-sse-transport-deprecation)
 - [🤖 MCP clients](#-mcp-clients)
 - [🪄 Try Apify MCP instantly](#-try-apify-mcp-instantly)
-- [💰 Skyfire agentic payments](#-skyfire-agentic-payments)
+- [💰 Agentic payments](#-agentic-payments)
+  - [How agentic payments work](#how-agentic-payments-work)
+  - [💸 x402](#-x402)
+  - [🔥 Skyfire](#-skyfire)
 - [🛠️ Tools, resources, and prompts](#%EF%B8%8F-tools-resources-and-prompts)
 - [📊 Telemetry](#-telemetry)
-- [🐛 Troubleshooting (local MCP server)](#-troubleshooting-local-mcp-server)
+- [💬 Usage examples](#-usage-examples)
+- [🐛 Troubleshooting](#-troubleshooting)
 - [⚙️ Development](#%EF%B8%8F-development)
+- [🔒 Privacy policy](#-privacy-policy)
 - [🤝 Contributing](#-contributing)
 - [📚 Learn more](#-learn-more)
 
@@ -89,18 +94,15 @@ Visit [mcp.apify.com](https://mcp.apify.com) to configure the server for your pr
 
 ![Apify-MCP-configuration-clients](https://raw.githubusercontent.com/apify/apify-mcp-server/refs/heads/master/docs/mcp-clients.png)
 
-### Supported clients matrix
+### Tested clients
 
-The following table outlines the tested MCP clients and their level of support for key features.
-
-| Client                      | Dynamic Tool Discovery | Notes                                                |
-|-----------------------------|------------------------|------------------------------------------------------|
-| **Claude.ai (web)**         | 🟡 Partial             | Tools may need to be reloaded manually in the client |
-| **Claude Desktop**          | 🟡 Partial             | Tools may need to be reloaded manually in the client |
-| **VS Code (Genie)**         | ✅ Full                 |                                                      |
-| **Cursor**                  | ✅ Full                 |                                                      |
-| **Apify Tester MCP Client** | ✅ Full                 | Designed for testing Apify MCP servers               |
-| **OpenCode**                | ✅ Full                 |                                                      |
+- [Claude Desktop](https://docs.apify.com/platform/integrations/claude-desktop)
+- Claude.ai (web)
+- [ChatGPT](https://docs.apify.com/platform/integrations/chatgpt)
+- VS Code (Genie)
+- Cursor
+- OpenCode
+- [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) — designed for testing Apify MCP servers
 
 
 **Smart tool selection based on client capabilities:**
@@ -118,21 +120,80 @@ Want to try Apify MCP without any setup?
 Check out [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
 
 This interactive, chat-like interface provides an easy way to explore the capabilities of Apify MCP without any local setup.
-Just sign in with your Apify account and start experimenting with web scraping, data extraction, and automation tools!
+Sign in with your Apify account and start experimenting with web scraping, data extraction, and automation tools!
 
 Or use the MCP bundle file (formerly known as Anthropic Desktop extension file, or DXT) for one-click installation: [Apify MCP Server MCPB file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb)
 
-# 💰 Skyfire agentic payments
 
-The Apify MCP Server integrates with [Skyfire](https://www.skyfire.xyz/) to enable agentic payments - AI agents can autonomously pay for Actor runs without requiring an Apify API token. Instead of authenticating with `APIFY_TOKEN`, the agent uses Skyfire PAY tokens to cover billing for each tool call.
+# 💰 Agentic payments
+
+You can pay for Actor runs without an Apify API token using either **x402** or **Skyfire**.
+
+- **x402** pays with USDC on [Base](https://base.org) and does not require a separate platform account. It is fully supported by [`mcpc`](https://github.com/apify/mcp-cli) (`npm install -g @apify/mcpc`). We use `mcpc` because it is one of the few MCP clients that supports the latest features and the x402 protocol natively.
+- **Skyfire** pays with PAY tokens and requires a Skyfire account with a funded wallet. It does not require a special MCP client; the entire payment flow is handled directly through the MCP tool call parameters.
+
+## How agentic payments work
+
+Actor run costs vary, so both payment methods use a prepaid balance model. The payment flow happens in four steps:
+
+1. **Discovery**: The agent discovers Actors with `search-actors` or `fetch-actor-details`. Those calls are free.
+2. **Prepayment**: Before running a paid Actor tool, the agent funds a prepaid balance.
+   - **x402**: `mcpc` automatically signs a $1.00 USDC transaction.
+   - **Skyfire**: The agent creates a PAY token (minimum $5.00) using Skyfire's `create-pay-token` tool.
+3. **Execution**: The agent calls the Actor tool.
+   - **x402**: Handled automatically by `mcpc` using the prepaid balance.
+   - **Skyfire**: The agent explicitly passes the PAY token in the `skyfire-pay-id` input property.
+4. **Resolution**: The tool returns the Actor results. Unused funds stay available for later runs.
+   - **x402**: After 60 minutes of inactivity, the server refunds any unused balance to the wallet on [Base](https://base.org).
+   - **Skyfire**: Skyfire returns unused funds when the token expires.
+
+## 💸 x402
+
+The [x402 protocol](https://www.x402.org/) enables direct, machine-to-machine payments. Your MCP client can use it to pay for Actor runs with USDC on the [Base blockchain](https://base.org/), completely bypassing the need for an Apify API token.
+
+### Prerequisites
+
+- A wallet with USDC on [Base](https://base.org) mainnet.
+
+### Setup
+
+Create or import a wallet:
+
+```bash
+# Create a new wallet
+mcpc x402 init
+
+# Import an existing wallet
+mcpc x402 import <private-key>
+
+# Show the wallet address so you can fund it with USDC on Base (https://base.org)
+mcpc x402 info
+```
+
+Connect to the server with x402 enabled:
+
+```bash
+mcpc connect "mcp.apify.com?payment=x402" @apify --x402
+```
+
+You can now call a paid tool:
+
+```bash
+mcpc @apify tools-call call-actor actor:="apify/rag-web-browser" input:='{"query": "latest AI news"}'
+```
+
+## 🔥 Skyfire
 
-**Prerequisites:**
-- A [Skyfire account](https://www.skyfire.xyz/) with a funded wallet
-- An MCP client that supports multiple servers (e.g., Claude Desktop, OpenCode, VS Code)
+[Skyfire](https://www.skyfire.xyz/) provides managed payment infrastructure for AI agents. Instead of authenticating with an Apify API token, your agent passes a Skyfire payment token to cover the cost of each tool call using PAY tokens.
 
-**Setup:**
+### Prerequisites
 
-Configure both the Skyfire MCP server and Apify MCP Server in your MCP client. Enable payment mode by adding the `payment=skyfire` query parameter to the Apify server URL:
+- A [Skyfire account](https://www.skyfire.xyz/) with a funded wallet.
+- An MCP client that supports multiple servers, such as Claude Desktop, OpenCode, or VS Code.
+
+### Setup
+
+Configure the Skyfire MCP server and the Apify MCP Server in your client. Add `payment=skyfire` to the Apify server URL:
 
 ```json
 {
@@ -150,16 +211,7 @@ Configure both the Skyfire MCP server and Apify MCP Server in your MCP client. E
 }
 ```
 
-**How it works:**
-
-When Skyfire mode is enabled, the agent handles the full payment flow autonomously:
-
-1. The agent discovers relevant Actors via `search-actors` or `fetch-actor-details` (these remain free).
-2. Before executing an Actor, the agent creates a PAY token using the `create-pay-token` tool from the Skyfire MCP server (minimum $5.00 USD).
-3. The agent passes the PAY token in the `skyfire-pay-id` input property when calling the Actor tool.
-4. Results are returned as usual. Unused funds on the token remain available for future runs or are returned upon expiration.
-
-To learn more, see the [Skyfire integration documentation](https://docs.apify.com/platform/integrations/skyfire) and the [Agentic Payments with Skyfire](https://blog.apify.com/agentic-payments-skyfire/) blog post.
+See the [Skyfire integration documentation](https://docs.apify.com/platform/integrations/skyfire) for setup details. The [Agentic Payments with Skyfire](https://blog.apify.com/agentic-payments-skyfire/) post provides additional background.
 
 # 🛠️ Tools, resources, and prompts
 
@@ -351,6 +403,34 @@ The server provides a set of predefined example prompts to help you get started
 
 The server does not yet provide any resources.
 
+## 💬 Usage examples
+
+Below are realistic examples showing how an AI assistant uses the Apify MCP Server tools.
+
+### Example 1: Search the web using RAG Web Browser
+
+**User prompt:**
+> Find the latest news about autonomous AI agents and summarize the key developments.
+
+The AI assistant calls the pre-configured `apify--rag-web-browser` Actor tool to search the web and return content from top results.
+The tool returns markdown content from the top 3 search results, which the AI assistant then summarizes for the user.
+
+### Example 2: Discover and run an Actor from the Apify Store
+
+**User prompt:**
+> Scrape the top 10 restaurants in Prague from Google Maps with their contact details.
+
+The AI assistant first searches for a suitable Actor, inspects its input schema, and then executes it.
+The tool returns a preview of the scraped data including restaurant names, addresses, ratings, phone numbers, and websites.
+
+### Example 3: Retrieve and paginate through Actor run results
+
+**User prompt:**
+> Show me the next 10 results from that scraping run.
+
+The AI assistant uses the dataset ID from the previous Actor run to fetch additional items.
+Expected output: The tool returns the next page of structured data items from the Actor's output dataset.
+
 ## 📡 Telemetry
 
 The Apify MCP Server collects telemetry data about tool calls to help Apify understand usage patterns and improve the service.
@@ -434,7 +514,7 @@ Example: `https://mcp.apify.com?tools=search-actors`.
 
 ## 🐦 Canary PR releases
 
-Apify MCP is split across two repositories: this one for core MCP logic and the private `apify-mcp-server-internal` for the hosted server.
+Apify MCP is split across two repositories: this repository for core MCP logic and the private `apify-mcp-server-internal` for the hosted server.
 Changes must be synchronized between both.
 
 To create a canary release, add the `beta` tag to your PR branch.
@@ -442,62 +522,11 @@ This publishes the package to [pkg.pr.new](https://pkg.pr.new/) for staging and
 See [the workflow file](.github/workflows/pre_release.yaml) for details.
 
 ## 🐋 Docker Hub integration
-The Apify MCP Server is also available on [Docker Hub](https://hub.docker.com/mcp/server/apify-mcp-server/overview), registered via the [mcp-registry](https://github.com/docker/mcp-registry) repository. The entry in `servers/apify-mcp-server/server.yaml` should be deployed automatically by the Docker Hub MCP registry (deployment frequency is unknown). **Before making major changes to the `stdio` server version, be sure to test it locally to ensure the Docker build passes.** To test, change the `source.branch` to your PR branch and run `task build -- apify-mcp-server`. For more details, see [CONTRIBUTING.md](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md).
-
-# 🐛 Troubleshooting (local MCP server)
-
-- Make sure you have `node` (v20 or higher) installed by running `node -v`.
-- Make sure the `APIFY_TOKEN` environment variable is set.
-- Always use the latest version of the MCP server by using `@apify/actors-mcp-server@latest`.
-
-### Common issues
-
-#### "Unable to connect to extension server", "Cannot find module", or tools not loading
-
-This is most commonly caused by a **corrupted npx cache** — often left behind when Claude Desktop restarts the MCP server process mid-download. Fix it by clearing the cache:
-
-```bash
-# macOS / Linux
-rm -rf ~/.npm/_npx
-npx -y @apify/actors-mcp-server@latest
-
-# Windows (PowerShell)
-Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
-npx -y @apify/actors-mcp-server@latest
-```
+The Apify MCP Server is also available on [Docker Hub](https://hub.docker.com/mcp/server/apify-mcp-server/overview), registered via the [mcp-registry](https://github.com/docker/mcp-registry) repository. The entry in `servers/apify-mcp-server/server.yaml` should be deployed automatically by the Docker Hub MCP registry (deployment frequency is unknown). **Before making major changes to the `stdio` server version, test it locally to ensure the Docker build passes.** To test, change the `source.branch` to your PR branch and run `task build -- apify-mcp-server`. For more details, see [CONTRIBUTING.md](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md).
 
-After clearing the cache, restart Claude Desktop.
+# 🐛 Troubleshooting
 
-#### Errors like "File is not defined" or "ReadableStream is not defined"
-
-You are running an **outdated version of Node.js**. The Apify MCP server requires Node.js **v20 or higher**:
-
-```bash
-node -v  # Check your version
-```
-
-If your version is below 20, update Node.js from [nodejs.org](https://nodejs.org).
-
-#### Server works in Claude Desktop chat but not in cowork mode
-
-This is a known issue we are investigating. As a workaround, try using the hosted server at [mcp.apify.com](https://mcp.apify.com) instead of the local stdio server.
-
-### Checking logs
-
-If you encounter issues, check the Claude Desktop logs for error details:
-
-- **macOS**: `~/Library/Logs/Claude/`
-- **Windows**: `%APPDATA%\Claude\logs\`
-- **Linux**: `~/.config/Claude/logs/`
-
-### Debugging the NPM package
-
-To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:
-
-```shell
-export APIFY_TOKEN="your-apify-token"
-npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
-```
+For step-by-step troubleshooting, see the [Claude Desktop integration guide](https://docs.apify.com/platform/integrations/claude-desktop) in the Apify documentation.
 
 ## 💡 Limitations
 
@@ -510,6 +539,12 @@ The Actor input schema is processed to be compatible with most MCP clients while
 - **Enum values and examples** are added to property descriptions to ensure visibility, even if the client doesn't fully support the JSON schema.
 - **Rental Actors** are only available for use with the hosted MCP server at https://mcp.apify.com. When running the server locally via stdio, you can only access Actors that are already added to your local toolset. To dynamically search for and use any Actor from Apify Store—including rental Actors—connect to the hosted endpoint.
 
+# 🔒 Privacy policy
+
+When you use this server, your requests and Actor inputs are sent to the Apify API for execution.
+Data is not shared with third parties beyond what is necessary to run the requested Actors.
+For full details on data collection, usage, sharing, and retention, see [Apify Legal](https://docs.apify.com/legal).
+
 # 🤝 Contributing
 
 We welcome contributions to improve the Apify MCP Server! Here's how you can help:
@@ -530,3 +565,5 @@ For major changes, please open an issue first to discuss your proposal and ensur
 - [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
 - [Webinar: Building and Monetizing MCP Servers on Apify](https://www.youtube.com/watch?v=w3AH3jIrXXo)
 - [How to build and monetize an AI agent on Apify](https://blog.apify.com/how-to-build-an-ai-agent/)
+- [Connect Apify MCP with Claude Desktop](https://docs.apify.com/platform/integrations/claude-desktop)
+- [Connect Apify MCP with ChatGPT](https://docs.apify.com/platform/integrations/chatgpt)

package/dist/mcp/server.d.ts

@@ -128,16 +128,10 @@ export declare class ActorsMcpServer {
     private setupTaskHandlers;
     private setupToolHandlers;
     /**
-     * Finalizes and tracks telemetry for a tool call.
-     * Calculates execution time, sets final status, and sends the telemetry event.
-     *
-     * @param telemetryData - Telemetry data to finalize and track (null if telemetry is disabled)
-     * @param userId - Apify user ID (string or null if not available)
-     * @param startTime - Timestamp when the tool call started
-     * @param toolStatus - Final status of the tool call
-     * @param callDiagnostics - Telemetry fields: always includes actor_name/actor_id when available; failure-specific fields only on non-success
+     * Logs tool call completion at INFO level and tracks telemetry.
+     * Computes duration once so both the log line and telemetry event use the same value.
      */
-    private finalizeAndTrackTelemetry;
+    private logToolCallAndTelemetry;
     /**
      * Executes a tool asynchronously for a long-running task and updates task status.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}
+{"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;IAqB1B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyC3B;;QAEI;IACJ,OAAO,CAAC,iBAAiB;IAuFzB,OAAO,CAAC,iBAAiB;IAubzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAiC/B;;;;;;;;;;;OAWG;YAEW,wBAAwB;YA2OxB,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"}

package/dist/mcp/server.js

@@ -20,7 +20,7 @@ import { getActorsAsTools, getCategoryTools, getDefaultTools } from '../tools/in
 import { openaiActorExecutor } from '../tools/openai/actor_executor.js';
 import { decodeDotPropertyNames, legacyToolNameToNew } from '../tools/utils.js';
 import { getHttpStatusCode, logHttpError } from '../utils/logging.js';
-import { buildMCPResponse } from '../utils/mcp.js';
+import { buildMCPResponse, getToolCallErrorUserText } from '../utils/mcp.js';
 import { buildPaymentRequiredResponse } from '../utils/payment_errors.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
@@ -607,11 +607,10 @@ export class ActorsMcpServer {
                 throw new Error('MCP Session ID is required for tool calls');
             }
             const startTime = Date.now();
-            let telemetryData;
-            let userId;
             let toolStatus = TOOL_STATUS.SUCCEEDED;
             let callDiagnostics = {};
             let shouldTrackTelemetry = true;
+            let resolvedToolName = name;
             const failInvalidParams = async (message, details, logFields) => {
                 toolStatus = TOOL_STATUS.SOFT_FAIL;
                 callDiagnostics = details;
@@ -628,9 +627,9 @@ export class ActorsMcpServer {
                 await this.server.sendLoggingMessage({ level: 'error', data: message });
                 throw new McpError(ErrorCode.InvalidParams, message);
             };
-            // Initialize telemetry with raw tool name — may be overwritten below once the tool is resolved.
+            // Initialize telemetry with raw tool name — updated below once the tool is resolved.
             // This ensures telemetry is available even for early failures (missing token, tool not found).
-            ({ telemetryData, userId } = await this.prepareTelemetryData(name, mcpSessionId, apifyToken));
+            const { telemetryData, userId } = await this.prepareTelemetryData(name, mcpSessionId, apifyToken);
             // actorName/actorId are declared here so they're available in the catch block for telemetry.
             // Set after tool resolution (inside the try block).
             let actorName;
@@ -662,8 +661,11 @@ export class ActorsMcpServer {
                     });
                 }
                 const tool = toolEntry;
-                // Re-initialize telemetry with the resolved tool (uses actorFullName for actor tools).
-                ({ telemetryData, userId } = await this.prepareTelemetryData(getToolFullName(tool), mcpSessionId, apifyToken));
+                resolvedToolName = getToolFullName(tool);
+                // Update telemetry tool name now that we resolved the tool (uses actorFullName for actor tools).
+                if (telemetryData) {
+                    telemetryData.tool_name = resolvedToolName;
+                }
                 // Extract actor name/id for telemetry — available even when validation fails later.
                 actorName = extractActorName(tool, args);
                 actorId = extractActorId(tool);
@@ -682,8 +684,8 @@ export class ActorsMcpServer {
                 // since validation expects the original, non-encoded property names.
                 args = decodeDotPropertyNames(args);
                 // Centralize all payment processing: validate, strip payment fields, create client.
-                // Must run before ajv validation so toolArgs doesn't contain provider-specific fields.
-                const { toolArgs, logSafeArgs, apifyClient, paymentRequiredResult } = prepareToolCallContext({
+                // Must run before AJV validation so toolArgsWithoutPayment doesn't contain provider-specific fields.
+                const { toolArgsWithoutPayment: toolArgs, toolArgsRedacted: logSafeArgs, apifyClient, paymentRequiredResult } = prepareToolCallContext({
                     provider: this.options.paymentProvider,
                     tool,
                     args: args,
@@ -706,7 +708,7 @@ export class ActorsMcpServer {
                         ...buildActorFields(actorName, actorId),
                     });
                 }
-                // Check if tool call is a long running task and the tool supports that
+                // Check if tool call is a long-running task and the tool supports that
                 // Cast to allowed task mode types ('optional' | 'required') for type-safe includes() check
                 const taskSupport = (_d = tool.execution) === null || _d === void 0 ? void 0 : _d.taskSupport;
                 if (request.params.task && !ALLOWED_TASK_TOOL_EXECUTION_MODES.includes(taskSupport)) {
@@ -764,7 +766,7 @@ export class ActorsMcpServer {
                         ? createProgressTracker(progressToken, extra.sendNotification)
                         : null;
                     try {
-                        log.info('Calling internal tool', { name: tool.name, mcpSessionId, input: logSafeArgs });
+                        log.info('Calling internal tool', { toolName: tool.name, mcpSessionId, input: logSafeArgs });
                         const res = await tool.call({
                             args: toolArgs,
                             extra,
@@ -818,8 +820,9 @@ export class ActorsMcpServer {
                             }
                         }
                         log.info('Calling Actor-MCP', {
+                            toolName: tool.name,
+                            actorMcpToolName: tool.originToolName,
                             actorId: tool.actorId,
-                            toolName: tool.originToolName,
                             mcpSessionId,
                             input: logSafeArgs,
                         });
@@ -867,7 +870,7 @@ export class ActorsMcpServer {
                 if (tool.type === 'actor') {
                     const progressTracker = createProgressTracker(progressToken, extra.sendNotification);
                     try {
-                        log.info('Calling Actor', { actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
+                        log.info('Calling Actor', { toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
                         const executorResult = await this.actorExecutor.executeActorTool({
                             actorFullName: tool.actorFullName,
                             input: toolArgs,
@@ -936,16 +939,23 @@ export class ActorsMcpServer {
                     validationMissingProperty: callDiagnostics.validation_missing_property,
                     validationAdditionalProperty: callDiagnostics.validation_additional_property,
                 });
-                const errorMessage = (error instanceof Error) ? error.message : 'Unknown error';
                 return buildMCPResponse({
-                    texts: [`Error calling tool "${name}": ${errorMessage}.  Please verify the tool name, input parameters, and ensure all required resources are available.`],
+                    texts: [getToolCallErrorUserText(name, error)],
                     isError: true,
                     telemetry: { toolStatus },
                 });
             }
             finally {
                 if (shouldTrackTelemetry) {
-                    this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus, callDiagnostics);
+                    this.logToolCallAndTelemetry({
+                        toolName: resolvedToolName,
+                        mcpSessionId,
+                        toolStatus,
+                        startTime,
+                        telemetryData,
+                        userId,
+                        callDiagnostics,
+                    });
                 }
             }
             const availableTools = this.listToolNames();
@@ -963,28 +973,28 @@ export class ActorsMcpServer {
         });
     }
     /**
-     * Finalizes and tracks telemetry for a tool call.
-     * Calculates execution time, sets final status, and sends the telemetry event.
-     *
-     * @param telemetryData - Telemetry data to finalize and track (null if telemetry is disabled)
-     * @param userId - Apify user ID (string or null if not available)
-     * @param startTime - Timestamp when the tool call started
-     * @param toolStatus - Final status of the tool call
-     * @param callDiagnostics - Telemetry fields: always includes actor_name/actor_id when available; failure-specific fields only on non-success
+     * Logs tool call completion at INFO level and tracks telemetry.
+     * Computes duration once so both the log line and telemetry event use the same value.
      */
-    finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus, callDiagnostics) {
-        if (!telemetryData) {
-            return;
+    logToolCallAndTelemetry(params) {
+        const durationMs = Date.now() - params.startTime;
+        log.info('Tool call completed', {
+            toolName: params.toolName,
+            mcpSessionId: params.mcpSessionId,
+            toolStatus: params.toolStatus,
+            durationMs,
+            ...(params.taskId !== undefined && { taskId: params.taskId }),
+        });
+        if (params.telemetryData) {
+            const finalizedTelemetryData = {
+                ...params.telemetryData,
+                tool_status: params.toolStatus,
+                tool_exec_time_ms: durationMs,
+                // Always include actor_name/actor_id; failure-specific fields are only present when callDiagnostics has them.
+                ...params.callDiagnostics,
+            };
+            trackToolCall(params.userId, this.telemetryEnv, finalizedTelemetryData);
         }
-        const execTime = Date.now() - startTime;
-        const finalizedTelemetryData = {
-            ...telemetryData,
-            tool_status: toolStatus,
-            tool_exec_time_ms: execTime,
-            // Always include actor_name/actor_id; failure-specific fields are only present when callDiagnostics has them.
-            ...callDiagnostics,
-        };
-        trackToolCall(userId, this.telemetryEnv, finalizedTelemetryData);
     }
     // TODO: this function quite duplicates the main tool call login the CallToolRequestSchema handler, we should refactor
     /**
@@ -1014,6 +1024,18 @@ export class ActorsMcpServer {
         // Prepare telemetry before try-catch so it's accessible to both paths.
         // This avoids re-fetching user data in the error handler.
         const { telemetryData, userId } = await this.prepareTelemetryData(getToolFullName(tool), mcpSessionId, apifyToken);
+        const finishTaskTracking = (status, diagnostics) => {
+            this.logToolCallAndTelemetry({
+                toolName: tool.name,
+                mcpSessionId,
+                toolStatus: status,
+                startTime,
+                taskId,
+                telemetryData,
+                userId,
+                callDiagnostics: diagnostics,
+            });
+        };
         try {
             // Check if task was already cancelled before we start execution.
             // Critical: if a client cancels the task immediately after creation (race condition),
@@ -1024,7 +1046,7 @@ export class ActorsMcpServer {
                     taskId,
                     mcpSessionId,
                 });
-                this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, TOOL_STATUS.ABORTED, {
+                finishTaskTracking(TOOL_STATUS.ABORTED, {
                     ...buildActorFields(actorName, actorId),
                 });
                 return;
@@ -1056,7 +1078,7 @@ export class ActorsMcpServer {
             if (toolStatus === TOOL_STATUS.SUCCEEDED && tool.type === 'internal') {
                 const progressTracker = createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
                 try {
-                    log.info('Calling internal tool for task', { taskId, name: tool.name, mcpSessionId, input: logSafeArgs });
+                    log.info('Calling internal tool for task', { taskId, toolName: tool.name, mcpSessionId, input: logSafeArgs });
                     const res = await tool.call({
                         args: toolArgs,
                         extra,
@@ -1083,7 +1105,7 @@ export class ActorsMcpServer {
             if (toolStatus === TOOL_STATUS.SUCCEEDED && tool.type === 'actor') {
                 const progressTracker = createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
                 try {
-                    log.info('Calling Actor for task', { taskId, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
+                    log.info('Calling Actor for task', { taskId, toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
                     const executorResult = await this.actorExecutor.executeActorTool({
                         actorFullName: tool.actorFullName,
                         input: toolArgs,
@@ -1115,7 +1137,7 @@ export class ActorsMcpServer {
                     taskId,
                     mcpSessionId,
                 });
-                this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus);
+                finishTaskTracking(toolStatus);
                 return;
             }
             // Store the result in the task store
@@ -1125,7 +1147,7 @@ export class ActorsMcpServer {
             });
             await this.taskStore.storeTaskResult(taskId, 'completed', result, mcpSessionId);
             log.debug('Task completed successfully', { taskId, toolName: tool.name, mcpSessionId });
-            this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus, callDiagnostics);
+            finishTaskTracking(toolStatus, callDiagnostics);
         }
         catch (error) {
             // Handle 402 Payment Required — return structured x402 result so clients can auto-pay
@@ -1133,7 +1155,7 @@ export class ActorsMcpServer {
             if (httpStatus === HTTP_PAYMENT_REQUIRED) {
                 logHttpError(error, 'Payment required while calling tool (task mode)', { toolName: tool.name });
                 await this.taskStore.storeTaskResult(taskId, 'completed', buildPaymentRequiredResponse(error), mcpSessionId);
-                this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, TOOL_STATUS.SOFT_FAIL, {
+                finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
                     failure_category: FAILURE_CATEGORY.INVALID_INPUT,
                     failure_http_status: 402,
                     ...buildActorFields(actorName, actorId),
@@ -1158,7 +1180,7 @@ export class ActorsMcpServer {
                 actorName: callDiagnostics.actor_name,
                 error,
             });
-            const errorMessage = (error instanceof Error) ? error.message : 'Unknown error';
+            const userText = getToolCallErrorUserText(tool.name, error);
             // Check if task was cancelled before storing result
             // TODO: In future, we should actually stop execution via AbortController,
             // but coordinating cancellation across distributed nodes would be complex
@@ -1167,23 +1189,22 @@ export class ActorsMcpServer {
                     taskId,
                     mcpSessionId,
                 });
-                this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus, callDiagnostics);
+                finishTaskTracking(toolStatus, callDiagnostics);
                 return;
             }
             log.debug('[executeToolAndUpdateTask] Storing failed result', {
                 taskId,
                 mcpSessionId,
-                error: errorMessage,
             });
             await this.taskStore.storeTaskResult(taskId, 'failed', {
                 content: [{
                         type: 'text',
-                        text: `Error calling tool: ${errorMessage}. Please verify the tool name, input parameters, and ensure all required resources are available.`,
+                        text: userText,
                     }],
                 isError: true,
                 internalToolStatus: toolStatus,
             }, mcpSessionId);
-            this.finalizeAndTrackTelemetry(telemetryData, userId, startTime, toolStatus, callDiagnostics);
+            finishTaskTracking(toolStatus, callDiagnostics);
         }
     }
     /*