@posthog/mcp 0.10.9 → 0.11.1

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/detect.ts

@@ -0,0 +1,78 @@
+/**
+ * Structural feature probes.
+ *
+ * Every question about the shape of a server object is answered here, by
+ * duck-typing the object in front of us — never by reading a package version or
+ * a protocol constant. Two reasons this is a rule and not a preference:
+ *
+ * - The two SDK majors expose the same capability under different names (v1's
+ *   `.tool()` vs v2's `.registerTool()`), so "which SDK is installed" answers a
+ *   different question than "can this object register a tool".
+ * - A single v2 server serves both protocol eras, request by request, so no
+ *   module-level constant describes it. v2's exported `LATEST_PROTOCOL_VERSION`
+ *   is `2025-11-25`.
+ *
+ * Nothing here imports `@modelcontextprotocol/*`; that boundary is pinned by
+ * `sdk-import-boundary.test.ts`.
+ */
+
+type UnknownRecord = Record<string, unknown>
+
+function asRecord(value: unknown): UnknownRecord | undefined {
+  return value && typeof value === 'object' ? (value as UnknownRecord) : undefined
+}
+
+function hasMethod(value: unknown, key: string): boolean {
+  return typeof asRecord(value)?.[key] === 'function'
+}
+
+/** A high-level `McpServer` wrapper: it holds the low-level server on `.server`. */
+export function hasNestedLowLevelServer(server: unknown): server is UnknownRecord & { server: UnknownRecord } {
+  const record = asRecord(server)
+  return !!record && 'server' in record && !!asRecord(record.server)
+}
+
+/** No `.server` property, so the object is itself the low-level `Server`. */
+export function isBareServerShape(server: unknown): boolean {
+  const record = asRecord(server)
+  return !!record && !('server' in record)
+}
+
+/** The high-level registry we read tool metadata from and wrap callbacks in. */
+export function hasToolRegistry(server: unknown): boolean {
+  return !!asRecord(asRecord(server)?._registeredTools)
+}
+
+/**
+ * The object can register a tool.
+ *
+ * v1 offers both `tool()` and `registerTool()`; v2 dropped the deprecated
+ * `tool()` and keeps only `registerTool()`. Requiring `tool()` specifically is
+ * what made `instrument()` reject every v2 high-level server — and, because
+ * `instrument()` swallows compatibility errors, reject it silently.
+ */
+export function canRegisterTools(server: unknown): boolean {
+  return hasMethod(server, 'registerTool') || hasMethod(server, 'tool')
+}
+
+/** Handler registration, which we patch to wrap late registrations. */
+export function canSetRequestHandler(server: unknown): boolean {
+  return hasMethod(server, 'setRequestHandler')
+}
+
+/** The live handler map we read and write directly. A real `Map` on both majors. */
+export function hasRequestHandlerMap(server: unknown): boolean {
+  const handlers = asRecord(server)?._requestHandlers
+  return handlers instanceof Map && typeof handlers.get === 'function'
+}
+
+/** `getClientVersion()` — still present on v2, and a link in B1's identity chain. */
+export function hasClientVersionAccessor(server: unknown): boolean {
+  return hasMethod(server, 'getClientVersion')
+}
+
+/** `_serverInfo`, which names the server on every event. */
+export function hasServerInfo(server: unknown): boolean {
+  const info = asRecord(asRecord(server)?._serverInfo)
+  return !!info && 'name' in info
+}

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

@@ -32,7 +32,6 @@ 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)

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'
@@ -33,6 +34,7 @@ import { getServerTrackingData, handleIdentify, setServerTrackingData, withIdent
 import type { LoggerFn } from './logger'
 import { buildCapturedMcpParameters } from './mcp-payloads'
 import { readRequestHandlerMethod } from './mcp-sdk-compat'
+import { getRequestHeaders } from './request-headers'
 import { getSessionId, getSessionInfo, newSessionId } from './session'
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from './session-token'
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from './tools'
@@ -157,22 +159,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 +230,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 +246,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 +355,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 +402,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 +510,7 @@ export async function handleListToolsRequest(
     timestamp: startTime,
   }
   stampMetaClientInfo(event, request)
+  stampTransportIdentity(event, extra)
 
   if (data) {
     await applyResolvedMetadata(event, data, request, extra)
@@ -683,7 +675,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
@@ -697,8 +689,8 @@ function mintStatelessSessionOnInitialize(
   extra: CompatibleRequestHandlerExtra | undefined
 ): string | undefined {
   try {
-    const headers = extra?.requestInfo?.headers
-    if (!headers || typeof headers !== 'object') {
+    const headers = getRequestHeaders(extra)
+    if (!headers) {
       return undefined // not an HTTP transport (stdio/in-memory) — nothing to mint into
     }
     if (readMcpSessionHeader(headers)) {
@@ -830,6 +822,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/request-headers.ts

@@ -0,0 +1,76 @@
+import type { RequestHeaderBag } from '../types'
+
+/**
+ * Reads the HTTP request headers off the `extra` (v1) / `ctx` (v2) object the
+ * MCP SDK hands a request handler, and returns them as a plain object with
+ * lowercase keys. Returns `undefined` when the request did not come over HTTP —
+ * stdio and in-memory transports carry no headers at all.
+ *
+ * The two SDK majors put them in different places and in different shapes: v1
+ * attaches a plain object at `extra.requestInfo.headers`, while v2 attaches the
+ * WHATWG `Request` at `ctx.http.req`, whose `headers` is a `Headers` instance
+ * that only answers to `.get()`. A v1-shaped read returns `undefined` on v2,
+ * which is why this exists.
+ *
+ * Normalisation is **by shape, not by source**: a framework is free to hand us a
+ * plain object where the SDK hands `Headers`, so both fields are checked for
+ * both shapes. `Headers` is duck-typed on `.entries` rather than `instanceof` —
+ * workerd and other edge runtimes are a different realm and would fail the
+ * identity check on a perfectly good object.
+ *
+ * Exported from the package for host callbacks. `identify`, `intentFallback`,
+ * `eventProperties` and `beforeSend` receive the SDK's `extra` unchanged — we
+ * deliberately do not synthesise a v1 shape on v2, because a fabricated
+ * `requestInfo` is a convincing partial lie about a shape the SDK removed on
+ * purpose. So a host that reads headers reads them through this instead:
+ *
+ * ```ts
+ * import { getRequestHeaders } from '@posthog/mcp'
+ *
+ * identify: async (request, extra) => {
+ *   const auth = getRequestHeaders(extra)?.['authorization']
+ *   // ...
+ * }
+ * ```
+ */
+export function getRequestHeaders(extra: unknown): RequestHeaderBag | undefined {
+  if (!extra || typeof extra !== 'object') {
+    return undefined
+  }
+  const record = extra as Record<string, unknown>
+  const http = record.http as { req?: { headers?: unknown } } | undefined
+  const requestInfo = record.requestInfo as { headers?: unknown } | undefined
+  const source = http?.req?.headers ?? requestInfo?.headers
+  if (!source || typeof source !== 'object') {
+    return undefined
+  }
+  return toHeaderBag(source)
+}
+
+/**
+ * Flattens either shape into a lowercase-keyed bag. Never throws: a header read
+ * failing must not take a tool call down with it.
+ */
+function toHeaderBag(source: object): RequestHeaderBag | undefined {
+  try {
+    const entries = isHeadersLike(source) ? [...source.entries()] : Object.entries(source)
+    const bag: RequestHeaderBag = {}
+    for (const [key, value] of entries) {
+      if (typeof key !== 'string' || value === undefined || value === null) {
+        continue
+      }
+      if (typeof value === 'string' || Array.isArray(value)) {
+        bag[key.toLowerCase()] = value as string | string[]
+      }
+    }
+    return bag
+  } catch {
+    return undefined
+  }
+}
+
+/** Duck-typed, never `instanceof` — an edge runtime's `Headers` is another realm's class. */
+function isHeadersLike(source: object): source is { entries(): Iterable<[string, string]> } {
+  const candidate = source as { entries?: unknown; get?: unknown }
+  return typeof candidate.entries === 'function' && typeof candidate.get === 'function'
+}

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)
 }
 
 /**