@posthog/mcp 0.10.8 → 0.11.0

package/src/extensions/compatibility.ts

@@ -21,26 +21,22 @@ type ServerRecord = Record<string, unknown>
  * - Server info structure
  */
 
-// Function to log compatibility information
 export function logCompatibilityWarning(logger: LoggerFn): void {
   logger(
     'PostHog MCP analytics SDK Compatibility: This version only supports Model Context Protocol TypeScript SDK v1.11 and above. Please upgrade if using an older version.'
   )
 }
 
-// Check if server has high-level structure (wrapper with .server property)
 export function isHighLevelServer(server: unknown): server is ServerRecord & { server: ServerRecord } {
   return (
     !!server && typeof server === 'object' && 'server' in server && !!server.server && typeof server.server === 'object'
   )
 }
 
-// Check if server has low-level structure (no .server property)
 export function isLowLevelServer(server: unknown): server is ServerRecord {
   return !!server && typeof server === 'object' && !('server' in server)
 }
 
-// Type guard function that validates server compatibility and returns typed server
 export function isCompatibleServerType(server: unknown, logger: LoggerFn): MCPServerLike | HighLevelMCPServerLike {
   if (!server || typeof server !== 'object') {
     logCompatibilityWarning(logger)
@@ -50,7 +46,6 @@ export function isCompatibleServerType(server: unknown, logger: LoggerFn): MCPSe
   }
 
   if (isHighLevelServer(server)) {
-    // Validate high-level server requirements
     if (!server._registeredTools || typeof server._registeredTools !== 'object') {
       logCompatibilityWarning(logger)
       throw new Error(
@@ -64,18 +59,15 @@ export function isCompatibleServerType(server: unknown, logger: LoggerFn): MCPSe
       )
     }
 
-    // Validate the underlying low-level server
     const targetServer = server.server
     validateLowLevelServer(targetServer, logger)
 
     return server as unknown as HighLevelMCPServerLike
   }
-  // Direct low-level server validation
   validateLowLevelServer(server, logger)
   return server as MCPServerLike
 }
 
-// Helper function to validate low-level server requirements
 function validateLowLevelServer(server: unknown, logger: LoggerFn): void {
   if (!server || typeof server !== 'object') {
     logCompatibilityWarning(logger)
@@ -100,7 +92,6 @@ function validateLowLevelServer(server: unknown, logger: LoggerFn): void {
     )
   }
 
-  // Validate that _requestHandlers contains functions with compatible signatures
   if (typeof serverRecord._requestHandlers.get !== 'function') {
     logCompatibilityWarning(logger)
     throw new Error(

package/src/extensions/constants.ts

@@ -38,6 +38,7 @@ export type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof t
 
 export const PostHogMCPAnalyticsProperty = {
   ClientName: '$mcp_client_name',
+  ClientUserAgent: '$mcp_client_user_agent',
   ClientVersion: '$mcp_client_version',
   ConversationId: '$mcp_conversation_id',
   DurationMs: '$mcp_duration_ms',
@@ -58,6 +59,7 @@ export const PostHogMCPAnalyticsProperty = {
   ToolCategory: '$mcp_tool_category',
   ToolDescription: '$mcp_tool_description',
   ToolName: '$mcp_tool_name',
+  VendorClient: '$mcp_vendor_client',
 } as const
 
 export type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof typeof PostHogMCPAnalyticsProperty]

package/src/extensions/context-parameters.ts

@@ -41,7 +41,6 @@ export function addContextParameterToTool<TTool extends ContextInjectableTool>(
   contextDescriptionOverride?: string,
   logger: LoggerFn = log
 ): TTool {
-  // Create a shallow copy of the tool to avoid modifying the original
   const modifiedTool = { ...tool }
   const toolName = tool.name || 'unknown'
   const schema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema | undefined
@@ -55,10 +54,6 @@ export function addContextParameterToTool<TTool extends ContextInjectableTool>(
     return modifiedTool
   }
 
-  // Note: If additionalProperties is false, we'll need to remove that constraint
-  // when adding context, otherwise the schema would be invalid. We handle this
-  // after the deep copy below.
-
   if (!modifiedTool.inputSchema) {
     modifiedTool.inputSchema = {
       type: 'object',
@@ -69,29 +64,26 @@ export function addContextParameterToTool<TTool extends ContextInjectableTool>(
 
   const contextDescription = contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION
 
-  // Deep copy the inputSchema to avoid mutations
+  // Deep copy: the server may reuse or freeze the schema object it handed us.
   modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as AnalyticsInjectableJsonSchema
 
   const inputSchema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema
 
-  // Ensure properties object exists
   if (!inputSchema.properties) {
     inputSchema.properties = {}
   }
 
-  // Handle additionalProperties: false - must remove this constraint since we're adding context
-  // The MCP SDK adds this constraint when converting Zod schemas to JSON Schema
+  // The MCP SDK emits `additionalProperties: false` when converting Zod schemas;
+  // left in place it would make the injected `context` key invalid.
   if (inputSchema.additionalProperties === false) {
     inputSchema.additionalProperties = undefined
   }
 
-  // Add context property
   inputSchema.properties.context = {
     type: 'string',
     description: contextDescription,
   }
 
-  // Add context to required array
   if (Array.isArray(inputSchema.required)) {
     if (!inputSchema.required.includes('context')) {
       inputSchema.required.push('context')

package/src/extensions/conversation-id.ts

@@ -102,20 +102,9 @@ export type ConversationIdResolution =
  * derivation is deterministic so that two pods agree — which also means two
  * *callers* sending the same string land in the same session. The strings agents
  * invent are not random (`conv-1`, `1`, `session`), so trusting them verbatim
- * would silently merge unrelated conversations, potentially across users.
- *
- * A compliant agent echoes the uuidv7 we minted and is unaffected. Anything else
- * is treated exactly as if the handle were absent: mint, and prompt back. Shape
+ * would silently merge unrelated conversations, potentially across users. Shape
  * rather than a registry of issued ids, because a per-request server has no
- * memory of what it minted.
- *
- * This narrows the problem, it does not prove provenance: a caller supplying a
- * well-formed uuidv7 is trusted, so two that pick the *same* one still merge. That
- * residue is far smaller than the case it replaces — an agent ignoring the
- * parameter description reaches for `conv-1` or `1`, not a conforming uuidv7 — and
- * closing it needs a signed handle, i.e. a secret shared by every pod. Worth doing
- * if this ever anchors something security-bearing; `$session_id` is an analytics
- * grouping key, so it does not today.
+ * memory of what it minted. Residual risk and why it's accepted: ADR-0004.
  */
 export function resolveConversationId(enabled: boolean, args: unknown): ConversationIdResolution {
   if (!enabled) {
@@ -123,10 +112,9 @@ export function resolveConversationId(enabled: boolean, args: unknown): Conversa
   }
   const supplied = extractConversationId(args)
   if (supplied && MINTED_CONVERSATION_ID.test(supplied)) {
-    // Lowercased because the shape test is case-insensitive but the hash behind
-    // `$session_id` is not. Some hosts normalise uuids to uppercase, and an
-    // uppercased echo of our own handle would otherwise clear the gate and then
-    // land in a different session than the call that minted it.
+    // Lowercased: the shape test is case-insensitive but the hash behind
+    // `$session_id` is not, so an uppercased echo (some hosts normalise uuids)
+    // would land in a different session than the call that minted it.
     return { minted: false, conversationId: supplied.toLowerCase() }
   }
   return { minted: true, conversationId: uuidv7() }

package/src/extensions/headers.ts

@@ -0,0 +1,52 @@
+/**
+ * The single place this package reads an HTTP request header.
+ *
+ * The MCP SDK hands us `IsomorphicHeaders` — a plain
+ * `Record<string, string | string[] | undefined>`, not a `Headers` instance — so
+ * values come out by bracket access rather than `.get()`. MCP SDK v2 plans to
+ * pass a real `Headers` object instead; funnelling every read through here keeps
+ * that migration a one-function change instead of a hunt for bracket lookups.
+ */
+
+/**
+ * Reads one header value out of an `IsomorphicHeaders` bag. `name` must be
+ * lower-cased: the HTTP transports build the bag with
+ * `Object.fromEntries(req.headers.entries())` and the Fetch spec lower-cases
+ * header names. A hand-rolled transport can still hand us mixed-case keys, so a
+ * case-insensitive scan backs up the direct lookup.
+ *
+ * Repeated headers arrive as an array — we take the first entry, since every
+ * header we read is single-valued by definition. Returns `undefined` for a
+ * missing, non-string, or blank value, and never throws: a malformed header from
+ * an untrusted client must not break the request it rode in on.
+ */
+export function readHeaderValue(headers: unknown, name: string): string | undefined {
+  if (!headers || typeof headers !== 'object') {
+    return undefined
+  }
+  const record = headers as Record<string, unknown>
+  let value = record[name]
+  if (value === undefined) {
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name)
+    value = key === undefined ? undefined : record[key]
+  }
+  return normalizeHeaderString(value)
+}
+
+/**
+ * Coerces one raw header value into a clean string, or `undefined`.
+ *
+ * Exported so the custom-dispatcher path can apply the same rules to values a host
+ * read off the request itself. Without it the two integration paths emit different
+ * properties for the *same* request: a whitespace-only header would survive as a junk
+ * value, and a repeated header would reach the wire as an array, because the
+ * downstream length cap passes non-strings through untouched.
+ */
+export function normalizeHeaderString(value: unknown): string | undefined {
+  const first = Array.isArray(value) ? value[0] : value
+  if (typeof first !== 'string') {
+    return undefined
+  }
+  const trimmed = first.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}

package/src/extensions/instrument-highlevel.ts

@@ -280,7 +280,6 @@ export function instrumentHighLevelServer(server: HighLevelMCPServerLike, logger
     const lowLevelServer = server.server
     const mcpAnalyticsData = getServerTrackingData(lowLevelServer)
 
-    // Patch already existing handlers, and patch setRequestHandler to capture dynamically created handlers.
     const handlers: Record<string, HandlerPatch> = {
       initialize: (trackedServer, originalHandler, request, extra) =>
         handleInitializeRequest(trackedServer, originalHandler, request, extra, logger),

package/src/extensions/instrument-lowlevel.ts

@@ -3,7 +3,6 @@
 // Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
-import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import type { CompatibleRequestHandlerExtra, MCPRequestLike, MCPServerLike } from '../types'
 import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
@@ -13,6 +12,7 @@ import {
   handleInitializeRequest,
   handleListToolsRequest,
   patchRequestHandlers,
+  registerFallbackRequestHandler,
   captureToolCall,
   isToolAdvertised,
   type HandlerPatch,
@@ -32,25 +32,24 @@ type MCPRequestExtra = Parameters<MCPRequestHandler>[1]
  */
 export function instrumentLowLevelServer(server: MCPServerLike, logger: LoggerFn): void {
   try {
-    // Patch already existing handlers, and patch setRequestHandler to capture dynamically created handlers.
     const hadCallToolHandler = server._requestHandlers.has('tools/call')
+    const traceToolCall: HandlerPatch = (server, originalHandler, request, extra) =>
+      handleToolCallRequest(server, originalHandler, request, extra, logger)
     const handlers: Record<string, HandlerPatch> = {
       initialize: (server, originalHandler, request, extra) =>
         handleInitializeRequest(server, originalHandler, request, extra, logger),
       'tools/list': (server, originalHandler, request, extra) =>
         handleListToolsRequest(server, originalHandler, request, extra, logger),
-      'tools/call': (server, originalHandler, request, extra) =>
-        handleToolCallRequest(server, originalHandler, request, extra, logger),
+      'tools/call': traceToolCall,
     }
     patchRequestHandlers(server, handlers)
 
     if (!hadCallToolHandler) {
-      // Register a raw fallback through the patched setter so reportMissing works
-      // even before an application dispatcher is attached. A later registration
-      // replaces it and is wrapped by patchRequestHandlers.
-      server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        throw new Error(`Unknown tool: ${request.params?.name || 'unknown'}`)
-      })
+      // Register a raw fallback so reportMissing works even before an application
+      // dispatcher is attached. A later registration replaces it and is wrapped by
+      // the patched setRequestHandler. Written into the handler map directly — see
+      // registerFallbackRequestHandler for why the SDK setter is the wrong door.
+      registerFallbackRequestHandler(server, 'tools/call', unknownToolHandler, traceToolCall)
     }
   } catch (error) {
     logger(`Warning: Failed to setup tool call instrumentation - ${error}`)
@@ -58,6 +57,11 @@ export function instrumentLowLevelServer(server: MCPServerLike, logger: LoggerFn
   }
 }
 
+/** Stands in for an application dispatcher that has not been attached yet. */
+async function unknownToolHandler(request: MCPRequestLike): Promise<never> {
+  throw new Error(`Unknown tool: ${request.params?.name || 'unknown'}`)
+}
+
 async function handleToolCallRequest(
   server: MCPServerLike,
   originalCallToolHandler: MCPRequestHandler | undefined,

package/src/extensions/instrumentation.ts

@@ -24,6 +24,7 @@ import {
   resolveConversationId,
 } from './conversation-id'
 import { stampMetaClientInfo } from './client-identity'
+import { stampTransportIdentity } from './transport-identity'
 import { addInstructionsToOutputSchemas, mirrorInstructionsIntoStructuredContent } from './output-instructions'
 import { captureEvent } from './capture'
 import { MCPAnalyticsEventType } from './event-types'
@@ -32,7 +33,7 @@ import { resolveToolCallIntent, setEventIntent, setExplicitContextIntent } from
 import { getServerTrackingData, handleIdentify, setServerTrackingData, withIdentity } from './internal'
 import type { LoggerFn } from './logger'
 import { buildCapturedMcpParameters } from './mcp-payloads'
-import { getLiteralValue, getObjectShape } from './mcp-sdk-compat'
+import { readRequestHandlerMethod } from './mcp-sdk-compat'
 import { getSessionId, getSessionInfo, newSessionId } from './session'
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from './session-token'
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from './tools'
@@ -157,22 +158,13 @@ function getActiveAnalyticsParameterOwnership(
   return {
     context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
     conversationId: data.options.enableConversationId === true && ownership?.conversationId === true,
-    // Deliberately read off `listed`, never the override. This asks whether
-    // `tools/list` actually declared `_mcp_instructions`, and only the advertised
-    // JSON Schema can answer it — an override is built from the live registry,
-    // which on the high-level path holds Zod.
-    //
-    // The cache is per-instance, so this is not merely "before the first
-    // `tools/list`": an instance that never serves a listing never writes the
-    // mirror at all. That is the per-request server pattern — `tools/list` lands
-    // on one instance, `tools/call` on a cold one — where the handle falls back
-    // to the `content` block and a structuredContent-only client misses it.
-    //
-    // Failing closed is deliberate. Writing a key the advertised schema did not
-    // declare fails the *entire* tool result under `additionalProperties: false`,
-    // so guessing costs the caller their result, while not guessing costs us one
-    // delivery channel. The fix is a process-scoped ownership cache, so a listing
-    // served by any instance answers for the rest — not a per-call guess.
+    // Deliberately read off `listed`, never the override: only the advertised
+    // JSON Schema can say whether `tools/list` declared `_mcp_instructions` (an
+    // override is built from the live registry, which holds Zod on the
+    // high-level path). An instance that never served a listing has no answer
+    // and fails closed — writing an undeclared key fails the customer's entire
+    // tool result under `additionalProperties: false`. See ADR-0004 for the
+    // per-request-instance gap this leaves and the planned fix.
     outputInstructions: data.options.enableConversationId === true && listed?.outputInstructions === true,
   }
 }
@@ -237,6 +229,9 @@ async function prepareToolCallEvent(
     // `_meta` on every request rather than at `initialize`; stamp them onto this
     // event now so concurrent requests can't cross-attribute it.
     stampMetaClientInfo(event, request)
+    // 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)
 
     await applyResolvedMetadata(event, data, request, extra)
     setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra))
@@ -250,19 +245,14 @@ async function prepareToolCallEvent(
 }
 
 /**
- * Delivers the conversation session handle back to the agent, over both channels a tool
- * result has:
+ * Delivers the conversation session handle back to the agent over both channels
+ * a tool result has: mirrored into `structuredContent` on every response (for
+ * tools whose output schema declares the key), and as a `content` text block on
+ * the minting response only. Why two channels and why those cadences: ADR-0004.
  *
- * - `structuredContent`, on *every* response for a tool whose output schema we
- *   declared the key on. Clients that read structured results never see the text
- *   block, and re-sending it each time lets an agent that dropped the session handle read
- *   it back.
- * - `content`, as a text block, only on the response that minted the session handle.
- *   Repeating it every call would put a `[SERVER]:` line in front of the user on
- *   every single tool result.
- *
- * If neither channel could carry a session handle we minted, the agent never received it,
- * so clear it off the event rather than showing analytics an id nobody has.
+ * If neither channel could carry a session handle we minted, the agent never
+ * received it, so clear it off the event rather than showing analytics an id
+ * nobody has.
  */
 function applyConversationInstructions(
   event: McpEvent | null,
@@ -364,13 +354,7 @@ export type HandlerPatch = (
   extra: CompatibleRequestHandlerExtra | undefined
 ) => Promise<unknown>
 
-/**
- * Applies the `patches` (keyed by method, e.g. `initialize`, `tools/list`) to the
- * handlers already registered, and patches `setRequestHandler` so matching
- * handlers registered later are patched too. The latter is what makes adapters
- * that register handlers post-construction work — e.g. `@rekog/mcp-nest` hands a
- * bare server to instrument() and only then registers its handlers.
- */
+/** Pre-patch handlers, kept so `isToolAdvertised` can query the raw listing. */
 const originalRequestHandlers = new WeakMap<MCPServerLike, Map<string, MCPRequestHandler>>()
 
 function rememberOriginalRequestHandler(
@@ -386,8 +370,45 @@ function rememberOriginalRequestHandler(
   handlers.set(handlerName, originalHandler)
 }
 
+/**
+ * Registers a synthetic fallback handler for `handlerName`, already wrapped in
+ * `patch`, by writing straight into `_requestHandlers` instead of going through
+ * `setRequestHandler`.
+ *
+ * Bypassing the SDK setter is deliberate, on three counts:
+ *
+ * - **Capability assertion.** `setRequestHandler` refuses a method the server
+ *   never declared a capability for, so instrumenting a low-level server built
+ *   without `capabilities.tools` used to throw `Server does not support tools`
+ *   and leave instrumentation half-applied. Our fallback is not a capability the
+ *   server offers — it exists only so a call for a tool nobody claims is still
+ *   captured — so the assertion has nothing to protect here.
+ * - **Schema validation.** The setter also wraps the handler in request/result
+ *   parsing, which a handler that can only ever throw `Unknown tool` never needs.
+ * - **Portability.** The setter's first argument is a Zod schema on SDK v1 and a
+ *   method string on v2; the map key is the same string on both, so this is the
+ *   one registration form that does not need to know which major it is talking
+ *   to — and it drops the last runtime `@modelcontextprotocol/sdk` import from
+ *   the shipped bundle.
+ */
+export function registerFallbackRequestHandler(
+  server: MCPServerLike,
+  handlerName: string,
+  fallbackHandler: MCPRequestHandler,
+  patch: HandlerPatch
+): void {
+  rememberOriginalRequestHandler(server, handlerName, fallbackHandler)
+  server._requestHandlers.set(handlerName, (request, extra) => patch(server, fallbackHandler, request, extra))
+}
+
+/**
+ * Applies the `patches` (keyed by method, e.g. `initialize`, `tools/list`) to the
+ * handlers already registered, and patches `setRequestHandler` so matching
+ * handlers registered later are patched too. The latter is what makes adapters
+ * that register handlers post-construction work — e.g. `@rekog/mcp-nest` hands a
+ * bare server to instrument() and only then registers its handlers.
+ */
 export function patchRequestHandlers(server: MCPServerLike, patches: Record<string, HandlerPatch>): void {
-  // Monkey patch existing handlers.
   for (const [handlerName, patch] of Object.entries(patches)) {
     const originalHandler = server._requestHandlers.get(handlerName)
     if (originalHandler) {
@@ -397,18 +418,31 @@ export function patchRequestHandlers(server: MCPServerLike, patches: Record<stri
   }
 
   // Monkey patch dynamically added handlers (registered after instrument()).
-  const originalSetRequestHandler = server.setRequestHandler.bind(server)
-  server.setRequestHandler = ((requestSchema: unknown, originalHandler: MCPRequestHandler) => {
-    const shape = getObjectShape(requestSchema)
-    const handlerName = shape?.method ? getLiteralValue(shape.method) : undefined
-    const patch = typeof handlerName === 'string' ? patches[handlerName] : undefined
-    if (!patch || typeof handlerName !== 'string') {
-      return originalSetRequestHandler(requestSchema, originalHandler)
+  //
+  // Variadic, and every argument is forwarded verbatim. The registration form is
+  // the SDK's business, not ours — only *that* a registration happened is ours.
+  // SDK v2 has a three-argument form for custom methods,
+  // `setRequestHandler(method, { params, result }, handler)`, and a two-parameter
+  // wrapper drops the handler: the SDK then sees the schemas object where the
+  // handler should be and throws `setRequestHandler: handler is required`, which
+  // takes down the host server rather than just our instrumentation.
+  const originalSetRequestHandler = server.setRequestHandler.bind(server) as (...args: unknown[]) => unknown
+  server.setRequestHandler = ((...args: unknown[]) => {
+    const handlerName = readRequestHandlerMethod(args[0])
+    // `hasOwnProperty`, not a bare index: `handlerName` is now an arbitrary
+    // caller-supplied string, and a custom method named `toString` would
+    // otherwise resolve to an inherited function and be treated as a patch.
+    const patch =
+      handlerName !== undefined && Object.prototype.hasOwnProperty.call(patches, handlerName)
+        ? patches[handlerName]
+        : undefined
+    if (handlerName === undefined || !patch) {
+      return originalSetRequestHandler(...args)
     }
 
     // Register first so the MCP SDK's request/result validation stays inside
     // our analytics wrapper, matching handlers that existed before instrument().
-    const result = originalSetRequestHandler(requestSchema, originalHandler)
+    const result = originalSetRequestHandler(...args)
     const registeredHandler = server._requestHandlers.get(handlerName)
     if (registeredHandler) {
       rememberOriginalRequestHandler(server, handlerName, registeredHandler)
@@ -475,6 +509,7 @@ export async function handleListToolsRequest(
     timestamp: startTime,
   }
   stampMetaClientInfo(event, request)
+  stampTransportIdentity(event, extra)
 
   if (data) {
     await applyResolvedMetadata(event, data, request, extra)
@@ -639,7 +674,7 @@ export function cacheToolCategories(cache: Map<string, string>, tools: ListTools
  * client name/version is lost after `initialize`. Fix: mint the
  * `Mcp-Session-Id` response header as a token carrying both. Clients replay
  * the header on every request, so any pod recovers them with no server-side
- * store (decoded in `getSessionId`).
+ * store (decoded in `getSessionId`). See ADR-0003.
  *
  * The header only reaches the wire when response headers are built after the
  * handler runs — StreamableHTTP with `enableJsonResponse: true`. SSE flushes
@@ -786,6 +821,7 @@ export async function handleInitializeRequest(
   // negotiated protocol version below overrides any `_meta` one); picks up client
   // info if a client also sends it in `_meta`.
   stampMetaClientInfo(event, request)
+  stampTransportIdentity(event, extra)
 
   await applyResolvedMetadata(event, data, request, extra)
 

package/src/extensions/internal.ts

@@ -15,6 +15,7 @@ import type {
 import { MCPAnalyticsEventType } from './event-types'
 import { captureEvent } from './capture'
 import { stampMetaClientInfo } from './client-identity'
+import { stampTransportIdentity } from './transport-identity'
 
 /**
  * Bounded LRU cache for session identities, capped at `maxSize` entries so a
@@ -153,6 +154,7 @@ export async function handleIdentify(
     timestamp: new Date(),
   }
   stampMetaClientInfo(identifyEvent, request)
+  stampTransportIdentity(identifyEvent, extra)
 
   try {
     const identityResult =
@@ -166,11 +168,10 @@ export async function handleIdentify(
       // was already announced by whichever pod handled `initialize`, so only the
       // handshake, or a genuine change a long-lived server observed, publishes
       // $identify. Every event still carries distinct_id/$set regardless, so
-      // person properties are never lost. Known gap: if identity is null at
-      // `initialize` but resolves later on a token session, that first $identify
-      // is suppressed too, so any pre-identify (anonymous) events aren't aliased
-      // onto the user. Inherent to statelessness (no pod knows a sibling already
-      // announced); revisit with the stateless-by-default rework.
+      // person properties are never lost. Known accepted gap (ADR-0003): an
+      // identity resolving only after `initialize` on a token session gets no
+      // standalone $identify, so its pre-identify events aren't aliased onto
+      // the user.
       const changed = previousIdentity !== undefined && !areIdentitiesEqual(previousIdentity, mergedIdentity)
       const firstSeen = previousIdentity === undefined
       const announcedAtInitialize =

package/src/extensions/mcp-sdk-compat.ts

@@ -143,6 +143,24 @@ export function getObjectShape(schema: unknown): Record<string, unknown> | undef
   return rawShape
 }
 
+/**
+ * Reads the method name a `setRequestHandler` registration is for.
+ *
+ * The two SDK majors disagree on what the first argument is: v1 passes the Zod
+ * schema for the request and carries the method as a literal on its shape, v2
+ * passes the method string itself. A registration we cannot name is one we
+ * cannot match against a patch — which is how a handler registered after
+ * `instrument()` on v2 ends up replacing our wrapper instead of being wrapped.
+ */
+export function readRequestHandlerMethod(requestSchema: unknown): string | undefined {
+  if (typeof requestSchema === 'string') {
+    return requestSchema
+  }
+  const shape = getObjectShape(requestSchema)
+  const method = shape?.method ? getLiteralValue(shape.method) : undefined
+  return typeof method === 'string' ? method : undefined
+}
+
 export function getLiteralValue(schema: unknown): unknown {
   if (!schema || typeof schema !== 'object') {
     return

package/src/extensions/output-instructions.ts

@@ -3,18 +3,16 @@ import { log } from './logger'
 import type { AnalyticsInjectableJsonSchema } from './analytics-parameters'
 
 /**
- * The `conversation_id` session handle reaches the agent as a text block appended to the
- * tool result. That block is invisible to any client that reads
- * `structuredContent` instead of `content` — which is what clients do whenever a
- * tool declares an `outputSchema`. Measured against Claude Code, correlation for
- * such tools drops to zero.
- *
- * The fix is to mirror the session handle into `structuredContent` as well, which this
- * module does in two halves that must stay in that order:
+ * Mirrors the `conversation_id` session handle into `structuredContent`, in two
+ * halves that must stay in that order:
  *
  *   1. declare `_mcp_instructions` on the tool's advertised `outputSchema`
  *   2. write it into the result's `structuredContent`
  *
+ * Needed because clients that read `structuredContent` — which they do whenever
+ * a tool declares an `outputSchema` — never see the `content` text block that
+ * carries the handle (ADR-0004).
+ *
  * The declaration is what makes the write safe. The MCP client ajv-validates
  * `structuredContent` against the schema from `tools/list`, and
  * `zod-to-json-schema` emits `additionalProperties: false` for a plain

package/src/extensions/posthog-events.ts

@@ -151,6 +151,14 @@ function addCommonEventProperties(event: Event, properties: Record<string, unkno
   if (event.clientVersion) {
     properties[PostHogMCPAnalyticsProperty.ClientVersion] = event.clientVersion
   }
+  // HTTP transports only, and only for the request that carried the header —
+  // stdio and in-memory servers simply never set these.
+  if (event.clientUserAgent) {
+    properties[PostHogMCPAnalyticsProperty.ClientUserAgent] = event.clientUserAgent
+  }
+  if (event.vendorClient) {
+    properties[PostHogMCPAnalyticsProperty.VendorClient] = event.vendorClient
+  }
   // Present on every event once negotiated at `initialize` (carried via
   // sessionInfo / the session token). Absent only before the handshake.
   if (event.protocolVersion) {
@@ -242,6 +250,12 @@ function buildExceptionEvent(event: Event): PostHogCaptureEvent {
   if (event.clientVersion) {
     properties[PostHogMCPAnalyticsProperty.ClientVersion] = event.clientVersion
   }
+  if (event.clientUserAgent) {
+    properties[PostHogMCPAnalyticsProperty.ClientUserAgent] = event.clientUserAgent
+  }
+  if (event.vendorClient) {
+    properties[PostHogMCPAnalyticsProperty.VendorClient] = event.vendorClient
+  }
   if (event.protocolVersion) {
     properties[PostHogMCPAnalyticsProperty.ProtocolVersion] = event.protocolVersion
   }