@posthog/mcp 0.10.8 → 0.11.0

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.8'
+export const version = '0.11.0'