feat: segment telemetry

README.md

@@ -34,6 +34,7 @@ The Apify Model Context Protocol (MCP) server at [**mcp.apify.com**](https://mcp
 - [🤖 MCP clients and examples](#-mcp-clients-and-examples)
 - [🪄 Try Apify MCP instantly](#-try-apify-mcp-instantly)
 - [🛠️ Tools, resources, and prompts](#-tools-resources-and-prompts)
+- [📊 Telemetry](#telemetry)
 - [🐛 Troubleshooting (local MCP server)](#-troubleshooting-local-mcp-server)
 - [⚙️ Development](#-development)
 - [🤝 Contributing](#-contributing)
@@ -266,13 +267,32 @@ The server provides a set of predefined example prompts to help you get started
 
 The server does not yet provide any resources.
 
-### Debugging the NPM package
+## 📡 Telemetry
 
-To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:
+The Apify MCP Server collects telemetry data about tool calls to help Apify understand usage patterns and improve the service.
+By default, telemetry is **enabled** for all tool calls.
 
-```shell
-export APIFY_TOKEN="your-apify-token"
-npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
+### Opting out of telemetry
+
+You can opt out of telemetry by setting the `--telemetry-enabled` CLI flag to `false` or the `TELEMETRY_ENABLED` environment variable to `false`.
+CLI flags take precedence over environment variables.
+
+#### Examples
+
+**For the remote server (mcp.apify.com)**:
+```text
+# Disable via URL parameter
+https://mcp.apify.com?telemetry-enabled=false
+```
+
+**For the local stdio server**:
+```bash
+# Disable via CLI flag
+npx @apify/actors-mcp-server --telemetry-enabled=false
+
+# Or set environment variable
+export TELEMETRY_ENABLED=false
+npx @apify/actors-mcp-server
 ```
 
 # ⚙️ Development
@@ -333,6 +353,15 @@ The Apify MCP Server is also available on [Docker Hub](https://hub.docker.com/mc
 - 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`.
 
+### 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
+```
+
 ## 💡 Limitations
 
 The Actor input schema is processed to be compatible with most MCP clients while adhering to [JSON Schema](https://json-schema.org/) standards. The processing includes:

package.json

@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "LICENSE",
+    "package.json",
     "server.json",
     "manifest.json"
   ],
@@ -42,6 +43,7 @@
     "@apify/datastructures": "^2.0.3",
     "@apify/log": "^2.5.16",
     "@modelcontextprotocol/sdk": "^1.18.1",
+    "@segment/analytics-node": "^2.3.0",
     "@types/cheerio": "^0.22.35",
     "@types/turndown": "^5.0.5",
     "ajv": "^8.17.1",

src/actor/server.ts

@@ -13,7 +13,9 @@ import express from 'express';
 import log from '@apify/log';
 
 import { ApifyClient } from '../apify-client.js';
+import { type TelemetryEnv } from '../const.js';
 import { ActorsMcpServer } from '../mcp/server.js';
+import { getTelemetryEnv } from '../telemetry.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
 
@@ -78,7 +80,19 @@ export function createExpressApp(
                 rt: Routes.SSE,
                 tr: TransportType.SSE,
             });
-            const mcpServer = new ActorsMcpServer({ setupSigintHandler: false });
+            // Extract telemetry query parameters
+            const urlParams = new URL(req.url, `http://${req.headers.host}`).searchParams;
+            const telemetryEnabledParam = urlParams.get('telemetry-enabled');
+            const telemetryEnvParam = urlParams.get('telemetry-env');
+            const telemetryEnabled = telemetryEnabledParam !== 'false'; // Default to true
+            const telemetryEnv: TelemetryEnv = getTelemetryEnv(telemetryEnvParam);
+
+            const mcpServer = new ActorsMcpServer({
+                setupSigintHandler: false,
+                transportType: 'sse',
+                telemetryEnabled,
+                telemetryEnv,
+            });
             const transport = new SSEServerTransport(Routes.MESSAGE, res);
 
             // Load MCP server tools
@@ -157,12 +171,25 @@ export function createExpressApp(
             // Reuse existing transport
                 transport = transports[sessionId];
             } else if (!sessionId && isInitializeRequest(req.body)) {
-            // New initialization request - use JSON response mode
+            // New initialization request
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
                     enableJsonResponse: false, // Use SSE response mode
                 });
-                const mcpServer = new ActorsMcpServer({ setupSigintHandler: false, initializeRequestData: req.body as InitializeRequest });
+                // Extract telemetry query parameters
+                const urlParams = new URL(req.url, `http://${req.headers.host}`).searchParams;
+                const telemetryEnabledParam = urlParams.get('telemetry-enabled');
+                const telemetryEnvParam = urlParams.get('telemetry-env');
+                const telemetryEnabled = telemetryEnabledParam !== 'false'; // Default to true
+                const telemetryEnv: TelemetryEnv = getTelemetryEnv(telemetryEnvParam);
+
+                const mcpServer = new ActorsMcpServer({
+                    setupSigintHandler: false,
+                    initializeRequestData: req.body as InitializeRequest,
+                    transportType: 'http',
+                    telemetryEnabled,
+                    telemetryEnv,
+                });
 
                 // Load MCP server tools
                 const apifyToken = process.env.APIFY_TOKEN as string;

src/const.ts

@@ -104,3 +104,13 @@ export const ALGOLIA = {
 export const PROGRESS_NOTIFICATION_INTERVAL_MS = 5_000; // 5 seconds
 
 export const APIFY_STORE_URL = 'https://apify.com';
+
+// Telemetry
+export type TelemetryEnv = 'dev' | 'prod';
+
+export const TELEMETRY_ENV = {
+    DEV: 'dev',
+    PROD: 'prod',
+} as const;
+
+export const DEFAULT_TELEMETRY_ENV: TelemetryEnv = TELEMETRY_ENV.PROD;