@posthog/mcp 0.11.4 → 0.11.6

package/README.md

@@ -116,6 +116,39 @@ identify: async (request, extra) => {
 }
 ```
 
+### What `$mcp_intent` records, and how to turn it off
+
+`context` defaults to **on**: the SDK adds a `context` parameter to every tool it advertises, asks
+the agent to say why it is calling, and records the answer as `$mcp_intent`. It is stripped before
+your tool runs wherever the SDK can confirm the parameter is its own.
+
+On a server that builds a fresh instance per HTTP request — `createMcpHandler`, or `@rekog/mcp-nest`
+in its stateless mode — that confirmation is not available: ownership is learned while serving
+`tools/list`, and the instance handling a `tools/call` never served one. There the SDK records the
+argument but does **not** strip it, because deleting an argument your tool declared would cost you
+the call, while an extra key usually costs nothing.
+
+What matters is instance lifetime, not statelessness. A server that is stateless at the transport
+(`sessionIdGenerator: undefined`) but keeps one long-lived server object learns ownership from the
+first `tools/list` and keeps it, so none of the above applies to it.
+
+The consequence worth knowing: if **your own** tool declares a parameter named `context` and the SDK
+cannot tell that it is yours, its value is recorded as `$mcp_intent`. It never leaves your project,
+and it is capped at 2048 characters. Two ways out, both one line:
+
+```ts
+instrument(server, posthog, { context: false })                   // no injection, no capture
+
+instrument(server, posthog, {                                     // keep it, drop the property
+  beforeSend: (event) => {
+    delete event.properties.$mcp_intent
+    return event
+  },
+})
+```
+
+`intentFallback` is the third option: supply the intent yourself when the agent did not send one.
+
 ### If you switched to `instrument(server.server)`
 
 Before v2 support landed, the compatibility gate rejected high-level v2 servers, and the usual

package/dist/extensions/instrumentation.d.ts

@@ -95,9 +95,7 @@ export declare function isToolAdvertised(server: MCPServerLike, toolName: string
  * Captures each `tools/list` and injects the SDK-managed tools (context
  * parameter, conversation id, `get_more_tools`) into the returned list.
  */
-export declare function handleListToolsRequest(server: MCPServerLike, originalListToolsHandler: MCPRequestHandler, request: MCPRequestLike, extra: CompatibleRequestHandlerExtra | undefined, logger: LoggerFn): Promise<{
-    tools: CompatibleToolsListLike['tools'];
-}>;
+export declare function handleListToolsRequest(server: MCPServerLike, originalListToolsHandler: MCPRequestHandler, request: MCPRequestLike, extra: CompatibleRequestHandlerExtra | undefined, logger: LoggerFn): Promise<CompatibleToolsListLike>;
 export declare function cacheToolDescriptions(cache: Map<string, string>, tools: CompatibleToolsListLike['tools'] | undefined): void;
 /**
  * Category declared on a tool's `_meta` block (the MCP spec allows arbitrary

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

@@ -1 +1 @@
-{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/extensions/instrumentation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/extensions/instrumentation.ts"],"names":[],"mappings":"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"}

package/dist/extensions/instrumentation.js

@@ -56,10 +56,11 @@ async function captureToolCall(params) {
     const { server, data, request, extra, execute, parameterOwnership, eventType, explicitContextIntent, takeCapturedError } = params;
     const resolvedEventType = eventType ?? external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpToolsCall;
     const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership, resolvedEventType === external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpMissingCapability);
+    const canCaptureContextIntent = resolvedEventType !== external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpMissingCapability && (0, external_context_parameters_js_namespaceObject.isContextEnabled)(data.options.context) && (ownership.context || !ownership.contextOwnershipKnown);
     const conversation = (0, external_conversation_id_js_namespaceObject.resolveConversationId)(ownership.conversationId, request.params?.arguments);
     const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership);
     const startTime = new Date();
-    const preparedEvent = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType);
+    const preparedEvent = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType, canCaptureContextIntent);
     if (preparedEvent && explicitContextIntent) (0, external_intent_js_namespaceObject.setExplicitContextIntent)(preparedEvent.event, explicitContextIntent);
     let result;
     try {
@@ -76,6 +77,7 @@ function getActiveAnalyticsParameterOwnership(data, toolName, override, isMissin
     const listed = toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : void 0;
     const ownership = override ?? listed;
     return {
+        contextOwnershipKnown: void 0 !== ownership,
         context: !isMissingCapabilityTool && (0, external_context_parameters_js_namespaceObject.isContextEnabled)(data.options.context) && ownership?.context === true,
         conversationId: true === data.options.enableConversationId && ownership?.conversationId === true,
         outputInstructions: true === data.options.enableConversationId && listed?.outputInstructions === true
@@ -93,12 +95,10 @@ function cloneRequestWithoutOwnedAnalyticsArguments(request, ownership) {
         }
     };
 }
-async function prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, eventType) {
+async function prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, eventType, canCaptureContextIntent) {
     try {
         const sessionId = (0, external_session_js_namespaceObject.getSessionId)(server, extra, conversation.conversationId);
         const sessionInfo = (0, external_session_js_namespaceObject.getSessionInfo)(server, data, sessionId);
-        const identity = await (0, external_internal_js_namespaceObject.handleIdentify)(server, data, sessionId, request, sessionInfo, extra, !!conversation.conversationId);
-        const requestAttribution = (0, external_internal_js_namespaceObject.withIdentity)(sessionInfo, identity);
         const toolName = request.params?.name;
         const event = {
             sessionId,
@@ -112,8 +112,10 @@ async function prepareToolCallEvent(server, data, request, downstreamRequest, ex
         };
         (0, external_client_identity_js_namespaceObject.stampClientIdentity)(event, request, extra, server);
         (0, external_transport_identity_js_namespaceObject.stampTransportIdentity)(event, extra);
+        const identity = await (0, external_internal_js_namespaceObject.handleIdentify)(server, data, sessionId, request, sessionInfo, extra, !!conversation.conversationId);
+        const requestAttribution = (0, external_internal_js_namespaceObject.withIdentity)(sessionInfo, identity);
         await (0, external_tracing_helpers_js_namespaceObject.applyResolvedMetadata)(event, data, request, extra);
-        (0, external_intent_js_namespaceObject.setEventIntent)(event, await (0, external_intent_js_namespaceObject.resolveToolCallIntent)(data, request, ownership.context, extra));
+        (0, external_intent_js_namespaceObject.setEventIntent)(event, await (0, external_intent_js_namespaceObject.resolveToolCallIntent)(data, request, canCaptureContextIntent, extra));
         return {
             event,
             requestAttribution
@@ -223,7 +225,7 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
     const data = (0, external_internal_js_namespaceObject.getServerTrackingData)(server);
     const startTime = new Date();
     const sessionId = (0, external_session_js_namespaceObject.getSessionId)(server, extra);
-    const requestAttribution = (0, external_session_js_namespaceObject.getSessionInfo)(server, data, sessionId);
+    const sessionInfo = (0, external_session_js_namespaceObject.getSessionInfo)(server, data, sessionId);
     const event = {
         sessionId,
         parameters: (0, external_mcp_payloads_js_namespaceObject.buildCapturedMcpParameters)(request),
@@ -232,13 +234,14 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
     };
     (0, external_client_identity_js_namespaceObject.stampClientIdentity)(event, request, extra, server);
     (0, external_transport_identity_js_namespaceObject.stampTransportIdentity)(event, extra);
+    const identity = data ? await (0, external_internal_js_namespaceObject.handleIdentify)(server, data, sessionId, request, sessionInfo, extra) : void 0;
+    const requestAttribution = (0, external_internal_js_namespaceObject.withIdentity)(sessionInfo, identity);
     if (data) await (0, external_tracing_helpers_js_namespaceObject.applyResolvedMetadata)(event, data, request, extra);
-    const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution);
+    const response = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution);
+    const tools = response.tools;
     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.');
-        return {
-            tools
-        };
+        return response;
     }
     if (0 === tools.length) {
         data.logger('Warning: No tools found in the original list. This is likely due to the tools not being registered before PostHog MCP analytics.instrument().');
@@ -246,20 +249,14 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
         event.isError = true;
         event.duration = Date.now() - startTime.getTime();
         (0, external_capture_js_namespaceObject.captureEvent)(server, event, data.logger, requestAttribution);
-        return {
-            tools
-        };
+        return response;
     }
-    event.response = {
-        tools
-    };
+    event.response = response;
     event.listedToolNames = collectListedToolNames(tools);
     event.isError = false;
     event.duration = Date.now() - startTime.getTime();
     (0, external_capture_js_namespaceObject.captureEvent)(server, event, data.logger, requestAttribution);
-    return {
-        tools
-    };
+    return response;
 }
 function cacheToolAnalyticsParameterOwnership(cache, tools) {
     for (const tool of tools)if (tool?.name) cache.set(tool.name, (0, external_analytics_parameters_js_namespaceObject.getAnalyticsParameterOwnership)(tool.inputSchema, tool.outputSchema));
@@ -300,7 +297,10 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
             cacheToolDescriptions(data.toolDescriptions, tools);
             cacheToolCategories(data.toolCategories, tools);
         }
-        return tools;
+        return {
+            ...originalResponse,
+            tools
+        };
     } catch (error) {
         logger(`Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`);
         event.error = (0, external_exceptions_js_namespaceObject.captureException)(error);
@@ -395,8 +395,6 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
         clientName: initializeClientInfo?.name ?? sessionInfo.clientName,
         clientVersion: initializeClientInfo?.version ?? sessionInfo.clientVersion
     };
-    const identity = await (0, external_internal_js_namespaceObject.handleIdentify)(server, data, sessionId, request, requestSessionInfo, extra);
-    const requestAttribution = (0, external_internal_js_namespaceObject.withIdentity)(requestSessionInfo, identity);
     const event = {
         sessionId,
         resourceName: request.params?.name || 'Unknown Tool Name',
@@ -405,7 +403,11 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
         timestamp: new Date()
     };
     (0, external_client_identity_js_namespaceObject.stampClientIdentity)(event, request, extra, server);
+    if (initializeClientInfo?.name) event.clientName = initializeClientInfo.name;
+    if (initializeClientInfo?.version) event.clientVersion = initializeClientInfo.version;
     (0, external_transport_identity_js_namespaceObject.stampTransportIdentity)(event, extra);
+    const identity = await (0, external_internal_js_namespaceObject.handleIdentify)(server, data, sessionId, request, requestSessionInfo, extra);
+    const requestAttribution = (0, external_internal_js_namespaceObject.withIdentity)(requestSessionInfo, identity);
     await (0, external_tracing_helpers_js_namespaceObject.applyResolvedMetadata)(event, data, request, extra);
     const result = await originalInitializeHandler(request, extra);
     event.response = result;

package/dist/extensions/instrumentation.mjs

@@ -20,10 +20,11 @@ async function captureToolCall(params) {
     const { server, data, request, extra, execute, parameterOwnership, eventType, explicitContextIntent, takeCapturedError } = params;
     const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall;
     const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership, resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability);
+    const canCaptureContextIntent = resolvedEventType !== MCPAnalyticsEventType.mcpMissingCapability && isContextEnabled(data.options.context) && (ownership.context || !ownership.contextOwnershipKnown);
     const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments);
     const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership);
     const startTime = new Date();
-    const preparedEvent = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType);
+    const preparedEvent = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType, canCaptureContextIntent);
     if (preparedEvent && explicitContextIntent) setExplicitContextIntent(preparedEvent.event, explicitContextIntent);
     let result;
     try {
@@ -40,6 +41,7 @@ function getActiveAnalyticsParameterOwnership(data, toolName, override, isMissin
     const listed = toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : void 0;
     const ownership = override ?? listed;
     return {
+        contextOwnershipKnown: void 0 !== ownership,
         context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
         conversationId: true === data.options.enableConversationId && ownership?.conversationId === true,
         outputInstructions: true === data.options.enableConversationId && listed?.outputInstructions === true
@@ -57,12 +59,10 @@ function cloneRequestWithoutOwnedAnalyticsArguments(request, ownership) {
         }
     };
 }
-async function prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, eventType) {
+async function prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, eventType, canCaptureContextIntent) {
     try {
         const sessionId = getSessionId(server, extra, conversation.conversationId);
         const sessionInfo = getSessionInfo(server, data, sessionId);
-        const identity = await handleIdentify(server, data, sessionId, request, sessionInfo, extra, !!conversation.conversationId);
-        const requestAttribution = withIdentity(sessionInfo, identity);
         const toolName = request.params?.name;
         const event = {
             sessionId,
@@ -76,8 +76,10 @@ async function prepareToolCallEvent(server, data, request, downstreamRequest, ex
         };
         stampClientIdentity(event, request, extra, server);
         stampTransportIdentity(event, extra);
+        const identity = await handleIdentify(server, data, sessionId, request, sessionInfo, extra, !!conversation.conversationId);
+        const requestAttribution = withIdentity(sessionInfo, identity);
         await applyResolvedMetadata(event, data, request, extra);
-        setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra));
+        setEventIntent(event, await resolveToolCallIntent(data, request, canCaptureContextIntent, extra));
         return {
             event,
             requestAttribution
@@ -187,7 +189,7 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
     const data = getServerTrackingData(server);
     const startTime = new Date();
     const sessionId = getSessionId(server, extra);
-    const requestAttribution = getSessionInfo(server, data, sessionId);
+    const sessionInfo = getSessionInfo(server, data, sessionId);
     const event = {
         sessionId,
         parameters: buildCapturedMcpParameters(request),
@@ -196,13 +198,14 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
     };
     stampClientIdentity(event, request, extra, server);
     stampTransportIdentity(event, extra);
+    const identity = data ? await handleIdentify(server, data, sessionId, request, sessionInfo, extra) : void 0;
+    const requestAttribution = withIdentity(sessionInfo, identity);
     if (data) await applyResolvedMetadata(event, data, request, extra);
-    const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution);
+    const response = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution);
+    const tools = response.tools;
     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.');
-        return {
-            tools
-        };
+        return response;
     }
     if (0 === tools.length) {
         data.logger('Warning: No tools found in the original list. This is likely due to the tools not being registered before PostHog MCP analytics.instrument().');
@@ -210,20 +213,14 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
         event.isError = true;
         event.duration = Date.now() - startTime.getTime();
         captureEvent(server, event, data.logger, requestAttribution);
-        return {
-            tools
-        };
+        return response;
     }
-    event.response = {
-        tools
-    };
+    event.response = response;
     event.listedToolNames = collectListedToolNames(tools);
     event.isError = false;
     event.duration = Date.now() - startTime.getTime();
     captureEvent(server, event, data.logger, requestAttribution);
-    return {
-        tools
-    };
+    return response;
 }
 function cacheToolAnalyticsParameterOwnership(cache, tools) {
     for (const tool of tools)if (tool?.name) cache.set(tool.name, getAnalyticsParameterOwnership(tool.inputSchema, tool.outputSchema));
@@ -264,7 +261,10 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
             cacheToolDescriptions(data.toolDescriptions, tools);
             cacheToolCategories(data.toolCategories, tools);
         }
-        return tools;
+        return {
+            ...originalResponse,
+            tools
+        };
     } catch (error) {
         logger(`Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`);
         event.error = captureException(error);
@@ -359,8 +359,6 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
         clientName: initializeClientInfo?.name ?? sessionInfo.clientName,
         clientVersion: initializeClientInfo?.version ?? sessionInfo.clientVersion
     };
-    const identity = await handleIdentify(server, data, sessionId, request, requestSessionInfo, extra);
-    const requestAttribution = withIdentity(requestSessionInfo, identity);
     const event = {
         sessionId,
         resourceName: request.params?.name || 'Unknown Tool Name',
@@ -369,7 +367,11 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
         timestamp: new Date()
     };
     stampClientIdentity(event, request, extra, server);
+    if (initializeClientInfo?.name) event.clientName = initializeClientInfo.name;
+    if (initializeClientInfo?.version) event.clientVersion = initializeClientInfo.version;
     stampTransportIdentity(event, extra);
+    const identity = await handleIdentify(server, data, sessionId, request, requestSessionInfo, extra);
+    const requestAttribution = withIdentity(requestSessionInfo, identity);
     await applyResolvedMetadata(event, data, request, extra);
     const result = await originalInitializeHandler(request, extra);
     event.response = result;

package/dist/extensions/intent.d.ts

@@ -3,7 +3,7 @@ interface ResolvedIntent {
     intent: string;
     source: MCPAnalyticsIntentSource;
 }
-export declare function resolveToolCallIntent(data: MCPAnalyticsData, request: MCPRequestLike, analyticsOwnsContext: boolean, extra?: CompatibleRequestHandlerExtra): Promise<ResolvedIntent | null>;
+export declare function resolveToolCallIntent(data: MCPAnalyticsData, request: MCPRequestLike, canCaptureContext: boolean, extra?: CompatibleRequestHandlerExtra): Promise<ResolvedIntent | null>;
 export declare function setEventIntent(event: McpEvent, resolvedIntent: ResolvedIntent | null): void;
 export declare function setExplicitContextIntent(event: McpEvent, context: string): void;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../src/extensions/intent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,QAAQ,EACT,MAAM,UAAU,CAAA;AAGjB,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAkCD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,oBAAoB,EAAE,OAAO,EAC7B,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOhC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAO3F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ/E"}
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../src/extensions/intent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,QAAQ,EACT,MAAM,UAAU,CAAA;AAGjB,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAkCD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,iBAAiB,EAAE,OAAO,EAC1B,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOhC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAO3F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ/E"}

package/dist/extensions/intent.js

@@ -51,9 +51,9 @@ async function runIntentFallback(data, request, extra) {
         return null;
     }
 }
-async function resolveToolCallIntent(data, request, analyticsOwnsContext, extra) {
+async function resolveToolCallIntent(data, request, canCaptureContext, extra) {
     const contextArgument = getContextArgument(request);
-    if (analyticsOwnsContext && (0, external_context_parameters_js_namespaceObject.isContextEnabled)(data.options.context) && contextArgument) return {
+    if (canCaptureContext && (0, external_context_parameters_js_namespaceObject.isContextEnabled)(data.options.context) && contextArgument) return {
         intent: contextArgument,
         source: 'context_parameter'
     };

package/dist/extensions/intent.mjs

@@ -21,9 +21,9 @@ async function runIntentFallback(data, request, extra) {
         return null;
     }
 }
-async function resolveToolCallIntent(data, request, analyticsOwnsContext, extra) {
+async function resolveToolCallIntent(data, request, canCaptureContext, extra) {
     const contextArgument = getContextArgument(request);
-    if (analyticsOwnsContext && isContextEnabled(data.options.context) && contextArgument) return {
+    if (canCaptureContext && isContextEnabled(data.options.context) && contextArgument) return {
         intent: contextArgument,
         source: 'context_parameter'
     };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.11.4";
+export declare const version = "0.11.6";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '0.11.4';
+const version = '0.11.6';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '0.11.4';
+const version = '0.11.6';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -28,7 +28,7 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@posthog/core": "^1.47.0"
+    "@posthog/core": "^1.48.0"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.27.1",
@@ -40,8 +40,8 @@
     "@types/node": "^20.0.0",
     "jest": "29.7.0",
     "zod": "^3.25.0",
-    "posthog-node": "^5.48.1",
-    "@posthog-tooling/tsconfig-base": "1.1.1"
+    "@posthog-tooling/tsconfig-base": "1.1.1",
+    "posthog-node": "^5.49.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.26.0",

package/src/extensions/instrumentation.ts

@@ -109,6 +109,14 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     parameterOwnership,
     resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability
   )
+  // Reading the argument and removing it are separate questions: deleting one the
+  // application declared costs the customer their call, so the strip below still
+  // requires positive ownership, while reading it when ownership is unresolved
+  // costs at worst a mislabelled property. ADR-0011.
+  const canCaptureContextIntent =
+    resolvedEventType !== MCPAnalyticsEventType.mcpMissingCapability &&
+    isContextEnabled(data.options.context) &&
+    (ownership.context || !ownership.contextOwnershipKnown)
   const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments)
   const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership)
 
@@ -124,7 +132,8 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     startTime,
     conversation,
     ownership,
-    resolvedEventType
+    resolvedEventType,
+    canCaptureContextIntent
   )
   if (preparedEvent && explicitContextIntent) {
     setExplicitContextIntent(preparedEvent.event, explicitContextIntent)
@@ -150,15 +159,24 @@ interface PreparedToolEvent {
   requestAttribution: SessionInfo
 }
 
+/**
+ * Ownership for one request, plus whether it could be resolved at all — "no
+ * answer" must not read the same as "the application owns it".
+ */
+interface ActiveAnalyticsParameterOwnership extends AnalyticsParameterOwnership {
+  contextOwnershipKnown: boolean
+}
+
 function getActiveAnalyticsParameterOwnership(
   data: MCPAnalyticsData,
   toolName: string | undefined,
   override: AnalyticsParameterOwnership | undefined,
   isMissingCapabilityTool: boolean
-): AnalyticsParameterOwnership {
+): ActiveAnalyticsParameterOwnership {
   const listed = toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : undefined
   const ownership = override ?? listed
   return {
+    contextOwnershipKnown: ownership !== undefined,
     context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
     conversationId: data.options.enableConversationId === true && ownership?.conversationId === true,
     // Deliberately read off `listed`, never the override: only the advertised
@@ -199,23 +217,14 @@ async function prepareToolCallEvent(
   startTime: Date,
   conversation: ConversationIdResolution,
   ownership: AnalyticsParameterOwnership,
-  eventType: MCPAnalyticsEventType
+  eventType: MCPAnalyticsEventType,
+  canCaptureContextIntent: boolean
 ): Promise<PreparedToolEvent | null> {
   try {
     const sessionId = getSessionId(server, extra, conversation.conversationId)
     // Snapshot token/client/protocol metadata synchronously, before identify or
     // metadata callbacks can yield and let another request replace shared state.
     const sessionInfo = getSessionInfo(server, data, sessionId)
-    const identity = await handleIdentify(
-      server,
-      data,
-      sessionId,
-      request,
-      sessionInfo,
-      extra,
-      !!conversation.conversationId
-    )
-    const requestAttribution = withIdentity(sessionInfo, identity)
 
     const toolName = request.params?.name
     const event: McpEvent = {
@@ -230,14 +239,30 @@ async function prepareToolCallEvent(
     }
     // Modern (stateless) clients carry client name/version + protocol version in
     // `_meta` on every request rather than at `initialize`; stamp them onto this
-    // event now so concurrent requests can't cross-attribute it.
+    // event now so concurrent requests can't cross-attribute it. Stamped before
+    // the identify await below for the same reason the snapshot is: the chain's
+    // last link is the server's own `getClientVersion()`, which a concurrent
+    // `initialize` can replace while an identify callback is in flight — and
+    // `captureEvent` prefers a stamped value over `sessionInfo`, so a late stamp
+    // would win with the wrong client's name.
     stampClientIdentity(event, request, extra, server)
     // Which *surface* of the client made this call lives only in the request
     // headers (HTTP transports); `clientInfo` can't tell a vendor's products apart.
     stampTransportIdentity(event, extra)
 
+    const identity = await handleIdentify(
+      server,
+      data,
+      sessionId,
+      request,
+      sessionInfo,
+      extra,
+      !!conversation.conversationId
+    )
+    const requestAttribution = withIdentity(sessionInfo, identity)
+
     await applyResolvedMetadata(event, data, request, extra)
-    setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra))
+    setEventIntent(event, await resolveToolCallIntent(data, request, canCaptureContextIntent, extra))
     return { event, requestAttribution }
   } catch (error) {
     data.logger(
@@ -511,27 +536,39 @@ export async function handleListToolsRequest(
   request: MCPRequestLike,
   extra: CompatibleRequestHandlerExtra | undefined,
   logger: LoggerFn
-): Promise<{ tools: CompatibleToolsListLike['tools'] }> {
+): Promise<CompatibleToolsListLike> {
   const data = getServerTrackingData(server)
   const startTime = new Date()
   const sessionId = getSessionId(server, extra)
-  // Snapshot before metadata resolution or the list handler can yield to a
-  // concurrent request using the same instrumented server.
-  const requestAttribution = getSessionInfo(server, data, sessionId)
+  // Snapshot before identify, metadata resolution, or the list handler can yield
+  // to a concurrent request using the same instrumented server.
+  const sessionInfo = getSessionInfo(server, data, sessionId)
   const event: McpEvent = {
     sessionId,
     parameters: buildCapturedMcpParameters(request),
     eventType: MCPAnalyticsEventType.mcpToolsList,
     timestamp: startTime,
   }
+  // Stamp before the identify await below. The last link of the identity chain is
+  // the server's own `getClientVersion()`, which a concurrent `initialize` can
+  // replace while a slow identify callback is in flight — and `captureEvent`
+  // prefers a stamped value over the `sessionInfo` snapshot, so a late stamp
+  // would win with the wrong client's name.
   stampClientIdentity(event, request, extra, server)
   stampTransportIdentity(event, extra)
 
+  // `getSessionInfo` only surfaces an identity some earlier request already
+  // cached on this instance. On a per-request instance that cache is always
+  // empty, so without resolving `identify` here too, `tools/list` would be the
+  // one request path that never attributes to a person.
+  const identity = data ? await handleIdentify(server, data, sessionId, request, sessionInfo, extra) : undefined
+  const requestAttribution = withIdentity(sessionInfo, identity)
+
   if (data) {
     await applyResolvedMetadata(event, data, request, extra)
   }
 
-  const tools = await getTracedToolsList(
+  const response = await getTracedToolsList(
     server,
     originalListToolsHandler,
     request,
@@ -540,12 +577,13 @@ export async function handleListToolsRequest(
     logger,
     requestAttribution
   )
+  const tools = response.tools
 
   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.'
     )
-    return { tools }
+    return response
   }
 
   if (tools.length === 0) {
@@ -556,15 +594,15 @@ export async function handleListToolsRequest(
     event.isError = true
     event.duration = Date.now() - startTime.getTime()
     captureEvent(server, event, data.logger, requestAttribution)
-    return { tools }
+    return response
   }
 
-  event.response = { tools }
+  event.response = response
   event.listedToolNames = collectListedToolNames(tools)
   event.isError = false
   event.duration = Date.now() - startTime.getTime()
   captureEvent(server, event, data.logger, requestAttribution)
-  return { tools }
+  return response
 }
 
 function cacheToolAnalyticsParameterOwnership(
@@ -595,7 +633,7 @@ async function getTracedToolsList(
   event: McpEvent,
   logger: LoggerFn,
   requestAttribution: SessionInfo
-): Promise<CompatibleToolsListLike['tools']> {
+): Promise<CompatibleToolsListLike> {
   try {
     const data = getServerTrackingData(server)
     const originalResponse = (await originalListToolsHandler(request, extra)) as CompatibleToolsListLike
@@ -637,7 +675,8 @@ async function getTracedToolsList(
       cacheToolCategories(data.toolCategories, tools)
     }
 
-    return tools
+    // Spread, never enumerate — fields later revisions add survive by default.
+    return { ...originalResponse, tools }
   } catch (error) {
     logger(
       `Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`
@@ -837,9 +876,6 @@ export async function handleInitializeRequest(
     clientName: initializeClientInfo?.name ?? sessionInfo.clientName,
     clientVersion: initializeClientInfo?.version ?? sessionInfo.clientVersion,
   }
-  const identity = await handleIdentify(server, data, sessionId, request, requestSessionInfo, extra)
-  const requestAttribution = withIdentity(requestSessionInfo, identity)
-
   const event: McpEvent = {
     sessionId,
     resourceName: request.params?.name || 'Unknown Tool Name',
@@ -847,12 +883,30 @@ export async function handleInitializeRequest(
     parameters: buildCapturedMcpParameters(request),
     timestamp: new Date(),
   }
-  // Harmless for a legacy `initialize` (client info rides the body there, and the
-  // negotiated protocol version below overrides any `_meta` one); picks up client
-  // info if a client also sends it in `_meta`.
+  // Picks up client info if a client also sends it in `_meta` (the negotiated
+  // protocol version below overrides any `_meta` one). Stamped before the
+  // identify await for the same reason the snapshot is taken there: the chain's
+  // last link is the server's own `getClientVersion()`, which a concurrent
+  // `initialize` can replace while an identify callback is in flight.
   stampClientIdentity(event, request, extra, server)
+  // A legacy `initialize` carries its client in the request body, which is the
+  // one place the chain does not read. That body is this request's own answer,
+  // so it outranks the accessor — which on a server that already handshaked
+  // still names the *previous* client, because the SDK only records this one
+  // when its handler runs further below. Without this, the second and every
+  // later handshake on a shared instance reports the first client's name, since
+  // `captureEvent` prefers a stamped value over `requestSessionInfo`.
+  if (initializeClientInfo?.name) {
+    event.clientName = initializeClientInfo.name
+  }
+  if (initializeClientInfo?.version) {
+    event.clientVersion = initializeClientInfo.version
+  }
   stampTransportIdentity(event, extra)
 
+  const identity = await handleIdentify(server, data, sessionId, request, requestSessionInfo, extra)
+  const requestAttribution = withIdentity(requestSessionInfo, identity)
+
   await applyResolvedMetadata(event, data, request, extra)
 
   const result = await originalInitializeHandler(request, extra)

package/src/extensions/intent.ts

@@ -52,11 +52,11 @@ async function runIntentFallback(
 export async function resolveToolCallIntent(
   data: MCPAnalyticsData,
   request: MCPRequestLike,
-  analyticsOwnsContext: boolean,
+  canCaptureContext: boolean,
   extra?: CompatibleRequestHandlerExtra
 ): Promise<ResolvedIntent | null> {
   const contextArgument = getContextArgument(request)
-  if (analyticsOwnsContext && isContextEnabled(data.options.context) && contextArgument) {
+  if (canCaptureContext && isContextEnabled(data.options.context) && contextArgument) {
     return { intent: contextArgument, source: 'context_parameter' }
   }
 

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.11.4'
+export const version = '0.11.6'