@posthog/mcp 0.10.9 → 0.11.0

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'
@@ -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(
@@ -417,8 +401,14 @@ export function registerFallbackRequestHandler(
   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) {
@@ -519,6 +509,7 @@ export async function handleListToolsRequest(
     timestamp: startTime,
   }
   stampMetaClientInfo(event, request)
+  stampTransportIdentity(event, extra)
 
   if (data) {
     await applyResolvedMetadata(event, data, request, extra)
@@ -683,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
@@ -830,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/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
   }

package/src/extensions/posthog-mcp.ts

@@ -19,6 +19,7 @@ import {
 } from './context-parameters'
 import { MCPAnalyticsEventType } from './event-types'
 import { captureException } from './exceptions'
+import { normalizeHeaderString } from './headers'
 import { applyMcpLibIdentity } from './lib-identity'
 import { log } from './logger'
 import { McpEventSink } from './sink'
@@ -72,10 +73,6 @@ export interface PostHogMCPOptions extends PostHogOptions {
  * ```
  */
 export class PostHogMCP extends PostHog {
-  // Reuses the shared sink so MCP events flow through the identical
-  // sanitize/truncate/fan-out pipeline as the `instrument()` path; the sink
-  // publishes via `this` (the inherited `capture()`), so the client's own
-  // `beforeSend` and batching apply.
   readonly #sink = new McpEventSink(this)
 
   // The get_more_tools name lives here (not on the per-call options) so that
@@ -85,7 +82,6 @@ export class PostHogMCP extends PostHog {
   constructor(apiKey: string, options: PostHogMCPOptions = {}) {
     super(apiKey, options)
     this.#missingCapabilityToolName = options.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
-    // Report `$lib: 'posthog-node-mcp'` instead of the inherited `posthog-node`.
     applyMcpLibIdentity(this)
   }
 
@@ -244,6 +240,12 @@ function baseEvent(eventType: MCPAnalyticsEventType, common: McpCaptureCommon):
     eventType,
     sessionId: common.sessionId,
     protocolVersion: common.protocolVersion,
+    // There is no `extra` on this path, so the host reads the request headers and
+    // passes them per capture — the SDK has no transport to read them from. Normalized
+    // with the same rules `instrument()` applies, so one request yields one set of
+    // properties whichever path captured it.
+    clientUserAgent: normalizeHeaderString(common.clientUserAgent),
+    vendorClient: normalizeHeaderString(common.vendorClient),
     timestamp: common.timestamp ?? new Date(),
     properties: common.properties,
     groups: common.groups,

package/src/extensions/session-token.ts

@@ -10,6 +10,8 @@
  * The token is unsigned: it holds only what the client already self-reports.
  */
 
+import { readHeaderValue } from './headers'
+
 export const MCP_SESSION_HEADER = 'mcp-session-id'
 
 /** What a session token carries. */
@@ -105,21 +107,7 @@ export function decodeSessionId(value: unknown): SessionTokenPayload | null {
  * transports lowercase header keys; the fallback scan covers hand-built extras.
  */
 export function readMcpSessionHeader(headers: unknown): string | undefined {
-  if (!headers || typeof headers !== 'object') {
-    return undefined
-  }
-  const record = headers as Record<string, unknown>
-  let value = record[MCP_SESSION_HEADER]
-  if (value === undefined) {
-    const key = Object.keys(record).find((k) => k.toLowerCase() === MCP_SESSION_HEADER)
-    value = key === undefined ? undefined : record[key]
-  }
-  const first = Array.isArray(value) ? value[0] : value
-  if (typeof first !== 'string') {
-    return undefined
-  }
-  const trimmed = first.trim()
-  return trimmed.length > 0 ? trimmed : undefined
+  return readHeaderValue(headers, MCP_SESSION_HEADER)
 }
 
 /**

package/src/extensions/session.ts

@@ -30,9 +30,10 @@ export function deriveSessionIdFromMCPSession(mcpSessionId: string): string {
 }
 
 /**
- * Derives the SDK session id from the agent's conversation handle. Deterministic
- * and unsalted on purpose: two pods that never met must agree on the session, and
- * the 2026-07-28 revision leaves them no shared state to agree through.
+ * Derives the SDK session id from the agent's conversation handle (ADR-0004).
+ * Deterministic and unsalted on purpose: two pods that never met must agree on
+ * the session, and the 2026-07-28 revision leaves them no shared state to agree
+ * through.
  *
  * Hashed rather than used verbatim so an MCP session can never collide with a
  * Session Replay id — a bare uuidv7 would render a "View recording" button that
@@ -69,26 +70,16 @@ export function getSessionId(
     throw new Error('Server tracking data not found')
   }
 
-  // 1. The agent's conversation handle. It outranks both steps below because it
-  // is the only id that survives reconnects, restarts, and the per-request
-  // server instances the 2026-07-28 revision introduces. Hashed rather than used
-  // verbatim so it can never collide with Session Replay ids.
-  //
-  // This returns instead of falling through to the shared-state writes at the
-  // end: the handle belongs to this one request, and persisting it would leak
-  // one chat's session onto a concurrent chat's `tools/list`.
-  //
-  // `lastActivity` therefore does not advance either, so a conversation that
-  // always echoes lets the in-memory fallback age past the inactivity timeout —
-  // and a later call carrying no handle rotates it. That is the honest reading:
-  // the fallback session really has been idle for that whole time.
+  // 1. The agent's conversation handle — the only id that survives reconnects,
+  // restarts, and the per-request server instances of the 2026-07-28 revision
+  // (ADR-0004). Returns before the shared-state writes at the end: the handle
+  // belongs to this one request, and persisting it (or advancing lastActivity)
+  // would leak one chat's session onto a concurrent chat's `tools/list`.
   if (conversationId) {
-    // The handle decides the *session*, but the request may still carry our token,
-    // and on a stateless instance that never processed `initialize` its payload is
-    // the only place client identity exists. Restore that before returning: the
-    // early return is about not persisting a session, not about ignoring what the
-    // request told us about the client. Without this, tool calls and `$identify`
-    // go out unattributed on exactly the deployments this branch exists for.
+    // The session comes from the handle, but on an instance that never processed
+    // `initialize` the request's token is still the only source of client
+    // identity — without this, tool calls and `$identify` go out unattributed
+    // on exactly the deployments this branch exists for.
     applyTokenClientIdentity(data, extra)
     return deriveSessionIdFromConversation(conversationId)
   }
@@ -110,14 +101,10 @@ export function getSessionId(
 /**
  * Restores the client name/version and protocol version baked into our token at
  * mint time, and hands the decoded token back so the caller can also take the
- * session id from it.
- *
- * Split out from step 2 because the two halves of the token have different
- * scopes. The session id it carries is per-chat, so a conversation-anchored
- * request must not adopt it. The client identity is per-connection — the same
- * client for every request on it — so a conversation-anchored request should,
- * and on a stateless instance that never saw `initialize` this is the only
- * source of it.
+ * session id from it. Split from step 2 because the token's two halves have
+ * different scopes: its session id is per-chat (a conversation-anchored request
+ * must not adopt it), its client identity is per-connection (every request on
+ * the connection should).
  */
 function applyTokenClientIdentity(
   data: MCPAnalyticsData,
@@ -139,9 +126,8 @@ function applyTokenClientIdentity(
  * issued. Returns undefined when the request carried neither, which is what
  * sends the caller on to 3.
  *
- * Both are 2025-11-25 mechanisms. The 2026-07-28 revision removed that header
- * outright — servers MUST NOT mint or echo it — so this entire step becomes
- * legacy-only once era detection lands.
+ * Both are 2025-11-25 mechanisms; the 2026-07-28 revision removed the header
+ * outright, so this step is legacy-only once era detection lands (ADR-0003).
  */
 function readSessionIdFromRequest(data: MCPAnalyticsData, extra?: CompatibleRequestHandlerExtra): string | undefined {
   // 2a. A token we minted at `initialize` and the client replayed. It rides the
@@ -203,8 +189,8 @@ export function getSessionInfo(
   const actorInfo = data?.identifiedSessions.get(sessionId ?? data.sessionId)
 
   const sessionInfo: SessionInfo = {
-    ipAddress: undefined, // grab from django
-    sdkLanguage: 'TypeScript', // hardcoded for now
+    ipAddress: undefined,
+    sdkLanguage: 'TypeScript',
     sdkVersion: version,
     serverName: server._serverInfo?.name,
     serverVersion: server._serverInfo?.version,

package/src/extensions/sink.ts

@@ -92,9 +92,8 @@ async function applyBeforeSend(
 }
 
 /**
- * Wraps a user-supplied `posthog-node` client. Runs every MCP event through the
- * sanitize → truncate pipeline, fans it out into the `$mcp_*` / `$exception`
- * events, applies `beforeSend`, and hands each to `posthog.capture()`.
+ * Wraps a user-supplied `posthog-node` client: runs every MCP event through
+ * {@link processMcpEvent} and hands each surviving payload to `posthog.capture()`.
  *
  * The SDK does not own the client lifecycle — the host application constructs
  * the `PostHog` instance and is responsible for `shutdown()` (matching
@@ -107,9 +106,8 @@ export class McpEventSink {
   ) {}
 
   /**
-   * Push an MCP event through the pipeline (sanitize → truncate → fan out →
-   * beforeSend → capture). Errors at any stage are logged and the event is
-   * dropped, never re-thrown into tool code.
+   * Errors at any stage are logged and the event is dropped, never re-thrown
+   * into tool code.
    */
   async capture(event: McpEvent, options: McpCaptureOptions): Promise<void> {
     const result = await processMcpEvent(event, options, this.logger)

package/src/extensions/tools.ts

@@ -36,15 +36,12 @@ export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAM
     },
     annotations: {
       title: 'Get More Tools',
-      // Doesn't mutate state on the MCP server
       readOnlyHint: true,
-      // Interacts with external entities because we store this in analytics
+      // Interacts with an external entity: the report lands in analytics.
       openWorldHint: true,
-      // A tool like `get_more_tools` would usually NOT be idempontent, but since we are
-      // only using this to keep track of missing tools/feedback/analytics, it is actually idempontent.
-      // It's also preferable to track it as idempontent to make agents more prone to call it proactively.
+      // Only records the gap, so repeat calls are harmless — and advertising it
+      // as idempotent makes agents more willing to call it proactively.
       idempotentHint: true,
-      // Never deletes any data from the MCP server
       destructiveHint: false,
     },
   }

package/src/extensions/transport-identity.ts

@@ -0,0 +1,94 @@
+import type { CompatibleRequestHandlerExtra, McpEvent } from '../types'
+import { readHeaderValue } from './headers'
+
+/**
+ * Transport-level client identity: the two request headers that say *which
+ * product* is calling, where `clientInfo` only says which client library is.
+ *
+ * MCP's own identity fields are too coarse to attribute usage to a surface. A
+ * vendor ships many products on one client: Anthropic reports
+ * `clientInfo.name = "claude-code"` from the CLI, the Agent SDK, the VS Code
+ * extension, the desktop app and more, so `$mcp_client_name` collapses all of
+ * them into one bucket. The distinguishing detail exists only in the User-Agent
+ * parenthetical — `claude-code/2.1.0 (cli)` vs `claude-code/2.1.0 (sdk-ts)` vs
+ * `claude-code/2.1.0 (claude-vscode)` — alongside vendor-specific headers like
+ * `x-anthropic-client`. Capturing them is the only way a server owner can tell
+ * their surfaces apart.
+ *
+ * We capture the raw strings and classify nothing. No vendor table, no product
+ * labels: friendly names are resolved at query time server-side, so labels can
+ * improve (and new surfaces can appear) without waiting on an SDK release, and
+ * there is exactly one resolver rather than one per installed SDK version.
+ *
+ * This is deliberately separate from `client-identity.ts`. That module reads the
+ * request body's `_meta` and therefore works on every transport, including stdio
+ * and in-memory. Headers exist only on HTTP transports, so everything here is a
+ * silent no-op elsewhere and those events stay byte-identical to before.
+ */
+
+/** Header carrying the client's product/surface, e.g. `claude-code/2.1.0 (cli)`. */
+export const CLIENT_USER_AGENT_HEADER = 'user-agent'
+
+/**
+ * Vendor-specific client header. Anthropic's clients send it alongside the
+ * User-Agent; it is captured verbatim as a second, independent signal rather
+ * than merged into one, so a query-time resolver can prefer whichever the
+ * vendor keeps stable.
+ */
+export const VENDOR_CLIENT_HEADER = 'x-anthropic-client'
+
+export interface TransportIdentity {
+  clientUserAgent?: string
+  vendorClient?: string
+}
+
+/**
+ * Reads the transport identity headers off `extra.requestInfo.headers`. Returns
+ * `undefined` when the request carries neither — including every stdio and
+ * in-memory request, which has no `requestInfo` at all. Never throws.
+ */
+export function readTransportIdentity(extra: CompatibleRequestHandlerExtra | undefined): TransportIdentity | undefined {
+  const headers = extra?.requestInfo?.headers
+  if (!headers) {
+    return undefined
+  }
+  const result: TransportIdentity = {}
+
+  const clientUserAgent = readHeaderValue(headers, CLIENT_USER_AGENT_HEADER)
+  if (clientUserAgent) {
+    result.clientUserAgent = clientUserAgent
+  }
+
+  const vendorClient = readHeaderValue(headers, VENDOR_CLIENT_HEADER)
+  if (vendorClient) {
+    result.vendorClient = vendorClient
+  }
+
+  return result.clientUserAgent || result.vendorClient ? result : undefined
+}
+
+/**
+ * Stamps the transport identity onto the event being built for *this* request,
+ * so it carries `$mcp_client_user_agent` and `$mcp_vendor_client`.
+ *
+ * Headers are per-request, so this writes to the event — a per-request object —
+ * and never to the server-wide `sessionInfo`. One instrumented server can
+ * multiplex concurrent requests from different clients, and caching a header
+ * into shared state would attribute one client's surface to another's event.
+ * `client-identity.ts` and `capture.ts` guard the same hazard.
+ *
+ * Values are capped downstream by `truncateEvent`, which runs on every capture
+ * path, so a hostile 1MB header cannot inflate an event.
+ */
+export function stampTransportIdentity(event: McpEvent, extra: CompatibleRequestHandlerExtra | undefined): void {
+  const identity = readTransportIdentity(extra)
+  if (!identity) {
+    return
+  }
+  if (identity.clientUserAgent) {
+    event.clientUserAgent = identity.clientUserAgent
+  }
+  if (identity.vendorClient) {
+    event.vendorClient = identity.vendorClient
+  }
+}

package/src/extensions/truncation.ts

@@ -430,6 +430,10 @@ export function truncateEvent<T extends Event | McpEvent>(event: T): T {
   result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH)
   result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH)
   result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH)
+  // Client-supplied HTTP headers, so unlike the fields above they are attacker-
+  // controlled in length. Any real User-Agent fits well inside the metadata cap.
+  result.clientUserAgent = truncateString(result.clientUserAgent, MAX_METADATA_LENGTH)
+  result.vendorClient = truncateString(result.vendorClient, MAX_METADATA_LENGTH)
   result.errorType = truncateString(result.errorType, MAX_METADATA_LENGTH)
 
   // Error field limits — operate on the core `$exception_list` shape

package/src/types.ts

@@ -151,6 +151,15 @@ export type BeforeSendFn = (event: PostHogCaptureEvent) => MaybePromise<PostHogC
 export interface Event {
   actorId?: string
   clientName?: string
+  /**
+   * Raw `user-agent` request header → `$mcp_client_user_agent`. HTTP transports
+   * only. The only place a client's *surface* is distinguishable: one vendor
+   * ships many products under a single `clientName` (Anthropic's CLI, Agent SDK
+   * and VS Code extension all report `claude-code`), and only the User-Agent
+   * parenthetical tells them apart. Captured verbatim — surfaces are resolved to
+   * friendly labels at query time, never in this SDK.
+   */
+  clientUserAgent?: string
   clientVersion?: string
   conversationId?: string
   duration?: number
@@ -199,6 +208,12 @@ export interface Event {
   toolDescription?: string
   userIntent?: string
   userIntentSource?: MCPAnalyticsIntentSource
+  /**
+   * Raw vendor client header (`x-anthropic-client`) → `$mcp_vendor_client`. HTTP
+   * transports only. A second, independent surface signal alongside
+   * {@link Event.clientUserAgent}; captured verbatim, never classified.
+   */
+  vendorClient?: string
 }
 
 /** A partially-built MCP event as it flows through the SDK before capture. */
@@ -344,6 +359,24 @@ export interface McpCaptureCommon {
    * not just the initialize event — the `PostHogMCP` client holds no per-session state.
    */
   protocolVersion?: string
+  /**
+   * Raw `user-agent` request header → `$mcp_client_user_agent`. The
+   * `instrument()` path reads this off the transport automatically; a custom
+   * dispatcher has no `extra`, so pass `req.headers['user-agent']` yourself.
+   *
+   * Worth wiring up: it is the only signal that separates a vendor's surfaces
+   * (Anthropic's CLI, Agent SDK and VS Code extension all report
+   * `clientName: "claude-code"`, and only the User-Agent parenthetical —
+   * `(cli)` / `(sdk-ts)` / `(claude-vscode)` — tells them apart). Send it raw;
+   * PostHog resolves friendly product labels at query time.
+   */
+  clientUserAgent?: string
+  /**
+   * Raw vendor client header → `$mcp_vendor_client`. Anthropic's clients send
+   * `x-anthropic-client`; pass it as a second, independent surface signal
+   * alongside {@link McpCaptureCommon.clientUserAgent}. Sent verbatim.
+   */
+  vendorClient?: string
   /** Person properties → `$set` (e.g. `{ name, email, plan }`). */
   setProperties?: JsonRecord
   /** Group memberships → `$groups`. */

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.10.9'
+export const version = '0.11.0'