@posthog/mcp 0.10.9 → 0.11.1

package/src/extensions/session.ts

@@ -14,6 +14,7 @@ import type {
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from './constants'
 import { deterministicPrefixedId, newPrefixedId } from './ids'
 import { getServerTrackingData, setServerTrackingData } from './internal'
+import { getRequestHeaders } from './request-headers'
 import { decodeSessionId, readMcpSessionHeader } from './session-token'
 import type { SessionTokenPayload } from './session-token'
 
@@ -30,9 +31,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 +71,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,20 +102,16 @@ 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,
   extra?: CompatibleRequestHandlerExtra
 ): SessionTokenPayload | undefined {
-  const token = decodeSessionId(readMcpSessionHeader(extra?.requestInfo?.headers))
+  const token = decodeSessionId(readMcpSessionHeader(getRequestHeaders(extra)))
   if (!token) {
     return undefined
   }
@@ -139,9 +127,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 +190,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,100 @@
+import type { CompatibleRequestHandlerExtra, McpEvent } from '../types'
+import { readHeaderValue } from './headers'
+import { getRequestHeaders } from './request-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 the request. Returns `undefined`
+ * when the request carries neither — including every stdio and in-memory
+ * request, which has no HTTP headers at all. Never throws.
+ *
+ * Sourced through `getRequestHeaders` rather than `extra.requestInfo.headers`
+ * directly: MCP SDK v2 puts the request at `extra.http.req` as a WHATWG
+ * `Request`, so a v1-shaped read finds nothing and this whole feature would be
+ * silently inert on exactly the servers being adopted now.
+ */
+export function readTransportIdentity(extra: CompatibleRequestHandlerExtra | undefined): TransportIdentity | undefined {
+  const headers = getRequestHeaders(extra)
+  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/index.ts

@@ -210,6 +210,9 @@ export {
   PostHogMCPAnalyticsEvent,
   PostHogMCPAnalyticsProperty,
 } from './extensions/constants'
+// Host callbacks receive the SDK's `extra`/`ctx` unchanged, and the two SDK
+// majors carry HTTP headers in different places and shapes. This reads either.
+export { getRequestHeaders } from './extensions/request-headers'
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp'
 export { getMoreToolsResult } from './extensions/tools'
 export { setLogger } from './extensions/logger'
@@ -229,6 +232,7 @@ export type {
   MissingCapabilityCaptureData,
   PreparedToolCall,
   PrepareToolListOptions,
+  RequestHeaderBag,
   ToolCallCaptureData,
   ToolsListCaptureData,
   UserIdentity,

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. */
@@ -210,14 +225,32 @@ export interface CompatibleRequestInfoLike {
   [key: string]: unknown
 }
 
+/**
+ * The HTTP request an MCP SDK v2 server attaches to the handler context, as a
+ * WHATWG `Request` — so `headers` answers to `.get()`, not to indexing.
+ */
+export interface CompatibleHttpRequestLike {
+  req?: { headers?: unknown; [key: string]: unknown }
+  [key: string]: unknown
+}
+
 export interface CompatibleRequestHandlerExtra {
   headers?: Record<string, string | string[]>
   sessionId?: string
   /** Present on HTTP transports only — headers ride every request, unlike `clientInfo`. */
   requestInfo?: CompatibleRequestInfoLike
+  /** Where MCP SDK v2 puts the same thing. Read both through `getRequestHeaders`. */
+  http?: CompatibleHttpRequestLike
   [key: string]: unknown
 }
 
+/**
+ * HTTP headers normalised to lowercase keys, as `getRequestHeaders` returns
+ * them — a plain bag, so a host's existing `headers['authorization']` keeps
+ * working when only the source of the headers changes.
+ */
+export type RequestHeaderBag = Record<string, string | string[]>
+
 export interface ServerClientInfoLike {
   name?: string
   version?: string
@@ -344,6 +377,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.1'