@posthog/mcp 0.25.2 → 1.0.0

package/README.md

@@ -8,6 +8,10 @@ SDK usage examples and code snippets live in the official documentation so they
 
 - [MCP analytics docs](https://posthog.com/docs/mcp-analytics)
 
+## Versioning
+
+From 1.0.0, `@posthog/mcp` follows semver for its API and for the events it sends. A minor or patch release doesn't rename or remove a `$mcp_*` event or property, change its type, or change which requests send an event, so saved insights keep working across upgrades. It may add events and properties, and redact more of a captured value. The rules come from the [MCP analytics spec](https://github.com/PostHog/sdk-specs/blob/main/openspec/specs/mcp-analytics/spec.md), section "Event schema stability".
+
 ## Stateless & multi-pod servers
 
 On stateless deployments the SDK mints the `Mcp-Session-Id` response header at `initialize`
@@ -184,9 +188,8 @@ enabled by default. Missing-capability reporting and feedback collection remain
 instrument(server, posthog, { captureModel: false, enableConversationId: false })
 ```
 
-Model capture adds a required `llm_model` argument to compatible tool schemas. Dispatch never
-enforces it, so servers keep working; strict-schema clients see the new field. Set
-`captureModel: false` to leave schemas untouched. Conversation correlation adds an optional
+Model capture adds an optional `llm_model` argument to compatible tool schemas. Strict-schema
+clients see the new field. Set `captureModel: false` to leave schemas untouched. Conversation correlation adds an optional
 `conversation_id` argument and returns a handle in eligible tool results. Clients must echo that
 handle to group later calls; calls without it mint new handles. Set `enableConversationId: false`
 to retain transport-based session grouping and unchanged response content. Custom `PostHogMCP`
@@ -227,7 +230,7 @@ Omit `serverBuild` when the deployment does not provide a reliable value.
 
 `captureModel` is **on** by default. The SDK records the best model id visible to the
 server as `$mcp_llm_model`. Recognized client metadata wins with source `client_metadata`. Otherwise,
-the SDK injects a required `llm_model` parameter and records the answer with source `self_reported`.
+the SDK injects an optional `llm_model` parameter and records the answer with source `self_reported`.
 
 MCP does not standardize or attest model identity. Client metadata and self-report are both
 unverified. Use the value to spot degradation across models, never for billing or access control.

package/dist/extensions/analytics-parameters.d.ts

@@ -18,7 +18,7 @@ export interface AnalyticsInjectableTool {
     [key: string]: unknown;
 }
 /**
- * Adds a required string parameter to a tool's JSON Schema. Called AFTER the MCP
+ * Adds a string parameter to a tool's JSON Schema. Called AFTER the MCP
  * SDK has converted Zod schemas to JSON Schema, so only JSON Schema needs
  * handling.
  *
@@ -30,7 +30,7 @@ export interface AnalyticsInjectableTool {
  * - Tools that already declare the parameter — it is theirs, not ours
  * - Complex schemas (oneOf/allOf/anyOf/$ref) that can't safely gain properties
  */
-export declare function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableTool>(tool: TTool, parameterName: string, description: string, injectionLabel: string, logger?: LoggerFn): TTool;
+export declare function addAnalyticsParameterToTool<TTool extends AnalyticsInjectableTool>(tool: TTool, parameterName: string, description: string, injectionLabel: string, required: boolean, logger?: LoggerFn): TTool;
 export declare function analyticsOwnsParameter(inputSchema: unknown, parameterName: string): boolean;
 export declare function getAnalyticsParameterOwnership(inputSchema: unknown, outputSchema?: unknown): AnalyticsParameterOwnership;
 /**

package/dist/extensions/analytics-parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-parameters.d.ts","sourceRoot":"","sources":["../../src/extensions/analytics-parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAiB7C,MAAM,WAAW,6BAA6B;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,6BAA6B,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAET;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,6BAA6B,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAIT;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,6BAA6B,CAAA;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,SAAS,uBAAuB,EAC/E,IAAI,EAAE,KAAK,EACX,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,QAAc,GACrB,KAAK,CAqDP;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAyB3F;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,OAAO,EACpB,YAAY,CAAC,EAAE,OAAO,GACrB,2BAA2B,CAO7B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,IAAI,CAAC,2BAA2B,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,CAAC,GACtF,OAAO,CAeT"}
+{"version":3,"file":"analytics-parameters.d.ts","sourceRoot":"","sources":["../../src/extensions/analytics-parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAiB7C,MAAM,WAAW,6BAA6B;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,6BAA6B,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAET;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,6BAA6B,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAIT;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,6BAA6B,CAAA;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,SAAS,uBAAuB,EAC/E,IAAI,EAAE,KAAK,EACX,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,OAAO,EACjB,MAAM,GAAE,QAAc,GACrB,KAAK,CAgDP;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAyB3F;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,OAAO,EACpB,YAAY,CAAC,EAAE,OAAO,GACrB,2BAA2B,CAO7B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,IAAI,CAAC,2BAA2B,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,CAAC,GACtF,OAAO,CAeT"}

package/dist/extensions/analytics-parameters.js

@@ -56,7 +56,7 @@ function hasAnalyticsParameter(schema, parameterName) {
 function canInjectAnalyticsParameter(schema, parameterName) {
     return !hasAnalyticsParameter(schema, parameterName) && !schema?.$ref && !schema?.oneOf && !schema?.allOf && !schema?.anyOf;
 }
-function addAnalyticsParameterToTool(tool, parameterName, description, injectionLabel, logger = external_logger_js_namespaceObject.log) {
+function addAnalyticsParameterToTool(tool, parameterName, description, injectionLabel, required, logger = external_logger_js_namespaceObject.log) {
     const modifiedTool = {
         ...tool
     };
@@ -68,8 +68,7 @@ function addAnalyticsParameterToTool(tool, parameterName, description, injection
     }
     if (!modifiedTool.inputSchema) modifiedTool.inputSchema = {
         type: 'object',
-        properties: {},
-        required: []
+        properties: {}
     };
     modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema));
     const inputSchema = modifiedTool.inputSchema;
@@ -79,11 +78,13 @@ function addAnalyticsParameterToTool(tool, parameterName, description, injection
         type: 'string',
         description
     };
-    if (Array.isArray(inputSchema.required)) {
-        if (!inputSchema.required.includes(parameterName)) inputSchema.required.push(parameterName);
-    } else inputSchema.required = [
-        parameterName
-    ];
+    if (required) {
+        const existing = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+        if (!existing.includes(parameterName)) inputSchema.required = [
+            ...existing,
+            parameterName
+        ];
+    }
     return modifiedTool;
 }
 function analyticsOwnsParameter(inputSchema, parameterName) {

package/dist/extensions/analytics-parameters.mjs

@@ -19,7 +19,7 @@ function hasAnalyticsParameter(schema, parameterName) {
 function canInjectAnalyticsParameter(schema, parameterName) {
     return !hasAnalyticsParameter(schema, parameterName) && !schema?.$ref && !schema?.oneOf && !schema?.allOf && !schema?.anyOf;
 }
-function addAnalyticsParameterToTool(tool, parameterName, description, injectionLabel, logger = log) {
+function addAnalyticsParameterToTool(tool, parameterName, description, injectionLabel, required, logger = log) {
     const modifiedTool = {
         ...tool
     };
@@ -31,8 +31,7 @@ function addAnalyticsParameterToTool(tool, parameterName, description, injection
     }
     if (!modifiedTool.inputSchema) modifiedTool.inputSchema = {
         type: 'object',
-        properties: {},
-        required: []
+        properties: {}
     };
     modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema));
     const inputSchema = modifiedTool.inputSchema;
@@ -42,11 +41,13 @@ function addAnalyticsParameterToTool(tool, parameterName, description, injection
         type: 'string',
         description
     };
-    if (Array.isArray(inputSchema.required)) {
-        if (!inputSchema.required.includes(parameterName)) inputSchema.required.push(parameterName);
-    } else inputSchema.required = [
-        parameterName
-    ];
+    if (required) {
+        const existing = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+        if (!existing.includes(parameterName)) inputSchema.required = [
+            ...existing,
+            parameterName
+        ];
+    }
     return modifiedTool;
 }
 function analyticsOwnsParameter(inputSchema, parameterName) {

package/dist/extensions/capture.js

@@ -39,7 +39,7 @@ function captureEvent(server, eventInput, logger, requestAttribution) {
     const sink = data.sink;
     if (!sink) return;
     const sessionInfo = requestAttribution ?? (0, external_session_js_namespaceObject.getSessionInfo)(server, data, eventInput.sessionId);
-    const duration = eventInput.duration || (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : void 0);
+    const duration = eventInput.duration ?? (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : void 0);
     const fullEvent = {
         id: eventInput.id || '',
         sessionId: eventInput.sessionId || data.sessionId,

package/dist/extensions/capture.mjs

@@ -7,7 +7,7 @@ function captureEvent(server, eventInput, logger, requestAttribution) {
     const sink = data.sink;
     if (!sink) return;
     const sessionInfo = requestAttribution ?? getSessionInfo(server, data, eventInput.sessionId);
-    const duration = eventInput.duration || (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : void 0);
+    const duration = eventInput.duration ?? (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : void 0);
     const fullEvent = {
         id: eventInput.id || '',
         sessionId: eventInput.sessionId || data.sessionId,

package/dist/extensions/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const INACTIVITY_TIMEOUT_IN_MINUTES = 30;
-export declare const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"";
+export declare const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = "A few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as \"a customer\". Do not quote the user or include names, emails, or other personal details.";
 export declare const DEFAULT_MODEL_PARAMETER_DESCRIPTION = "The model identifier you are running as, for example \"claude-opus-4-8\" or \"gpt-5.2\". Pass \"unknown\" if you are not certain. Recorded for the server developer's analytics.";
 export declare const DEFAULT_CONVERSATION_ID_DESCRIPTION = "The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.";
 export declare const POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics";
@@ -18,6 +18,7 @@ export declare const PostHogMCPAnalyticsEvent: {
     readonly ResourcesList: '$mcp_resources_list';
     readonly ToolCall: '$mcp_tool_call';
     readonly ToolsList: '$mcp_tools_list';
+    readonly UnknownTool: '$mcp_unknown_tool';
 };
 export type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof typeof PostHogMCPAnalyticsEvent];
 export declare const PostHogMCPAnalyticsProperty: {

package/dist/extensions/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/extensions/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,6BAA6B,KAAK,CAAA;AAE/C,eAAO,MAAM,qCAAqC,onBAA4mB,CAAA;AAE9pB,eAAO,MAAM,mCAAmC,qLAA+K,CAAA;AAE/N,eAAO,MAAM,mCAAmC,oMACmJ,CAAA;AAEnM,eAAO,MAAM,4BAA4B,0BAA0B,CAAA;AAMnE,eAAO,MAAM,oBAAoB,qBAAqB,CAAA;AAItD,eAAO,MAAM,wBAAwB;aACnC,MAAM,EAAE,aAAa;aACrB,SAAS,EAAE,YAAY;aACvB,QAAQ,EAAE,eAAe;IACzB,2DAA2D;aAC3D,QAAQ,EAAE,WAAW;aACrB,UAAU,EAAE,iBAAiB;aAC7B,iBAAiB,EAAE,yBAAyB;aAC5C,SAAS,EAAE,iBAAiB;aAC5B,WAAW,EAAE,mBAAmB;aAChC,YAAY,EAAE,oBAAoB;aAClC,aAAa,EAAE,qBAAqB;aACpC,QAAQ,EAAE,gBAAgB;aAC1B,SAAS,EAAE,iBAAiB;CACpB,CAAA;AAEV,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAA;AAE/G,eAAO,MAAM,2BAA2B;aACtC,UAAU,EAAE,kBAAkB;aAC9B,eAAe,EAAE,wBAAwB;aACzC,aAAa,EAAE,qBAAqB;aACpC,cAAc,EAAE,sBAAsB;aACtC,UAAU,EAAE,kBAAkB;aAC9B,YAAY,EAAE,oBAAoB;aAClC,SAAS,EAAE,iBAAiB;aAC5B,eAAe,EAAE,uBAAuB;aACxC,sBAAsB,EAAE,+BAA+B;aACvD,iBAAiB,EAAE,yBAAyB;aAC5C,4BAA4B,EAAE,qCAAqC;aACnE,eAAe,EAAE,uBAAuB;aACxC,qBAAqB,EAAE,8BAA8B;aACrD,YAAY,EAAE,oBAAoB;aAClC,YAAY,EAAE,oBAAoB;aAClC,SAAS,EAAE,gBAAgB;aAC3B,OAAO,EAAE,eAAe;aACxB,gBAAgB,EAAE,yBAAyB;aAC3C,SAAS,EAAE,iBAAiB;aAC5B,MAAM,EAAE,aAAa;aACrB,YAAY,EAAE,oBAAoB;aAClC,eAAe,EAAE,wBAAwB;aACzC,QAAQ,EAAE,gBAAgB;aAC1B,cAAc,EAAE,uBAAuB;aACvC,UAAU,EAAE,iBAAiB;aAC7B,eAAe,EAAE,uBAAuB;aACxC,YAAY,EAAE,oBAAoB;aAClC,QAAQ,EAAE,eAAe;aACzB,WAAW,EAAE,mBAAmB;aAChC,UAAU,EAAE,kBAAkB;aAC9B,aAAa,EAAE,qBAAqB;aACpC,SAAS,EAAE,aAAa;aACxB,MAAM,EAAE,aAAa;aACrB,YAAY,EAAE,oBAAoB;aAClC,eAAe,EAAE,uBAAuB;aACxC,QAAQ,EAAE,gBAAgB;aAC1B,YAAY,EAAE,oBAAoB;CAC1B,CAAA;AAEV,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/extensions/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,6BAA6B,KAAK,CAAA;AAE/C,eAAO,MAAM,qCAAqC,+NAA6N,CAAA;AAE/Q,eAAO,MAAM,mCAAmC,qLAA+K,CAAA;AAE/N,eAAO,MAAM,mCAAmC,oMACmJ,CAAA;AAEnM,eAAO,MAAM,4BAA4B,0BAA0B,CAAA;AAMnE,eAAO,MAAM,oBAAoB,qBAAqB,CAAA;AAItD,eAAO,MAAM,wBAAwB;aACnC,MAAM,EAAE,aAAa;aACrB,SAAS,EAAE,YAAY;aACvB,QAAQ,EAAE,eAAe;IACzB,2DAA2D;aAC3D,QAAQ,EAAE,WAAW;aACrB,UAAU,EAAE,iBAAiB;aAC7B,iBAAiB,EAAE,yBAAyB;aAC5C,SAAS,EAAE,iBAAiB;aAC5B,WAAW,EAAE,mBAAmB;aAChC,YAAY,EAAE,oBAAoB;aAClC,aAAa,EAAE,qBAAqB;aACpC,QAAQ,EAAE,gBAAgB;aAC1B,SAAS,EAAE,iBAAiB;aAC5B,WAAW,EAAE,mBAAmB;CACxB,CAAA;AAEV,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAA;AAE/G,eAAO,MAAM,2BAA2B;aACtC,UAAU,EAAE,kBAAkB;aAC9B,eAAe,EAAE,wBAAwB;aACzC,aAAa,EAAE,qBAAqB;aACpC,cAAc,EAAE,sBAAsB;aACtC,UAAU,EAAE,kBAAkB;aAC9B,YAAY,EAAE,oBAAoB;aAClC,SAAS,EAAE,iBAAiB;aAC5B,eAAe,EAAE,uBAAuB;aACxC,sBAAsB,EAAE,+BAA+B;aACvD,iBAAiB,EAAE,yBAAyB;aAC5C,4BAA4B,EAAE,qCAAqC;aACnE,eAAe,EAAE,uBAAuB;aACxC,qBAAqB,EAAE,8BAA8B;aACrD,YAAY,EAAE,oBAAoB;aAClC,YAAY,EAAE,oBAAoB;aAClC,SAAS,EAAE,gBAAgB;aAC3B,OAAO,EAAE,eAAe;aACxB,gBAAgB,EAAE,yBAAyB;aAC3C,SAAS,EAAE,iBAAiB;aAC5B,MAAM,EAAE,aAAa;aACrB,YAAY,EAAE,oBAAoB;aAClC,eAAe,EAAE,wBAAwB;aACzC,QAAQ,EAAE,gBAAgB;aAC1B,cAAc,EAAE,uBAAuB;aACvC,UAAU,EAAE,iBAAiB;aAC7B,eAAe,EAAE,uBAAuB;aACxC,YAAY,EAAE,oBAAoB;aAClC,QAAQ,EAAE,eAAe;aACzB,WAAW,EAAE,mBAAmB;aAChC,UAAU,EAAE,kBAAkB;aAC9B,aAAa,EAAE,qBAAqB;aACpC,SAAS,EAAE,aAAa;aACxB,MAAM,EAAE,aAAa;aACrB,YAAY,EAAE,oBAAoB;aAClC,eAAe,EAAE,uBAAuB;aACxC,QAAQ,EAAE,gBAAgB;aAC1B,YAAY,EAAE,oBAAoB;CAC1B,CAAA;AAEV,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA"}

package/dist/extensions/constants.js

@@ -28,7 +28,7 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 const INACTIVITY_TIMEOUT_IN_MINUTES = 30;
-const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = 'Explain in 15-25 words, in third person, why this tool is called and how it supports the user\'s goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer\'s recent orders to investigate a billing issue and help support determine the appropriate resolution."';
+const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = 'A few words on why you are calling this tool, for the server developer\'s analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details.';
 const DEFAULT_MODEL_PARAMETER_DESCRIPTION = 'The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Pass "unknown" if you are not certain. Recorded for the server developer\'s analytics.';
 const DEFAULT_CONVERSATION_ID_DESCRIPTION = "The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.";
 const POSTHOG_MCP_ANALYTICS_SOURCE = 'posthog_mcp_analytics';
@@ -45,7 +45,8 @@ const PostHogMCPAnalyticsEvent = {
     ResourceRead: '$mcp_resource_read',
     ResourcesList: '$mcp_resources_list',
     ToolCall: '$mcp_tool_call',
-    ToolsList: '$mcp_tools_list'
+    ToolsList: '$mcp_tools_list',
+    UnknownTool: '$mcp_unknown_tool'
 };
 const PostHogMCPAnalyticsProperty = {
     ClientName: '$mcp_client_name',

package/dist/extensions/constants.mjs

@@ -1,5 +1,5 @@
 const INACTIVITY_TIMEOUT_IN_MINUTES = 30;
-const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = 'Explain in 15-25 words, in third person, why this tool is called and how it supports the user\'s goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer\'s recent orders to investigate a billing issue and help support determine the appropriate resolution."';
+const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = 'A few words on why you are calling this tool, for the server developer\'s analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details.';
 const DEFAULT_MODEL_PARAMETER_DESCRIPTION = 'The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Pass "unknown" if you are not certain. Recorded for the server developer\'s analytics.';
 const DEFAULT_CONVERSATION_ID_DESCRIPTION = "The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.";
 const POSTHOG_MCP_ANALYTICS_SOURCE = 'posthog_mcp_analytics';
@@ -16,7 +16,8 @@ const PostHogMCPAnalyticsEvent = {
     ResourceRead: '$mcp_resource_read',
     ResourcesList: '$mcp_resources_list',
     ToolCall: '$mcp_tool_call',
-    ToolsList: '$mcp_tools_list'
+    ToolsList: '$mcp_tools_list',
+    UnknownTool: '$mcp_unknown_tool'
 };
 const PostHogMCPAnalyticsProperty = {
     ClientName: '$mcp_client_name',

package/dist/extensions/context-parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-parameters.d.ts","sourceRoot":"","sources":["../../src/extensions/context-parameters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAA+B,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAA;AAExG,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAE7C,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,6BAA6B,CAAA;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,OAAO,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAEjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,SAAS,qBAAqB,EAC3E,IAAI,EAAE,KAAK,EACX,0BAA0B,CAAC,EAAE,MAAM,EACnC,MAAM,GAAE,QAAc,GACrB,KAAK,CAQP;AAED,wBAAgB,0BAA0B,CAAC,KAAK,SAAS,qBAAqB,EAC5E,KAAK,EAAE,KAAK,EAAE,EACd,0BAA0B,CAAC,EAAE,MAAM,EACnC,MAAM,GAAE,QAAc,GACrB,KAAK,EAAE,CAET"}
+{"version":3,"file":"context-parameters.d.ts","sourceRoot":"","sources":["../../src/extensions/context-parameters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAA+B,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAA;AAExG,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAE7C,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,6BAA6B,CAAA;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,OAAO,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAEjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,SAAS,qBAAqB,EAC3E,IAAI,EAAE,KAAK,EACX,0BAA0B,CAAC,EAAE,MAAM,EACnC,MAAM,GAAE,QAAc,GACrB,KAAK,CASP;AAED,wBAAgB,0BAA0B,CAAC,KAAK,SAAS,qBAAqB,EAC5E,KAAK,EAAE,KAAK,EAAE,EACd,0BAA0B,CAAC,EAAE,MAAM,EACnC,MAAM,GAAE,QAAc,GACrB,KAAK,EAAE,CAET"}

package/dist/extensions/context-parameters.js

@@ -43,7 +43,7 @@ function getContextDescription(context) {
     return 'object' == typeof context ? context.description : void 0;
 }
 function addContextParameterToTool(tool, contextDescriptionOverride, logger = external_logger_js_namespaceObject.log) {
-    return (0, external_analytics_parameters_js_namespaceObject.addAnalyticsParameterToTool)(tool, 'context', contextDescriptionOverride || external_constants_js_namespaceObject.DEFAULT_CONTEXT_PARAMETER_DESCRIPTION, 'context', logger);
+    return (0, external_analytics_parameters_js_namespaceObject.addAnalyticsParameterToTool)(tool, 'context', contextDescriptionOverride || external_constants_js_namespaceObject.DEFAULT_CONTEXT_PARAMETER_DESCRIPTION, 'context', true, logger);
 }
 function addContextParameterToTools(tools, contextDescriptionOverride, logger = external_logger_js_namespaceObject.log) {
     return tools.map((tool)=>addContextParameterToTool(tool, contextDescriptionOverride, logger));

package/dist/extensions/context-parameters.mjs

@@ -8,7 +8,7 @@ function getContextDescription(context) {
     return 'object' == typeof context ? context.description : void 0;
 }
 function addContextParameterToTool(tool, contextDescriptionOverride, logger = log) {
-    return addAnalyticsParameterToTool(tool, 'context', contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION, 'context', logger);
+    return addAnalyticsParameterToTool(tool, 'context', contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION, 'context', true, logger);
 }
 function addContextParameterToTools(tools, contextDescriptionOverride, logger = log) {
     return tools.map((tool)=>addContextParameterToTool(tool, contextDescriptionOverride, logger));

package/dist/extensions/event-types.d.ts

@@ -16,6 +16,7 @@ export declare const MCPAnalyticsEventType: {
     readonly mcpResourcesRead: 'mcp:resources/read';
     readonly mcpToolsCall: 'mcp:tools/call';
     readonly mcpToolsList: 'mcp:tools/list';
+    readonly mcpUnknownTool: 'mcp:unknown_tool';
 };
 export type MCPAnalyticsEventType = (typeof MCPAnalyticsEventType)[keyof typeof MCPAnalyticsEventType];
 //# sourceMappingURL=event-types.d.ts.map

package/dist/extensions/event-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../src/extensions/event-types.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;aAChC,MAAM,EAAE,gBAAgB;aACxB,WAAW,EAAE,cAAc;aAC3B,oBAAoB,EAAE,wBAAwB;aAC9C,aAAa,EAAE,gBAAgB;aAC/B,aAAa,EAAE,iBAAiB;aAChC,cAAc,EAAE,kBAAkB;aAClC,gBAAgB,EAAE,oBAAoB;aACtC,gBAAgB,EAAE,oBAAoB;aACtC,YAAY,EAAE,gBAAgB;aAC9B,YAAY,EAAE,gBAAgB;CACtB,CAAA;AAEV,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAA"}
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../src/extensions/event-types.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;aAChC,MAAM,EAAE,gBAAgB;aACxB,WAAW,EAAE,cAAc;aAC3B,oBAAoB,EAAE,wBAAwB;aAC9C,aAAa,EAAE,gBAAgB;aAC/B,aAAa,EAAE,iBAAiB;aAChC,cAAc,EAAE,kBAAkB;aAClC,gBAAgB,EAAE,oBAAoB;aACtC,gBAAgB,EAAE,oBAAoB;aACtC,YAAY,EAAE,gBAAgB;aAC9B,YAAY,EAAE,gBAAgB;aAC9B,cAAc,EAAE,kBAAkB;CAC1B,CAAA;AAEV,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAA"}

package/dist/extensions/event-types.js

@@ -37,7 +37,8 @@ const MCPAnalyticsEventType = {
     mcpResourcesList: 'mcp:resources/list',
     mcpResourcesRead: 'mcp:resources/read',
     mcpToolsCall: 'mcp:tools/call',
-    mcpToolsList: 'mcp:tools/list'
+    mcpToolsList: 'mcp:tools/list',
+    mcpUnknownTool: 'mcp:unknown_tool'
 };
 __webpack_require__.d(__webpack_exports__, {}, {
     MCPAnalyticsEventType: MCPAnalyticsEventType

package/dist/extensions/event-types.mjs

@@ -8,6 +8,7 @@ const MCPAnalyticsEventType = {
     mcpResourcesList: 'mcp:resources/list',
     mcpResourcesRead: 'mcp:resources/read',
     mcpToolsCall: 'mcp:tools/call',
-    mcpToolsList: 'mcp:tools/list'
+    mcpToolsList: 'mcp:tools/list',
+    mcpUnknownTool: 'mcp:unknown_tool'
 };
 export { MCPAnalyticsEventType };

package/dist/extensions/feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/extensions/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EAEtB,cAAc,EAGd,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,EACX,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAI7C,eAAO,MAAM,uBAAuB,EAAG,eAAwB,CAAA;AAoF/D,KAAK,sBAAsB,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,sBAAsB,GAAG,SAAS,CAKpC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,sBAA2B,GAAG,sBAAsB,CA6CtG;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,GAAE,sBAA2B,GACnC,cAAc,CAoBhB;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAElE;AAuCD,uFAAuF;AACvF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,cAAc,GAAG,UAAU,CAqC/E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CAS7D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,EACpC,MAAM,GAAE,QAAc,GACrB,OAAO,CAAC,wBAAwB,CAAC,CAiBnC"}
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/extensions/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EAEtB,cAAc,EAGd,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,EACX,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAK7C,eAAO,MAAM,uBAAuB,EAAG,eAAwB,CAAA;AAoF/D,KAAK,sBAAsB,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,sBAAsB,GAAG,SAAS,CAKpC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,sBAA2B,GAAG,sBAAsB,CAoCtG;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,GAAE,sBAA2B,GACnC,cAAc,CAoBhB;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAElE;AAuCD,uFAAuF;AACvF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,cAAc,GAAG,UAAU,CAqC/E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CAS7D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,EACpC,MAAM,GAAE,QAAc,GACrB,OAAO,CAAC,wBAAwB,CAAC,CAiBnC"}

package/dist/extensions/feedback.js

@@ -40,6 +40,7 @@ __webpack_require__.d(__webpack_exports__, {
 const external_constants_js_namespaceObject = require("./constants.js");
 const external_logger_js_namespaceObject = require("./logger.js");
 const external_mcp_payloads_js_namespaceObject = require("./mcp-payloads.js");
+const external_tools_js_namespaceObject = require("./tools.js");
 const external_truncation_js_namespaceObject = require("./truncation.js");
 const SEND_FEEDBACK_TOOL_NAME = 'send_feedback';
 const FEEDBACK_TYPES = [
@@ -131,11 +132,7 @@ function getFeedbackToolDescriptor(options = {}) {
             ]
         },
         annotations: {
-            title: 'Send feedback',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-            destructiveHint: false
+            ...external_tools_js_namespaceObject.VIRTUAL_TOOL_ANNOTATIONS
         }
     };
 }

package/dist/extensions/feedback.mjs

@@ -1,6 +1,7 @@
 import { PostHogMCPAnalyticsProperty } from "./constants.mjs";
 import { log } from "./logger.mjs";
 import { sanitizeFreeText, sanitizeFreeTextValue } from "./mcp-payloads.mjs";
+import { VIRTUAL_TOOL_ANNOTATIONS } from "./tools.mjs";
 import { TRUNCATION_SUFFIX } from "./truncation.mjs";
 const SEND_FEEDBACK_TOOL_NAME = 'send_feedback';
 const FEEDBACK_TYPES = [
@@ -92,11 +93,7 @@ function getFeedbackToolDescriptor(options = {}) {
             ]
         },
         annotations: {
-            title: 'Send feedback',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-            destructiveHint: false
+            ...VIRTUAL_TOOL_ANNOTATIONS
         }
     };
 }

package/dist/extensions/instrument-highlevel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-highlevel.d.ts","sourceRoot":"","sources":["../../src/extensions/instrument-highlevel.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,sBAAsB,EAIvB,MAAM,UAAU,CAAA;AAmBjB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAwRxC,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,QAAQ,GAAG,IAAI,CA+BhG"}
+{"version":3,"file":"instrument-highlevel.d.ts","sourceRoot":"","sources":["../../src/extensions/instrument-highlevel.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,sBAAsB,EAIvB,MAAM,UAAU,CAAA;AAmBjB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AA6RxC,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,QAAQ,GAAG,IAAI,CAgChG"}

package/dist/extensions/instrument-highlevel.js

@@ -155,7 +155,7 @@ function addTracingToToolCallbackInternal(tool, toolName, server, getCurrentInpu
     wrappedTool[MCP_ANALYTICS_PROCESSED] = true;
     return wrappedTool;
 }
-async function handleToolCallRequest(highLevelServer, server, originalCallToolHandler, request, extra, logger) {
+async function handleToolCallRequest(highLevelServer, server, originalCallToolHandler, request, extra, logger, registryDispatches) {
     const data = (0, external_internal_js_namespaceObject.getServerTrackingData)(server);
     if (!data) {
         logger('Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using tool calls.');
@@ -195,7 +195,7 @@ async function handleToolCallRequest(highLevelServer, server, originalCallToolHa
             execute: async ()=>(0, external_feedback_js_namespaceObject.handleFeedback)(report, feedbackOptions, data.logger)
         });
     }
-    const registeredTool = toolName ? highLevelServer._registeredTools[toolName] : void 0;
+    const registeredTool = toolName && Object.prototype.hasOwnProperty.call(highLevelServer._registeredTools, toolName) ? highLevelServer._registeredTools[toolName] : void 0;
     return await (0, external_instrumentation_js_namespaceObject.captureToolCall)({
         server,
         data,
@@ -204,6 +204,7 @@ async function handleToolCallRequest(highLevelServer, server, originalCallToolHa
         execute: (downstreamRequest)=>originalCallToolHandler(downstreamRequest, extra),
         parameterOwnership: registeredTool ? (0, external_analytics_parameters_js_namespaceObject.getAnalyticsParameterOwnership)(registeredTool.inputSchema, registeredTool.outputSchema) : void 0,
         inputSchema: registeredTool?.inputSchema,
+        isUnknownTool: !!toolName && !registeredTool && registryDispatches(),
         takeCapturedError: ()=>{
             const captured = extra?.__mcp_analytics_error;
             if (extra) extra.__mcp_analytics_error = void 0;
@@ -215,10 +216,11 @@ function instrumentHighLevelServer(server, logger) {
     try {
         const lowLevelServer = server.server;
         const mcpAnalyticsData = (0, external_internal_js_namespaceObject.getServerTrackingData)(lowLevelServer);
+        const registryDispatches = trackRegistryDispatch(server);
         const handlers = {
             initialize: (trackedServer, originalHandler, request, extra)=>(0, external_instrumentation_js_namespaceObject.handleInitializeRequest)(trackedServer, originalHandler, request, extra, logger),
             'tools/list': (trackedServer, originalHandler, request, extra)=>(0, external_instrumentation_js_namespaceObject.handleListToolsRequest)(trackedServer, originalHandler, request, extra, logger),
-            'tools/call': (trackedServer, originalHandler, request, extra)=>handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger),
+            'tools/call': (trackedServer, originalHandler, request, extra)=>handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger, registryDispatches),
             'resources/list': (0, external_instrumentation_js_namespaceObject.traceResourceRequest)(external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpResourcesList, logger),
             'resources/templates/list': (0, external_instrumentation_js_namespaceObject.traceResourceRequest)(external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpResourcesList, logger),
             'resources/read': (0, external_instrumentation_js_namespaceObject.traceResourceRequest)(external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpResourcesRead, logger)
@@ -234,6 +236,16 @@ function instrumentHighLevelServer(server, logger) {
         logger(`Warning: Failed to setup tool call instrumentation - ${error}`);
     }
 }
+function trackRegistryDispatch(server) {
+    const lowLevelServer = server.server;
+    let replaced = false;
+    const setRequestHandler = lowLevelServer.setRequestHandler.bind(lowLevelServer);
+    lowLevelServer.setRequestHandler = (...args)=>{
+        if (server._toolHandlersInitialized && 'tools/call' === (0, external_mcp_sdk_compat_js_namespaceObject.readRequestHandlerMethod)(args[0])) replaced = true;
+        return setRequestHandler(...args);
+    };
+    return ()=>true === server._toolHandlersInitialized && !replaced;
+}
 function seedToolDescriptionsFromRegistry(cache, tools) {
     for (const [name, tool] of Object.entries(tools))if ('string' == typeof tool?.description) cache.set(name, tool.description);
 }

package/dist/extensions/instrument-highlevel.mjs

@@ -4,7 +4,7 @@ import { isContextEnabled } from "./context-parameters.mjs";
 import { isCaptureModelEnabled } from "./model-parameters.mjs";
 import { MCPAnalyticsEventType } from "./event-types.mjs";
 import { getServerTrackingData } from "./internal.mjs";
-import { createWrappedTool, getToolFunction, hasToolFunction } from "./mcp-sdk-compat.mjs";
+import { createWrappedTool, getToolFunction, hasToolFunction, readRequestHandlerMethod } from "./mcp-sdk-compat.mjs";
 import { getReportMissingToolDescriptor, handleReportMissing, resolveMissingCapabilityToolName } from "./tools.mjs";
 import { captureToolCall, handleInitializeRequest, handleListToolsRequest, isToolAdvertised, patchRequestHandlers, readToolMetaCategory, traceResourceRequest } from "./instrumentation.mjs";
 import { getContextArgument } from "./tracing-helpers.mjs";
@@ -123,7 +123,7 @@ function addTracingToToolCallbackInternal(tool, toolName, server, getCurrentInpu
     wrappedTool[MCP_ANALYTICS_PROCESSED] = true;
     return wrappedTool;
 }
-async function handleToolCallRequest(highLevelServer, server, originalCallToolHandler, request, extra, logger) {
+async function handleToolCallRequest(highLevelServer, server, originalCallToolHandler, request, extra, logger, registryDispatches) {
     const data = getServerTrackingData(server);
     if (!data) {
         logger('Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using tool calls.');
@@ -163,7 +163,7 @@ async function handleToolCallRequest(highLevelServer, server, originalCallToolHa
             execute: async ()=>handleFeedback(report, feedbackOptions, data.logger)
         });
     }
-    const registeredTool = toolName ? highLevelServer._registeredTools[toolName] : void 0;
+    const registeredTool = toolName && Object.prototype.hasOwnProperty.call(highLevelServer._registeredTools, toolName) ? highLevelServer._registeredTools[toolName] : void 0;
     return await captureToolCall({
         server,
         data,
@@ -172,6 +172,7 @@ async function handleToolCallRequest(highLevelServer, server, originalCallToolHa
         execute: (downstreamRequest)=>originalCallToolHandler(downstreamRequest, extra),
         parameterOwnership: registeredTool ? getAnalyticsParameterOwnership(registeredTool.inputSchema, registeredTool.outputSchema) : void 0,
         inputSchema: registeredTool?.inputSchema,
+        isUnknownTool: !!toolName && !registeredTool && registryDispatches(),
         takeCapturedError: ()=>{
             const captured = extra?.__mcp_analytics_error;
             if (extra) extra.__mcp_analytics_error = void 0;
@@ -183,10 +184,11 @@ function instrumentHighLevelServer(server, logger) {
     try {
         const lowLevelServer = server.server;
         const mcpAnalyticsData = getServerTrackingData(lowLevelServer);
+        const registryDispatches = trackRegistryDispatch(server);
         const handlers = {
             initialize: (trackedServer, originalHandler, request, extra)=>handleInitializeRequest(trackedServer, originalHandler, request, extra, logger),
             'tools/list': (trackedServer, originalHandler, request, extra)=>handleListToolsRequest(trackedServer, originalHandler, request, extra, logger),
-            'tools/call': (trackedServer, originalHandler, request, extra)=>handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger),
+            'tools/call': (trackedServer, originalHandler, request, extra)=>handleToolCallRequest(server, trackedServer, originalHandler, request, extra, logger, registryDispatches),
             'resources/list': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesList, logger),
             'resources/templates/list': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesList, logger),
             'resources/read': traceResourceRequest(MCPAnalyticsEventType.mcpResourcesRead, logger)
@@ -202,6 +204,16 @@ function instrumentHighLevelServer(server, logger) {
         logger(`Warning: Failed to setup tool call instrumentation - ${error}`);
     }
 }
+function trackRegistryDispatch(server) {
+    const lowLevelServer = server.server;
+    let replaced = false;
+    const setRequestHandler = lowLevelServer.setRequestHandler.bind(lowLevelServer);
+    lowLevelServer.setRequestHandler = (...args)=>{
+        if (server._toolHandlersInitialized && 'tools/call' === readRequestHandlerMethod(args[0])) replaced = true;
+        return setRequestHandler(...args);
+    };
+    return ()=>true === server._toolHandlersInitialized && !replaced;
+}
 function seedToolDescriptionsFromRegistry(cache, tools) {
     for (const [name, tool] of Object.entries(tools))if ('string' == typeof tool?.description) cache.set(name, tool.description);
 }

package/dist/extensions/instrument-lowlevel.js

@@ -99,7 +99,9 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
             execute: async ()=>(0, external_feedback_js_namespaceObject.handleFeedback)(report, feedbackOptions, data.logger)
         });
     }
-    const originalTool = resolveOriginalTool(data, toolName);
+    const lookup = lookUpOriginalTool(data, toolName);
+    const originalTool = lookup.registered ? lookup.tool : void 0;
+    const hasDispatcher = void 0 !== originalCallToolHandler && originalCallToolHandler !== unknownToolHandler;
     return await (0, external_instrumentation_js_namespaceObject.captureToolCall)({
         server,
         data,
@@ -107,16 +109,27 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
         extra,
         execute: (downstreamRequest)=>runOriginalToolHandler(originalCallToolHandler, downstreamRequest, extra),
         parameterOwnership: originalTool && !(toolName && data.toolAnalyticsParameterOwnership.has(toolName)) ? (0, external_analytics_parameters_js_namespaceObject.getAnalyticsParameterOwnership)(originalTool.inputSchema) : void 0,
-        inputSchema: originalTool?.inputSchema
+        inputSchema: originalTool?.inputSchema,
+        isUnknownTool: !!toolName && (!hasDispatcher || false === lookup.registered)
     });
 }
-function resolveOriginalTool(data, toolName) {
-    if (!toolName || !data.options.resolveOriginalTool) return;
+function lookUpOriginalTool(data, toolName) {
+    if (!toolName || !data.options.resolveOriginalTool) return {
+        registered: void 0
+    };
     try {
-        return data.options.resolveOriginalTool(toolName) ?? void 0;
+        const tool = data.options.resolveOriginalTool(toolName);
+        return tool ? {
+            registered: true,
+            tool
+        } : {
+            registered: false
+        };
     } catch (error) {
         data.logger(`Warning: resolveOriginalTool failed for tool ${toolName} - ${error}`);
-        return;
+        return {
+            registered: void 0
+        };
     }
 }
 function runOriginalToolHandler(handler, request, extra) {

package/dist/extensions/instrument-lowlevel.mjs

@@ -67,7 +67,9 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
             execute: async ()=>handleFeedback(report, feedbackOptions, data.logger)
         });
     }
-    const originalTool = resolveOriginalTool(data, toolName);
+    const lookup = lookUpOriginalTool(data, toolName);
+    const originalTool = lookup.registered ? lookup.tool : void 0;
+    const hasDispatcher = void 0 !== originalCallToolHandler && originalCallToolHandler !== unknownToolHandler;
     return await captureToolCall({
         server,
         data,
@@ -75,16 +77,27 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
         extra,
         execute: (downstreamRequest)=>runOriginalToolHandler(originalCallToolHandler, downstreamRequest, extra),
         parameterOwnership: originalTool && !(toolName && data.toolAnalyticsParameterOwnership.has(toolName)) ? getAnalyticsParameterOwnership(originalTool.inputSchema) : void 0,
-        inputSchema: originalTool?.inputSchema
+        inputSchema: originalTool?.inputSchema,
+        isUnknownTool: !!toolName && (!hasDispatcher || false === lookup.registered)
     });
 }
-function resolveOriginalTool(data, toolName) {
-    if (!toolName || !data.options.resolveOriginalTool) return;
+function lookUpOriginalTool(data, toolName) {
+    if (!toolName || !data.options.resolveOriginalTool) return {
+        registered: void 0
+    };
     try {
-        return data.options.resolveOriginalTool(toolName) ?? void 0;
+        const tool = data.options.resolveOriginalTool(toolName);
+        return tool ? {
+            registered: true,
+            tool
+        } : {
+            registered: false
+        };
     } catch (error) {
         data.logger(`Warning: resolveOriginalTool failed for tool ${toolName} - ${error}`);
-        return;
+        return {
+            registered: void 0
+        };
     }
 }
 function runOriginalToolHandler(handler, request, extra) {

package/dist/extensions/instrumentation.d.ts

@@ -52,6 +52,11 @@ interface TraceToolCallParams {
      * read it here to capture the real stack rather than the result envelope.
      */
     takeCapturedError?: () => unknown;
+    /**
+     * The SDK knows the server has no tool by this name, so a rejected call is
+     * recorded as `$mcp_unknown_tool`, not as a tool call.
+     */
+    isUnknownTool?: boolean;
 }
 /**
  * The shared tool-call lifecycle: resolve conversation id, build + enrich the

package/dist/extensions/instrumentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/extensions/instrumentation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,uBAAuB,EAEvB,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EAId,MAAM,UAAU,CAAA;AAqBjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAiBxC;;;;;;GAMG;AAEH,KAAK,iBAAiB,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,6BAA6B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAE7G,2EAA2E;AAC3E,KAAK,YAAY,GAAG,CAAC,iBAAiB,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAmB3E,UAAU,mBAAmB;IAC3B,MAAM,EAAE,aAAa,CAAA;IACrB,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,CAAC,EAAE,6BAA6B,CAAA;IACrC,OAAO,EAAE,YAAY,CAAA;IACrB,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,2BAA2B,CAAA;IAChD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAA;IACjC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,UAAU,CAAA;IACjC;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwFnF;AAuQD,KAAK,iBAAiB,GAAG,OAAO,qBAAqB,CAAC,gBAAgB,GAAG,OAAO,qBAAqB,CAAC,gBAAgB,CAAA;AAuDtH,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,QAAQ,GAAG,YAAY,CAGjG;AAgDD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,MAAM,EAAE,aAAa,EACrB,eAAe,EAAE,iBAAiB,EAClC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,6BAA6B,GAAG,SAAS,KAC7C,OAAO,CAAC,OAAO,CAAC,CAAA;AAkBrB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,iBAAiB,EAClC,KAAK,EAAE,YAAY,GAClB,IAAI,CAGN;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI,CA0CvG;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,6BAA6B,GAAG,SAAS,EAChD,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAoB9B;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,aAAa,EACrB,wBAAwB,EAAE,iBAAiB,EAC3C,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,6BAA6B,GAAG,SAAS,EAChD,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC,uBAAuB,CAAC,CAwElC;AAqJD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,GAAG,SAAS,GAClD,IAAI,CASN;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGtE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,GAAG,SAAS,GAClD,IAAI,CAUN;AAuHD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,aAAa,EACrB,yBAAyB,EAAE,iBAAiB,EAC5C,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,6BAA6B,GAAG,SAAS,EAChD,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC,OAAO,CAAC,CA6ElB"}
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/extensions/instrumentation.ts"],"names":[],"mappings":"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"}