@posthog/mcp 0.11.3 → 0.11.5

package/README.md

@@ -73,6 +73,27 @@ Details: [docs/ARCHITECTURE.md §4](./docs/ARCHITECTURE.md).
 `@modelcontextprotocol/{core,server,client}` v2 — and on both the high-level `McpServer` and the
 low-level `Server`. Shapes are detected at runtime, so neither major is a dependency here.
 
+### Sessions and client identity on a v2 server
+
+Protocol revision is a property of each **request**, not of the server: a v2 server serves both
+`2025-11-25` and `2026-07-28` traffic, and the SDK is instrumented once for both.
+
+- **On `2026-07-28`** there is no `initialize` and no session header — the revision removed
+  protocol-level sessions, and this SDK will not mint one. Session correlation therefore comes from
+  `enableConversationId`, which is **opt-in**. Without it every request is its own `$session_id`.
+- **On `2025-11-25`**, the session id and the client's name and version are exchanged once at
+  `initialize`. If your server builds a fresh `McpServer` per HTTP request — which
+  `createMcpHandler` does by default — the instance serving a later `tools/call` never saw that
+  handshake. The SDK bridges it by minting the `Mcp-Session-Id` token described above, which the
+  client replays on every request.
+
+  **That token only reaches the client if the transport builds response headers _after_ the handler
+  runs.** `@rekog/mcp-nest` with `enableJsonResponse: true` does; `createMcpHandler`'s legacy leg
+  does not, and there is no setting we can reach from inside the server. On that leg, expect
+  `$mcp_client_name` and `$mcp_client_version` to be absent for `2025-11-25` traffic — the protocol
+  version still arrives, because clients send it on the `MCP-Protocol-Version` header of every
+  request.
+
 ### Reading request headers in a callback
 
 If your `identify`, `intentFallback`, `eventProperties` or `beforeSend` reads HTTP headers, it has
@@ -95,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":"AAKA,OAAO,KAAK,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,aAAa,EAId,MAAM,UAAU,CAAA;AAcjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AASxC;;;;;;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;AAE3E,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;;;;OAIG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAA;IACjC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CA8DnF;AAiOD;;;;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,CAmElC;AAsFD,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,CA4DlB"}

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 {
@@ -69,13 +70,14 @@ async function captureToolCall(params) {
         throw error;
     }
     const finalResult = applyConversationInstructions(preparedEvent?.event ?? null, result, conversation, ownership);
-    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError);
+    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError, result);
     return finalResult;
 }
 function getActiveAnalyticsParameterOwnership(data, toolName, override, isMissingCapabilityTool) {
     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,7 +95,7 @@ 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);
@@ -113,7 +115,7 @@ 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);
         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
@@ -140,14 +142,14 @@ function applyConversationInstructions(event, result, conversation, ownership) {
     if (!delivered && conversation.minted && event) event.conversationId = void 0;
     return updated;
 }
-function publishSuccessfulToolEvent(server, preparedEvent, result, startTime, logger, takeCapturedError) {
+function publishSuccessfulToolEvent(server, preparedEvent, result, startTime, logger, takeCapturedError, resultBeforeInstructions) {
     if (!preparedEvent) return;
     const { event, requestAttribution } = preparedEvent;
     try {
         if ((0, external_tracing_helpers_js_namespaceObject.isToolResultError)(result)) {
             event.isError = true;
             const capturedError = takeCapturedError?.();
-            event.error = (0, external_exceptions_js_namespaceObject.captureException)(capturedError ?? result);
+            event.error = (0, external_exceptions_js_namespaceObject.captureException)(capturedError ?? resultBeforeInstructions ?? result);
         } else event.isError = false;
         event.response = result;
         event.duration = Date.now() - startTime.getTime();
@@ -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);
@@ -329,6 +329,7 @@ function mintStatelessSessionOnInitialize(server, data, request, extra) {
     try {
         const headers = (0, external_request_headers_js_namespaceObject.getRequestHeaders)(extra);
         if (!headers) return;
+        if ((0, external_session_js_namespaceObject.isModernEraRequest)(request, extra, server)) return;
         if ((0, external_session_token_js_namespaceObject.readMcpSessionHeader)(headers)) return;
         const transport = server.transport;
         if (!transport || extra?.sessionId || transport.sessionId) return;

package/dist/extensions/instrumentation.mjs

@@ -12,7 +12,7 @@ import { getServerTrackingData, handleIdentify, setServerTrackingData, withIdent
 import { buildCapturedMcpParameters } from "./mcp-payloads.mjs";
 import { readRequestHandlerMethod } from "./mcp-sdk-compat.mjs";
 import { getRequestHeaders } from "./request-headers.mjs";
-import { getSessionId, getSessionInfo, newSessionId } from "./session.mjs";
+import { getSessionId, getSessionInfo, isModernEraRequest, newSessionId } from "./session.mjs";
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from "./session-token.mjs";
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from "./tools.mjs";
 import { applyResolvedMetadata, isToolResultError } from "./tracing-helpers.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 {
@@ -33,13 +34,14 @@ async function captureToolCall(params) {
         throw error;
     }
     const finalResult = applyConversationInstructions(preparedEvent?.event ?? null, result, conversation, ownership);
-    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError);
+    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError, result);
     return finalResult;
 }
 function getActiveAnalyticsParameterOwnership(data, toolName, override, isMissingCapabilityTool) {
     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,7 +59,7 @@ 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);
@@ -77,7 +79,7 @@ async function prepareToolCallEvent(server, data, request, downstreamRequest, ex
         stampClientIdentity(event, request, extra, server);
         stampTransportIdentity(event, extra);
         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
@@ -104,14 +106,14 @@ function applyConversationInstructions(event, result, conversation, ownership) {
     if (!delivered && conversation.minted && event) event.conversationId = void 0;
     return updated;
 }
-function publishSuccessfulToolEvent(server, preparedEvent, result, startTime, logger, takeCapturedError) {
+function publishSuccessfulToolEvent(server, preparedEvent, result, startTime, logger, takeCapturedError, resultBeforeInstructions) {
     if (!preparedEvent) return;
     const { event, requestAttribution } = preparedEvent;
     try {
         if (isToolResultError(result)) {
             event.isError = true;
             const capturedError = takeCapturedError?.();
-            event.error = captureException(capturedError ?? result);
+            event.error = captureException(capturedError ?? resultBeforeInstructions ?? result);
         } else event.isError = false;
         event.response = result;
         event.duration = Date.now() - startTime.getTime();
@@ -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);
@@ -293,6 +293,7 @@ function mintStatelessSessionOnInitialize(server, data, request, extra) {
     try {
         const headers = getRequestHeaders(extra);
         if (!headers) return;
+        if (isModernEraRequest(request, extra, server)) return;
         if (readMcpSessionHeader(headers)) return;
         const transport = server.transport;
         if (!transport || extra?.sessionId || transport.sessionId) return;

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/extensions/session.d.ts

@@ -1,4 +1,28 @@
-import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPServerLike, SessionInfo } from '../types';
+import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, MCPServerLike, SessionInfo } from '../types';
+/**
+ * The revision that removed protocol-level sessions. A request declaring this or
+ * anything later must not be answered with an `Mcp-Session-Id`.
+ *
+ * Compared as a string, which is safe and stable because MCP revisions are
+ * ISO dates: any future revision sorts above this one and is treated as modern,
+ * which is the right default — sessions were removed, not re-added.
+ */
+export declare const MODERN_PROTOCOL_REVISION = "2026-07-28";
+/**
+ * Whether *this request* is governed by 2026-07-28 or later.
+ *
+ * Era is a property of the request, never of the installed SDK: one v2 server
+ * serves both, request by request, and v2's exported `LATEST_PROTOCOL_VERSION`
+ * still reads `2025-11-25`. So the version is resolved from the request itself —
+ * an `initialize` body declares the version it is asking for, and every other
+ * request carries it in the envelope, `_meta`, or the `MCP-Protocol-Version`
+ * header — and only then compared.
+ *
+ * Unknown means legacy. A request that declares nothing is a v1 client on a
+ * transport that has always had a session header, and taking it away from them
+ * would be the regression.
+ */
+export declare function isModernEraRequest(request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra, server?: MCPServerLike): boolean;
 export declare function newSessionId(): string;
 /**
  * Derives the SDK session id deterministically from the MCP sessionId, so the

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AAQjB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,CAAC,EAAE,6BAA6B,EACrC,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAgCR;AAuED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAmCb"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,cAAc,EACd,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AASjB;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAA;AAcpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,EACrC,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAYT;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,CAAC,EAAE,6BAA6B,EACrC,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAgCR;AAuED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAmCb"}

package/dist/extensions/session.js

@@ -24,18 +24,35 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    isModernEraRequest: ()=>isModernEraRequest,
     deriveSessionIdFromConversation: ()=>deriveSessionIdFromConversation,
-    getSessionId: ()=>getSessionId,
+    newSessionId: ()=>newSessionId,
+    MODERN_PROTOCOL_REVISION: ()=>MODERN_PROTOCOL_REVISION,
     deriveSessionIdFromMCPSession: ()=>deriveSessionIdFromMCPSession,
-    getSessionInfo: ()=>getSessionInfo,
-    newSessionId: ()=>newSessionId
+    getSessionId: ()=>getSessionId,
+    getSessionInfo: ()=>getSessionInfo
 });
 const external_version_js_namespaceObject = require("../version.js");
 const external_constants_js_namespaceObject = require("./constants.js");
 const external_ids_js_namespaceObject = require("./ids.js");
+const external_client_identity_js_namespaceObject = require("./client-identity.js");
 const external_internal_js_namespaceObject = require("./internal.js");
 const external_request_headers_js_namespaceObject = require("./request-headers.js");
 const external_session_token_js_namespaceObject = require("./session-token.js");
+const MODERN_PROTOCOL_REVISION = '2026-07-28';
+const REVISION_SHAPE = /^\d{4}-\d{2}-\d{2}$/;
+const DRAFT_REVISION = 'draft';
+function isModernEraRequest(request, extra, server) {
+    const requested = request.params?.protocolVersion;
+    const version = ('string' == typeof requested && requested.length > 0 ? requested : void 0) ?? (0, external_client_identity_js_namespaceObject.resolveClientIdentity)({
+        request,
+        extra,
+        server
+    })?.protocolVersion;
+    if (!version) return false;
+    if (version === DRAFT_REVISION) return true;
+    return REVISION_SHAPE.test(version) && version >= MODERN_PROTOCOL_REVISION;
+}
 function newSessionId() {
     return (0, external_ids_js_namespaceObject.newPrefixedId)('ses');
 }
@@ -111,16 +128,20 @@ function getSessionInfo(server, data, sessionId) {
         ...sessionInfo
     };
 }
+exports.MODERN_PROTOCOL_REVISION = __webpack_exports__.MODERN_PROTOCOL_REVISION;
 exports.deriveSessionIdFromConversation = __webpack_exports__.deriveSessionIdFromConversation;
 exports.deriveSessionIdFromMCPSession = __webpack_exports__.deriveSessionIdFromMCPSession;
 exports.getSessionId = __webpack_exports__.getSessionId;
 exports.getSessionInfo = __webpack_exports__.getSessionInfo;
+exports.isModernEraRequest = __webpack_exports__.isModernEraRequest;
 exports.newSessionId = __webpack_exports__.newSessionId;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "MODERN_PROTOCOL_REVISION",
     "deriveSessionIdFromConversation",
     "deriveSessionIdFromMCPSession",
     "getSessionId",
     "getSessionInfo",
+    "isModernEraRequest",
     "newSessionId"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/extensions/session.mjs

@@ -1,9 +1,24 @@
-import { version } from "../version.mjs";
+import { version as external_version_mjs_version } from "../version.mjs";
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from "./constants.mjs";
 import { deterministicPrefixedId, newPrefixedId } from "./ids.mjs";
+import { resolveClientIdentity } from "./client-identity.mjs";
 import { getServerTrackingData, setServerTrackingData } from "./internal.mjs";
 import { getRequestHeaders } from "./request-headers.mjs";
 import { decodeSessionId, readMcpSessionHeader } from "./session-token.mjs";
+const MODERN_PROTOCOL_REVISION = '2026-07-28';
+const REVISION_SHAPE = /^\d{4}-\d{2}-\d{2}$/;
+const DRAFT_REVISION = 'draft';
+function isModernEraRequest(request, extra, server) {
+    const requested = request.params?.protocolVersion;
+    const version = ('string' == typeof requested && requested.length > 0 ? requested : void 0) ?? resolveClientIdentity({
+        request,
+        extra,
+        server
+    })?.protocolVersion;
+    if (!version) return false;
+    if (version === DRAFT_REVISION) return true;
+    return REVISION_SHAPE.test(version) && version >= MODERN_PROTOCOL_REVISION;
+}
 function newSessionId() {
     return newPrefixedId('ses');
 }
@@ -62,7 +77,7 @@ function getSessionInfo(server, data, sessionId) {
     const sessionInfo = {
         ipAddress: void 0,
         sdkLanguage: 'TypeScript',
-        sdkVersion: version,
+        sdkVersion: external_version_mjs_version,
         serverName: server._serverInfo?.name,
         serverVersion: server._serverInfo?.version,
         clientName: clientInfo?.name,
@@ -79,4 +94,4 @@ function getSessionInfo(server, data, sessionId) {
         ...sessionInfo
     };
 }
-export { deriveSessionIdFromConversation, deriveSessionIdFromMCPSession, getSessionId, getSessionInfo, newSessionId };
+export { MODERN_PROTOCOL_REVISION, deriveSessionIdFromConversation, deriveSessionIdFromMCPSession, getSessionId, getSessionInfo, isModernEraRequest, newSessionId };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.11.3";
+export declare const version = "0.11.5";
 //# 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.3';
+const version = '0.11.5';
 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.3';
+const version = '0.11.5';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "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",
@@ -41,7 +41,7 @@
     "jest": "29.7.0",
     "zod": "^3.25.0",
     "@posthog-tooling/tsconfig-base": "1.1.1",
-    "posthog-node": "^5.48.1"
+    "posthog-node": "^5.49.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.26.0",

package/src/extensions/instrumentation.ts

@@ -35,7 +35,7 @@ import type { LoggerFn } from './logger'
 import { buildCapturedMcpParameters } from './mcp-payloads'
 import { readRequestHandlerMethod } from './mcp-sdk-compat'
 import { getRequestHeaders } from './request-headers'
-import { getSessionId, getSessionInfo, newSessionId } from './session'
+import { getSessionId, getSessionInfo, isModernEraRequest, newSessionId } from './session'
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from './session-token'
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from './tools'
 import { applyResolvedMetadata, isToolResultError } from './tracing-helpers'
@@ -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)
@@ -139,7 +148,9 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
   }
 
   const finalResult = applyConversationInstructions(preparedEvent?.event ?? null, result, conversation, ownership)
-  publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError)
+  // `result`, not `finalResult`: the error is read from what the tool produced,
+  // before the conversation handle was written into it. See below.
+  publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError, result)
   return finalResult
 }
 
@@ -148,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
@@ -197,7 +217,8 @@ 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)
@@ -235,7 +256,7 @@ async function prepareToolCallEvent(
     stampTransportIdentity(event, extra)
 
     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(
@@ -288,13 +309,26 @@ function applyConversationInstructions(
   return updated
 }
 
+/**
+ * @param result - what the caller receives, conversation handle included.
+ * @param resultBeforeInstructions - the same result as the tool produced it.
+ *
+ * The two differ once `enableConversationId` mints a handle, and the difference
+ * matters for errors. A tool that fails returns its message in `content`, and on
+ * MCP SDK v2 that flattened `isError` result is the only description of the
+ * failure we get — the throw never reaches our callback wrapper. Reading the
+ * error off the *delivered* result would therefore append the prompt-back to it,
+ * putting a fresh uuid inside `$mcp_error_message` on every failed call and
+ * splitting one recurring failure into as many groups as there were calls.
+ */
 function publishSuccessfulToolEvent(
   server: MCPServerLike,
   preparedEvent: PreparedToolEvent | null,
   result: unknown,
   startTime: Date,
   logger: LoggerFn,
-  takeCapturedError?: () => unknown
+  takeCapturedError?: () => unknown,
+  resultBeforeInstructions?: unknown
 ): void {
   if (!preparedEvent) {
     return
@@ -304,7 +338,7 @@ function publishSuccessfulToolEvent(
     if (isToolResultError(result)) {
       event.isError = true
       const capturedError = takeCapturedError?.()
-      event.error = captureException(capturedError ?? result)
+      event.error = captureException(capturedError ?? resultBeforeInstructions ?? result)
     } else {
       event.isError = false
     }
@@ -496,27 +530,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,
@@ -525,12 +571,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) {
@@ -541,15 +588,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(
@@ -580,7 +627,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
@@ -622,7 +669,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}`
@@ -699,6 +747,14 @@ function mintStatelessSessionOnInitialize(
     if (!headers) {
       return undefined // not an HTTP transport (stdio/in-memory) — nothing to mint into
     }
+    // 2026-07-28 removed sessions from the protocol: a server MUST NOT mint or
+    // echo `Mcp-Session-Id` under it. Today that era never reaches here anyway,
+    // because it has no `initialize` — but relying on that is relying on an SDK
+    // routing detail to keep us spec-compliant, so the era is asked directly.
+    // Per request, never per server: the same v2 server serves both.
+    if (isModernEraRequest(request, extra, server)) {
+      return undefined
+    }
     if (readMcpSessionHeader(headers)) {
       return undefined // client already replays a session id (ours or the transport's)
     }

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/extensions/session.ts

@@ -7,17 +7,73 @@ import { version } from '../version'
 import type {
   CompatibleRequestHandlerExtra,
   MCPAnalyticsData,
+  MCPRequestLike,
   MCPServerLike,
   ServerClientInfoLike,
   SessionInfo,
 } from '../types'
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from './constants'
 import { deterministicPrefixedId, newPrefixedId } from './ids'
+import { resolveClientIdentity } from './client-identity'
 import { getServerTrackingData, setServerTrackingData } from './internal'
 import { getRequestHeaders } from './request-headers'
 import { decodeSessionId, readMcpSessionHeader } from './session-token'
 import type { SessionTokenPayload } from './session-token'
 
+/**
+ * The revision that removed protocol-level sessions. A request declaring this or
+ * anything later must not be answered with an `Mcp-Session-Id`.
+ *
+ * Compared as a string, which is safe and stable because MCP revisions are
+ * ISO dates: any future revision sorts above this one and is treated as modern,
+ * which is the right default — sessions were removed, not re-added.
+ */
+export const MODERN_PROTOCOL_REVISION = '2026-07-28'
+
+/**
+ * Revisions are ISO dates, and only a date-shaped token may be compared as one.
+ * Without this the comparison is lexicographic over arbitrary input, so any
+ * string starting above `'2'` — every junk value beginning with a letter —
+ * sorts as modern and silently loses the session header. Unknown must mean
+ * legacy, so anything that is not a date is not compared at all.
+ */
+const REVISION_SHAPE = /^\d{4}-\d{2}-\d{2}$/
+
+/** The spec's rolling draft sits ahead of every dated revision, sessions included. */
+const DRAFT_REVISION = 'draft'
+
+/**
+ * Whether *this request* is governed by 2026-07-28 or later.
+ *
+ * Era is a property of the request, never of the installed SDK: one v2 server
+ * serves both, request by request, and v2's exported `LATEST_PROTOCOL_VERSION`
+ * still reads `2025-11-25`. So the version is resolved from the request itself —
+ * an `initialize` body declares the version it is asking for, and every other
+ * request carries it in the envelope, `_meta`, or the `MCP-Protocol-Version`
+ * header — and only then compared.
+ *
+ * Unknown means legacy. A request that declares nothing is a v1 client on a
+ * transport that has always had a session header, and taking it away from them
+ * would be the regression.
+ */
+export function isModernEraRequest(
+  request: MCPRequestLike,
+  extra?: CompatibleRequestHandlerExtra,
+  server?: MCPServerLike
+): boolean {
+  const requested = request.params?.protocolVersion
+  const version =
+    (typeof requested === 'string' && requested.length > 0 ? requested : undefined) ??
+    resolveClientIdentity({ request, extra, server })?.protocolVersion
+  if (!version) {
+    return false
+  }
+  if (version === DRAFT_REVISION) {
+    return true
+  }
+  return REVISION_SHAPE.test(version) && version >= MODERN_PROTOCOL_REVISION
+}
+
 export function newSessionId(): string {
   return newPrefixedId('ses')
 }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.11.3'
+export const version = '0.11.5'