Merge branch 'master' into segment-telemetry

Author: jirispilka

CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.6](https://github.com/apify/apify-mcp-server/releases/tag/v0.5.6) (2025-11-19)
+
+### 🚀 Features
+
+- Add tool annotations ([#333](https://github.com/apify/apify-mcp-server/pull/333)) ([149cbbc](https://github.com/apify/apify-mcp-server/commit/149cbbc7f5ee1db6c4bed68b2beead4197e990b3)) by [@jirispilka](https://github.com/jirispilka), closes [#327](https://github.com/apify/apify-mcp-server/issues/327)
+- Improve error handling (required for claude connector) ([#331](https://github.com/apify/apify-mcp-server/pull/331)) ([005db2a](https://github.com/apify/apify-mcp-server/commit/005db2a3af24595e67d9548597ca09302be0f9fa)) by [@jirispilka](https://github.com/jirispilka)
+
+
+## [0.5.5](https://github.com/apify/apify-mcp-server/releases/tag/v0.5.5) (2025-11-14)
+
+### 🚀 Features
+
+- Refactor(logging): centralize HTTP error logging  ([#336](https://github.com/apify/apify-mcp-server/pull/336)) ([7b0a52d](https://github.com/apify/apify-mcp-server/commit/7b0a52d1e3baeb732747b1cbf58cb70ad1a135a7)) by [@jirispilka](https://github.com/jirispilka)
+
+
+## [0.5.2](https://github.com/apify/apify-mcp-server/releases/tag/v0.5.2) (2025-11-12)
+
+### 🚀 Features
+
+- Update search-actors tool ([#321](https://github.com/apify/apify-mcp-server/pull/321)) ([602abc5](https://github.com/apify/apify-mcp-server/commit/602abc55bff1f59e937d8e24acc8d7aad64852c2)) by [@jirispilka](https://github.com/jirispilka)
+
+### 🐛 Bug Fixes
+
+- Update readme, add image with clients ([#326](https://github.com/apify/apify-mcp-server/pull/326)) ([da560ab](https://github.com/apify/apify-mcp-server/commit/da560abcbd8b7cb2553032899b8cc963357495e5)) by [@jirispilka](https://github.com/jirispilka)
+- Deduplicate error logs, use info for 404/400 errors, fix ajv validate when it contains $ref ([#335](https://github.com/apify/apify-mcp-server/pull/335)) ([0ebbf50](https://github.com/apify/apify-mcp-server/commit/0ebbf5069a38e4168c5b031764136c66db4f2e18)) by [@jirispilka](https://github.com/jirispilka)
+
+
 ## [0.5.1](https://github.com/apify/apify-mcp-server/releases/tag/v0.5.1) (2025-10-27)
 
 ### 🚀 Features

README.md

@@ -179,6 +179,14 @@ Here is an overview list of all the tools provided by the Apify MCP Server.
 
 > The `get-actor-output` tool is automatically included with any Actor-related tool, such as `call-actor`, `add-actor`, or any specific Actor tool like `apify-slash-rag-web-browser`. When you call an Actor - either through the `call-actor` tool or directly via an Actor tool (e.g., `apify-slash-rag-web-browser`) - you receive a preview of the output. The preview depends on the Actor's output format and length; for some Actors and runs, it may include the entire output, while for others, only a limited version is returned to avoid overwhelming the LLM. To retrieve the full output of an Actor run, use the `get-actor-output` tool (supports limit, offset, and field filtering) with the `datasetId` provided by the Actor call.
 
+### Tool annotations
+
+All tools include metadata annotations to help MCP clients and LLMs understand tool behavior:
+
+- **`title`**: Short display name for the tool (e.g., "Search Actors", "Call Actor", "apify/rag-web-browser")
+- **`readOnlyHint`**: `true` for tools that only read data without modifying state (e.g., `get-dataset`, `fetch-actor-details`)
+- **`openWorldHint`**: `true` for tools that access external resources outside the Apify platform (e.g., `call-actor` executes external Actors, `get-html-skeleton` scrapes external websites). Tools that interact only with the Apify platform (like `search-actors` or `fetch-apify-docs`) do not have this hint.
+
 ### Tools configuration
 
 The `tools` configuration parameter is used to specify loaded tools - either categories or specific tools directly, and Apify Actors. For example, `tools=storage,runs` loads two categories; `tools=add-actor` loads just one tool.

evals/evaluation-utils.ts

@@ -73,7 +73,7 @@ export function filterById(testCases: TestCase[], idPattern: string): TestCase[]
 export async function loadTools(): Promise<ToolBase[]> {
     const apifyClient = new ApifyClient({ token: process.env.APIFY_API_TOKEN || '' });
     const urlTools = await processParamsGetTools('', apifyClient);
-    return urlTools.map((t: ToolEntry) => getToolPublicFieldOnly(t.tool)) as ToolBase[];
+    return urlTools.map((t: ToolEntry) => getToolPublicFieldOnly(t)) as ToolBase[];
 }
 
 export function transformToolsToOpenAIFormat(tools: ToolBase[]): OpenAI.Chat.Completions.ChatCompletionTool[] {

manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.2",
   "name": "apify-mcp-server",
   "display_name": "Apify MCP server",
-  "version": "0.5.1",
+  "version": "0.5.6",
   "description": "Extract data from any website using thousands of tools from the Apify Store.",
   "long_description": "Apify is the world's largest marketplace of tools for web scraping, data extraction, and web automation. You can extract structured data from social media, e-commerce, search engines, maps, travel sites, or any other website.",
   "keywords": [

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@apify/actors-mcp-server",
-  "version": "0.5.1",
+  "version": "0.5.6",
   "type": "module",
   "description": "Apify MCP Server",
   "mcpName": "com.apify/apify-mcp-server",

package.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/apify/apify-mcp-server",
     "source": "github"
   },
-  "version": "0.5.1",
+  "version": "0.5.6",
   "remotes": [
     {
       "type": "streamable-http",

server.json

@@ -26,7 +26,14 @@ export function createExpressApp(
     const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
 
     function respondWithError(res: Response, error: unknown, logMessage: string, statusCode = 500) {
-        log.error('Error in request', { logMessage, error });
+        if (statusCode >= 500) {
+            // Server errors (>= 500) - log as exception
+            log.exception(error instanceof Error ? error : new Error(String(error)), 'Error in request', { logMessage, statusCode });
+        } else {
+            // Client errors (< 500) - log as softFail without stack trace
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            log.softFail('Error in request', { logMessage, error: errorMessage, statusCode });
+        }
         if (!res.headersSent) {
             res.status(statusCode).json({
                 jsonrpc: '2.0',
@@ -110,7 +117,7 @@ export function createExpressApp(
             });
             const sessionId = new URL(req.url, `http://${req.headers.host}`).searchParams.get('sessionId');
             if (!sessionId) {
-                log.error('No session ID provided in POST request');
+                log.softFail('No session ID provided in POST request', { statusCode: 400 });
                 res.status(400).json({
                     jsonrpc: '2.0',
                     error: {
@@ -125,7 +132,7 @@ export function createExpressApp(
             if (transport) {
                 await transport.handlePostMessage(req, res);
             } else {
-                log.error('Server is not connected to the client.');
+                log.softFail('Server is not connected to the client.', { statusCode: 400 });
                 res.status(400).json({
                     jsonrpc: '2.0',
                     error: {
@@ -232,7 +239,7 @@ export function createExpressApp(
             return;
         }
 
-        log.error('Session not found', { sessionId });
+        log.softFail('Session not found', { sessionId, statusCode: 400 });
         res.status(400).send('Bad Request: Session not found').end();
     });
 

src/actor/server.ts

@@ -5,6 +5,7 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import log from '@apify/log';
 
 import { TimeoutError } from '../errors.js';
+import { logHttpError } from '../utils/logging.js';
 import { ACTORIZED_MCP_CONNECTION_TIMEOUT_MSEC } from './const.js';
 import { getMCPServerID } from './utils.js';
 
@@ -40,8 +41,7 @@ export async function connectMCPClient(
             log.warning('Connection to MCP server using SSE transport timed out', { url });
             return null;
         }
-
-        log.error('Failed to connect to MCP server using SSE transport', { cause: error });
+        logHttpError(error, 'Failed to connect to MCP server using SSE transport', { url, cause: error });
         throw error;
     }
 }

src/mcp/client.ts

@@ -40,6 +40,7 @@ import { callActorGetDataset, defaultTools, getActorsAsTools, toolCategories } f
 import { decodeDotPropertyNames } from '../tools/utils.js';
 import type { ToolEntry } from '../types.js';
 import { buildActorResponseContent } from '../utils/actor-response.js';
+import { logHttpError } from '../utils/logging.js';
 import { buildMCPResponse } from '../utils/mcp.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { cloneToolEntry, getToolPublicFieldOnly } from '../utils/tools.js';
@@ -210,7 +211,7 @@ export class ActorsMcpServer {
     * Loads missing toolNames from a provided list of tool names.
     * Skips toolNames that are already loaded and loads only the missing ones.
     * @param toolNames - Array of tool names to ensure are loaded
-    * @param apifyToken - Apify API token for authentication
+    * @param apifyClient
     */
     public async loadToolsByName(toolNames: string[], apifyClient: ApifyClient) {
         const loadedTools = this.listAllToolNames();
@@ -245,7 +246,7 @@ export class ActorsMcpServer {
      * Load actors as tools, upsert them to the server, and return the tool entries.
      * This is a public method that wraps getActorsAsTools and handles the upsert operation.
      * @param actorIdsOrNames - Array of actor IDs or names to load as tools
-     * @param apifyToken - Apify API token for authentication
+     * @param apifyClient
      * @returns Promise<ToolEntry[]> - Array of loaded tool entries
      */
     public async loadActorsAsTools(actorIdsOrNames: string[], apifyClient: ApifyClient): Promise<ToolEntry[]> {
@@ -343,8 +344,8 @@ export class ActorsMcpServer {
             }
         } else {
             // No skyfire mode and telemetry disabled - store tools as-is
-            for (const wrap of tools) {
-                this.tools.set(wrap.name, wrap);
+            for (const tool of tools) {
+                this.tools.set(tool.name, tool);
             }
         }
         if (shouldNotifyToolsChangedHandler) this.notifyToolsChangedHandler();
@@ -532,8 +533,10 @@ export class ActorsMcpServer {
 
             // Validate token
             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);
+                const msg = `APIFY_TOKEN is required but was not provided.
+Please set the APIFY_TOKEN environment variable or pass it as a parameter in the request body.
+You can obtain your Apify token from https://console.apify.com/account/integrations.`;
+                log.softFail(msg, { statusCode: 400 });
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
                     ErrorCode.InvalidParams,
@@ -556,17 +559,21 @@ export class ActorsMcpServer {
             const tool = Array.from(this.tools.values())
                 .find((t) => t.name === name || (t.type === 'actor' && t.actorFullName === name));
             if (!tool) {
-                const msg = `Tool ${name} not found. Available tools: ${this.listToolNames().join(', ')}`;
-                log.error(msg);
+                const availableTools = this.listToolNames();
+                const msg = `Tool "${name}" was not found.
+Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
+Please verify the tool name is correct. You can list all available tools using the tools/list request.`;
+                log.softFail(msg, { statusCode: 404 });
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
                     ErrorCode.InvalidParams,
                     msg,
                 );
             }
             if (!args) {
-                const msg = `Missing arguments for tool ${name}`;
-                log.error(msg);
+                const msg = `Missing arguments for tool "${name}".
+Please provide the required arguments for this tool. Check the tool's input schema using ${HelperTools.ACTOR_GET_DETAILS} tool to see what parameters are required.`;
+                log.softFail(msg, { statusCode: 400 });
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
                     ErrorCode.InvalidParams,
@@ -578,8 +585,12 @@ export class ActorsMcpServer {
             args = decodeDotPropertyNames(args);
             log.debug('Validate arguments for tool', { toolName: tool.name, input: args });
             if (!tool.ajvValidate(args)) {
-                const msg = `Invalid arguments for tool ${tool.name}: args: ${JSON.stringify(args)} error: ${JSON.stringify(tool.ajvValidate.errors)}`;
-                log.error(msg);
+                const errors = tool?.ajvValidate.errors || [];
+                const errorMessages = errors.map((e: { message?: string; instancePath?: string }) => `${e.instancePath || 'root'}: ${e.message || 'validation error'}`).join('; ');
+                const msg = `Invalid arguments for tool "${tool.name}".
+Validation errors: ${errorMessages}.
+Please check the tool's input schema using ${HelperTools.ACTOR_GET_DETAILS} tool and ensure all required parameters are provided with correct types and values.`;
+                log.softFail(msg, { statusCode: 400 });
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
                     ErrorCode.InvalidParams,
@@ -653,14 +664,11 @@ export class ActorsMcpServer {
                     try {
                         client = await connectMCPClient(tool.serverUrl, apifyToken);
                         if (!client) {
-                            const msg = `Failed to connect to MCP server ${tool.serverUrl}`;
-                            log.error(msg);
+                            const msg = `Failed to connect to MCP server at "${tool.serverUrl}".
+Please verify the server URL is correct and accessible, and ensure you have a valid Apify token with appropriate permissions.`;
+                            log.softFail(msg, { statusCode: 408 }); // 408 Request Timeout
                             await this.server.sendLoggingMessage({ level: 'error', data: msg });
-                            return {
-                                content: [
-                                    { type: 'text', text: msg },
-                                ],
-                            };
+                            return buildMCPResponse([msg], true);
                         }
 
                         // Only set up notification handlers if progressToken is provided by the client
@@ -701,12 +709,7 @@ export class ActorsMcpServer {
                     if (this.options.skyfireMode
                         && args['skyfire-pay-id'] === undefined
                     ) {
-                        return {
-                            content: [{
-                                type: 'text',
-                                text: SKYFIRE_TOOL_INSTRUCTIONS,
-                            }],
-                        };
+                        return buildMCPResponse([SKYFIRE_TOOL_INSTRUCTIONS]);
                     }
 
                     // Create progress tracker if progressToken is available
@@ -748,15 +751,19 @@ export class ActorsMcpServer {
                     }
                 }
             } catch (error) {
-                log.error('Error occurred while calling tool', { toolName: name, error });
+                logHttpError(error, 'Error occurred while calling tool', { toolName: name });
                 const errorMessage = (error instanceof Error) ? error.message : 'Unknown error';
                 return buildMCPResponse([
-                    `Error calling tool ${name}: ${errorMessage}`,
-                ]);
+                    `Error calling tool "${name}": ${errorMessage}.
+Please verify the tool name, input parameters, and ensure all required resources are available.`,
+                ], true);
             }
 
-            const msg = `Unknown tool: ${name}`;
-            log.error(msg);
+            const availableTools = this.listToolNames();
+            const msg = `Unknown tool type for "${name}".
+Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
+Please verify the tool name and ensure the tool is properly registered.`;
+            log.softFail(msg, { statusCode: 404 });
             await this.server.sendLoggingMessage({
                 level: 'error',
                 data: msg,