@posthog/mcp 0.11.0 → 0.11.2

package/src/extensions/detect.ts

@@ -0,0 +1,87 @@
+/**
+ * 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')
+}
+
+/**
+ * `getNegotiatedProtocolVersion()` — v2 only, and the last link in the protocol
+ * version chain. A v1 server does not have it, which is why the chain probes for
+ * it instead of branching on which SDK is installed.
+ */
+export function hasNegotiatedProtocolVersionAccessor(server: unknown): boolean {
+  return hasMethod(server, 'getNegotiatedProtocolVersion')
+}
+
+/** `_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/instrument-highlevel.ts

@@ -3,9 +3,9 @@
 // Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import type {
   CompatibleRequestHandlerExtra,
+  CompatibleToolResultLike,
   HighLevelMCPServerLike,
   MCPServerLike,
   RegisteredTool,
@@ -173,7 +173,7 @@ function addTracingToToolCallbackInternal(
     return tool
   }
 
-  const wrappedCallback = async (...params: unknown[]): Promise<CallToolResult> => {
+  const wrappedCallback = async (...params: unknown[]): Promise<CompatibleToolResultLike> => {
     let args: unknown
     let extra: CompatibleRequestHandlerExtra
 
@@ -192,13 +192,13 @@ function addTracingToToolCallbackInternal(
     })
     try {
       if (cleanedArgs === undefined) {
-        const handler = originalCallback as (extra: CompatibleRequestHandlerExtra) => Promise<CallToolResult>
+        const handler = originalCallback as (extra: CompatibleRequestHandlerExtra) => Promise<CompatibleToolResultLike>
         return await handler(extra)
       }
       const handler = originalCallback as (
         args: unknown,
         extra: CompatibleRequestHandlerExtra
-      ) => Promise<CallToolResult>
+      ) => Promise<CompatibleToolResultLike>
       return await handler(cleanedArgs, extra)
     } catch (error) {
       if (error instanceof Error) {

package/src/extensions/instrumentation.ts

@@ -3,10 +3,10 @@
 // Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
-import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
 import type {
   AnalyticsParameterOwnership,
   CompatibleRequestHandlerExtra,
+  CompatibleToolsListLike,
   MCPAnalyticsData,
   MCPRequestLike,
   MCPServerLike,
@@ -23,7 +23,7 @@ import {
   injectConversationIdPromptBack,
   resolveConversationId,
 } from './conversation-id'
-import { stampMetaClientInfo } from './client-identity'
+import { stampClientIdentity } from './client-identity'
 import { stampTransportIdentity } from './transport-identity'
 import { addInstructionsToOutputSchemas, mirrorInstructionsIntoStructuredContent } from './output-instructions'
 import { captureEvent } from './capture'
@@ -34,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'
@@ -228,7 +229,7 @@ async function prepareToolCallEvent(
     // Modern (stateless) clients carry client name/version + protocol version in
     // `_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)
+    stampClientIdentity(event, request, extra, server)
     // 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)
@@ -470,7 +471,7 @@ export async function isToolAdvertised(
   }
 
   try {
-    const response = (await listHandler({ method: 'tools/list', params: {} }, extra)) as ListToolsResult
+    const response = (await listHandler({ method: 'tools/list', params: {} }, extra)) as CompatibleToolsListLike
     if (!response || !Array.isArray(response.tools)) {
       return undefined
     }
@@ -495,7 +496,7 @@ export async function handleListToolsRequest(
   request: MCPRequestLike,
   extra: CompatibleRequestHandlerExtra | undefined,
   logger: LoggerFn
-): Promise<{ tools: ListToolsResult['tools'] }> {
+): Promise<{ tools: CompatibleToolsListLike['tools'] }> {
   const data = getServerTrackingData(server)
   const startTime = new Date()
   const sessionId = getSessionId(server, extra)
@@ -508,7 +509,7 @@ export async function handleListToolsRequest(
     eventType: MCPAnalyticsEventType.mcpToolsList,
     timestamp: startTime,
   }
-  stampMetaClientInfo(event, request)
+  stampClientIdentity(event, request, extra, server)
   stampTransportIdentity(event, extra)
 
   if (data) {
@@ -553,7 +554,7 @@ export async function handleListToolsRequest(
 
 function cacheToolAnalyticsParameterOwnership(
   cache: Map<string, AnalyticsParameterOwnership>,
-  tools: ListToolsResult['tools']
+  tools: CompatibleToolsListLike['tools']
 ): void {
   // Merge pages and concurrent enumerations; repeated tool names overwrite stale schemas.
   for (const tool of tools) {
@@ -563,7 +564,7 @@ function cacheToolAnalyticsParameterOwnership(
   }
 }
 
-function collectListedToolNames(tools: ListToolsResult['tools'] | undefined): string[] | undefined {
+function collectListedToolNames(tools: CompatibleToolsListLike['tools'] | undefined): string[] | undefined {
   if (!tools || tools.length === 0) {
     return
   }
@@ -579,10 +580,10 @@ async function getTracedToolsList(
   event: McpEvent,
   logger: LoggerFn,
   requestAttribution: SessionInfo
-): Promise<ListToolsResult['tools']> {
+): Promise<CompatibleToolsListLike['tools']> {
   try {
     const data = getServerTrackingData(server)
-    const originalResponse = (await originalListToolsHandler(request, extra)) as ListToolsResult
+    const originalResponse = (await originalListToolsHandler(request, extra)) as CompatibleToolsListLike
     // Injection must not mutate arrays reused or frozen by the server.
     let tools = [...(originalResponse.tools || [])]
 
@@ -634,7 +635,10 @@ async function getTracedToolsList(
   }
 }
 
-export function cacheToolDescriptions(cache: Map<string, string>, tools: ListToolsResult['tools'] | undefined): void {
+export function cacheToolDescriptions(
+  cache: Map<string, string>,
+  tools: CompatibleToolsListLike['tools'] | undefined
+): void {
   if (!tools) {
     return
   }
@@ -655,7 +659,10 @@ export function readToolMetaCategory(meta: unknown): string | undefined {
   return typeof category === 'string' && category.length > 0 ? category : undefined
 }
 
-export function cacheToolCategories(cache: Map<string, string>, tools: ListToolsResult['tools'] | undefined): void {
+export function cacheToolCategories(
+  cache: Map<string, string>,
+  tools: CompatibleToolsListLike['tools'] | undefined
+): void {
   if (!tools) {
     return
   }
@@ -688,8 +695,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)) {
@@ -820,7 +827,7 @@ export async function handleInitializeRequest(
   // Harmless for a legacy `initialize` (client info rides the body there, and the
   // negotiated protocol version below overrides any `_meta` one); picks up client
   // info if a client also sends it in `_meta`.
-  stampMetaClientInfo(event, request)
+  stampClientIdentity(event, request, extra, server)
   stampTransportIdentity(event, extra)
 
   await applyResolvedMetadata(event, data, request, extra)

package/src/extensions/internal.ts

@@ -14,7 +14,7 @@ import type {
 } from '../types'
 import { MCPAnalyticsEventType } from './event-types'
 import { captureEvent } from './capture'
-import { stampMetaClientInfo } from './client-identity'
+import { stampClientIdentity } from './client-identity'
 import { stampTransportIdentity } from './transport-identity'
 
 /**
@@ -153,7 +153,7 @@ export async function handleIdentify(
     parameters: { request, extra },
     timestamp: new Date(),
   }
-  stampMetaClientInfo(identifyEvent, request)
+  stampClientIdentity(identifyEvent, request, extra, server)
   stampTransportIdentity(identifyEvent, extra)
 
   try {

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.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'
 
@@ -110,7 +111,7 @@ 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
   }

package/src/extensions/tools.ts

@@ -3,7 +3,7 @@
 // Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
-import { type CallToolResult, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
+import type { CompatibleTextToolResult, CompatibleToolsListLike } from '../types'
 import { log, type LoggerFn } from './logger'
 
 export const GET_MORE_TOOLS_NAME = 'get_more_tools' as const
@@ -17,7 +17,7 @@ export function resolveMissingCapabilityToolName(options?: { missingCapabilityTo
   return options?.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
 }
 
-type ReportMissingToolDescriptor = ListToolsResult['tools'][number]
+type ReportMissingToolDescriptor = CompatibleToolsListLike['tools'][number]
 
 export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAME): ReportMissingToolDescriptor {
   return {
@@ -53,7 +53,7 @@ export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAM
  * report was recorded (custom dispatcher path); the `instrument()` path returns
  * it automatically.
  */
-export function getMoreToolsResult(): CallToolResult {
+export function getMoreToolsResult(): CompatibleTextToolResult {
   return {
     content: [
       {
@@ -64,7 +64,7 @@ export function getMoreToolsResult(): CallToolResult {
   }
 }
 
-export function handleReportMissing(args: { context: string }, logger: LoggerFn = log): CallToolResult {
+export function handleReportMissing(args: { context: string }, logger: LoggerFn = log): CompatibleTextToolResult {
   logger(`Missing tool reported: ${JSON.stringify(args)}`)
   return getMoreToolsResult()
 }

package/src/extensions/transport-identity.ts

@@ -1,5 +1,6 @@
 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
@@ -43,12 +44,17 @@ export interface TransportIdentity {
 }
 
 /**
- * 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.
+ * 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 = extra?.requestInfo?.headers
+  const headers = getRequestHeaders(extra)
   if (!headers) {
     return undefined
   }

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

@@ -3,8 +3,8 @@
 // Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import type { ErrorTracking } from '@posthog/core'
+import type { AnalyticsInjectableJsonSchema } from './extensions/analytics-parameters'
 import type { MCPAnalyticsEventType } from './extensions/event-types'
 import type { IdentityCache } from './extensions/internal'
 import type { PostHogCaptureEvent } from './extensions/posthog-events'
@@ -18,6 +18,54 @@ export type ErrorProperties = ErrorTracking.ErrorProperties
 /** A single parsed stack frame. Re-exported from `@posthog/core`. */
 export type StackFrame = ErrorTracking.StackFrame
 
+/**
+ * The MCP wire shapes we touch, declared structurally rather than imported from
+ * `@modelcontextprotocol/sdk`.
+ *
+ * Both SDK majors are **optional** peers — a v2-only consumer has no v1 SDK
+ * installed — so a type import of it in shipped `.d.ts` output is a `TS2307`
+ * for anyone type-checking without `skipLibCheck`. These are deliberately loose
+ * (open-ended, everything optional): they describe what we *read* off an SDK
+ * result, and an SDK-typed value assigns to them cleanly. What we hand back to
+ * the SDK is typed precisely instead — see {@link CompatibleTextToolResult}.
+ */
+export interface CompatibleToolResultLike {
+  content?: unknown[]
+  structuredContent?: JsonRecord
+  isError?: boolean
+  _meta?: JsonRecord
+  [key: string]: unknown
+}
+
+/** One entry of a `tools/list` response, as we read it. */
+export interface CompatibleToolDescriptorLike {
+  name: string
+  title?: string
+  description?: string
+  /** The advertised JSON Schema, as the analytics parameters are injected into it. */
+  inputSchema?: AnalyticsInjectableJsonSchema
+  outputSchema?: unknown
+  _meta?: JsonRecord
+  [key: string]: unknown
+}
+
+/** A `tools/list` response, as we read it. */
+export interface CompatibleToolsListLike {
+  tools: CompatibleToolDescriptorLike[]
+  nextCursor?: string
+  [key: string]: unknown
+}
+
+/**
+ * A text-only tool result *we* construct and a host may hand straight back to
+ * the SDK. Typed precisely, not loosely, so it stays assignable to the SDK's own
+ * `CallToolResult` — the direction that would silently break callers.
+ */
+export interface CompatibleTextToolResult {
+  content: { type: 'text'; text: string }[]
+  isError?: boolean
+}
+
 export interface MCPRequestParamsLike {
   arguments?: JsonRecord
   name?: string
@@ -128,8 +176,11 @@ export type MaybePromise<T> = T | Promise<T>
 export type MCPAnalyticsIntentSource = 'context_parameter' | 'inferred'
 
 export type ToolCallback =
-  | ((args: unknown, extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>)
-  | ((extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>)
+  | ((
+      args: unknown,
+      extra: CompatibleRequestHandlerExtra
+    ) => CompatibleToolResultLike | Promise<CompatibleToolResultLike>)
+  | ((extra: CompatibleRequestHandlerExtra) => CompatibleToolResultLike | Promise<CompatibleToolResultLike>)
 
 // RegisteredTool type that supports both MCP SDK 1.23- (callback) and 1.24+ (handler)
 export type RegisteredTool = {
@@ -225,14 +276,38 @@ 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
+  /**
+   * MCP SDK v2's parsed request. It lifts the reserved `io.modelcontextprotocol/*`
+   * keys out of `params._meta` into `envelope`, so client identity is here rather
+   * than on the request by the time a handler runs.
+   */
+  mcpReq?: { envelope?: Record<string, unknown>; [key: string]: unknown }
   [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

package/src/version.ts

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