@posthog/mcp 0.8.0 → 0.9.1

package/src/extensions/exceptions.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
 

package/src/extensions/ids.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { uuidv7 } from '@posthog/core'
 

package/src/extensions/instrument-highlevel.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// 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, HighLevelMCPServerLike, MCPServerLike, RegisteredTool } from '../types'

package/src/extensions/instrument-lowlevel.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import type { CompatibleRequestHandlerExtra, MCPRequestLike, MCPServerLike } from '../types'

package/src/extensions/instrumentation.ts

@@ -1,9 +1,17 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// 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 { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, MCPServerLike, McpEvent } from '../types'
+import type {
+  CompatibleRequestHandlerExtra,
+  MCPAnalyticsData,
+  MCPRequestLike,
+  MCPServerLike,
+  McpEvent,
+  ServerClientInfoLike,
+} from '../types'
 import { addContextParameterToTools, getContextDescription, isContextEnabled } from './context-parameters'
 import {
   addConversationIdToTools,
@@ -17,11 +25,12 @@ import { captureEvent } from './capture'
 import { MCPAnalyticsEventType } from './event-types'
 import { captureException } from './exceptions'
 import { resolveToolCallIntent, setEventIntent, setExplicitContextIntent } from './intent'
-import { getServerTrackingData, handleIdentify } from './internal'
+import { getServerTrackingData, handleIdentify, setServerTrackingData } from './internal'
 import { log } from './logger'
 import { buildCapturedMcpParameters } from './mcp-payloads'
 import { getLiteralValue, getObjectShape } from './mcp-sdk-compat'
-import { getServerSessionId } from './session'
+import { getSessionId, newSessionId } from './session'
+import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from './session-token'
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from './tools'
 import { applyResolvedMetadata, isToolResultError } from './tracing-helpers'
 
@@ -129,7 +138,7 @@ async function prepareToolCallEvent(
   eventType: MCPAnalyticsEventType
 ): Promise<McpEvent | null> {
   try {
-    const sessionId = getServerSessionId(server, extra)
+    const sessionId = getSessionId(server, extra)
     await handleIdentify(server, data, sessionId, request, extra)
 
     const toolName = request.params?.name
@@ -283,7 +292,7 @@ export async function handleListToolsRequest(
   const data = getServerTrackingData(server)
   const startTime = new Date()
   const event: McpEvent = {
-    sessionId: getServerSessionId(server, extra),
+    sessionId: getSessionId(server, extra),
     parameters: buildCapturedMcpParameters(request),
     eventType: MCPAnalyticsEventType.mcpToolsList,
     timestamp: startTime,
@@ -410,6 +419,71 @@ export function cacheToolCategories(cache: Map<string, string>, tools: ListTools
 
 // --- initialize -----------------------------------------------------------
 
+/**
+ * Stateless servers never issue a session id, so sessions fragment and the
+ * 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`).
+ *
+ * The header only reaches the wire when response headers are built after the
+ * handler runs — StreamableHTTP with `enableJsonResponse: true`. SSE flushes
+ * headers first; those servers set the header themselves with the exported
+ * `encodeSessionId`, and this mint is a harmless no-op.
+ */
+function mintStatelessSessionOnInitialize(
+  server: MCPServerLike,
+  data: MCPAnalyticsData,
+  request: MCPRequestLike,
+  extra: CompatibleRequestHandlerExtra | undefined
+): void {
+  try {
+    const headers = extra?.requestInfo?.headers
+    if (!headers || typeof headers !== 'object') {
+      return // not an HTTP transport (stdio/in-memory) — nothing to mint into
+    }
+    if (readMcpSessionHeader(headers)) {
+      return // client already replays a session id (ours or the transport's)
+    }
+    const transport = server.transport
+    if (!transport || extra?.sessionId || transport.sessionId) {
+      return // stateful transports manage their own session id — leave it alone
+    }
+
+    const sessionId = newSessionId()
+    const clientInfo = readInitializeClientInfo(request)
+    const token = encodeSessionId({ sessionId, clientName: clientInfo?.name, clientVersion: clientInfo?.version })
+    if (!writeSessionIdToTransport(transport, token)) {
+      return // transport can't carry a response session id — keep generated behavior
+    }
+
+    data.sessionId = sessionId
+    data.sessionSource = 'token'
+    data.sessionInfo.clientName = clientInfo?.name
+    data.sessionInfo.clientVersion = clientInfo?.version
+    data.lastActivity = new Date()
+    setServerTrackingData(server, data)
+  } catch (error) {
+    log(`Warning: PostHog MCP analytics failed to mint a stateless session id - ${error}`)
+  }
+}
+
+/**
+ * Read the client name/version off the `initialize` request body — the SDK
+ * hasn't stored it yet (`getClientVersion()`) when our patch runs.
+ */
+function readInitializeClientInfo(request: MCPRequestLike): ServerClientInfoLike | undefined {
+  const clientInfo = request.params?.clientInfo
+  if (!clientInfo || typeof clientInfo !== 'object') {
+    return undefined
+  }
+  const { name, version } = clientInfo as Record<string, unknown>
+  return {
+    name: typeof name === 'string' ? name : undefined,
+    version: typeof version === 'string' ? version : undefined,
+  }
+}
+
 /**
  * Captures the connection handshake (and resolves identity) on `initialize`
  * before the original handler runs.
@@ -428,7 +502,9 @@ export async function handleInitializeRequest(
     return await originalInitializeHandler(request, extra)
   }
 
-  const sessionId = getServerSessionId(server, extra)
+  // Mint first so the `$mcp_initialize` event below already carries the minted id.
+  mintStatelessSessionOnInitialize(server, data, request, extra)
+  const sessionId = getSessionId(server, extra)
   await handleIdentify(server, data, sessionId, request, extra)
 
   const event: McpEvent = {

package/src/extensions/intent.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type {
   CompatibleRequestHandlerExtra,

package/src/extensions/internal.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type {
   CompatibleRequestHandlerExtra,
@@ -117,8 +118,10 @@ export function mergeIdentities(previous: UserIdentity | undefined, next: UserId
 }
 
 /**
- * Resolves the optional `identify` callback, dedupes against the server's identity
- * cache, and publishes an `$identify` event only when the identity has materially changed.
+ * Resolves the optional `identify` callback on every request (the resolved
+ * identity is what stamps `distinct_id`/`$set` onto events), but publishes the
+ * `$identify` event at most once per session: at `initialize`, when a
+ * long-lived server first sees the identity, or when it materially changes.
  */
 export async function handleIdentify(
   server: MCPServerLike,
@@ -146,11 +149,24 @@ export async function handleIdentify(
     if (identityResult) {
       const previousIdentity = data.identifiedSessions.get(sessionId)
       const mergedIdentity = mergeIdentities(previousIdentity, identityResult)
-      const hasChanged = !(previousIdentity && areIdentitiesEqual(previousIdentity, mergedIdentity))
+      // "First seen" means new to this instance's cache — which on a stateless
+      // pod (fresh instrument() per request) is every request. A token session
+      // 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.
+      const changed = previousIdentity !== undefined && !areIdentitiesEqual(previousIdentity, mergedIdentity)
+      const firstSeen = previousIdentity === undefined
+      const announcedAtInitialize = data.sessionSource === 'token' && request.method !== 'initialize'
+      const shouldPublish = changed || (firstSeen && !announcedAtInitialize)
 
       data.identifiedSessions.set(sessionId, mergedIdentity)
 
-      if (hasChanged) {
+      if (shouldPublish) {
         log(`Identified session ${sessionId} with identity: ${JSON.stringify(mergedIdentity)}`)
         captureEvent(server, identifyEvent)
       }

package/src/extensions/logger.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 /**
  * STDIO-safe logger.

package/src/extensions/mcp-payloads.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 const CONTEXT_ARGUMENT_NAME = 'context'
 const REDACTED_VALUE = '[redacted]'

package/src/extensions/mcp-sdk-compat.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 /**
  * MCP SDK Compatibility Helpers

package/src/extensions/posthog-events.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { Event } from '../types'
 import { POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty } from './constants'

package/src/extensions/sanitization.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { Event, McpEvent } from '../types'
 import { sanitizeCapturedValue } from './mcp-payloads'

package/src/extensions/session-token.ts

@@ -0,0 +1,168 @@
+/**
+ * Self-encoded session tokens for stateless / multi-pod MCP servers.
+ *
+ * A stateless server keeps nothing between requests, so every request starts a
+ * new session and the client name/version (only sent at `initialize`) is lost.
+ * The one value clients replay on every request is the `Mcp-Session-Id` header.
+ * So at `initialize` we mint that header as a token carrying the session id and
+ * client identity — any pod can read them back from the header alone.
+ *
+ * The token is unsigned: it holds only what the client already self-reports.
+ */
+
+export const MCP_SESSION_HEADER = 'mcp-session-id'
+
+/** What a session token carries. */
+export interface SessionTokenPayload {
+  /** PostHog session id (`ses_…`) → `$session_id`. */
+  sessionId: string
+  /** MCP client name → `$mcp_client_name`. */
+  clientName?: string
+  /** MCP client version → `$mcp_client_version`. */
+  clientVersion?: string
+}
+
+// On the wire the token is base64url(JSON) with shortened keys to keep the
+// header small: sid = sessionId, cn = clientName, cv = clientVersion.
+const MAX_TOKEN_LENGTH = 4096
+const MAX_SESSION_ID_LENGTH = 128
+const MAX_CLIENT_FIELD_LENGTH = 200
+
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+={0,2}$/
+
+/**
+ * Encodes a session token for the `Mcp-Session-Id` response header. Also
+ * exported for SSE servers, which flush headers before handlers run and so
+ * must set the header themselves at the HTTP layer.
+ */
+export function encodeSessionId(payload: SessionTokenPayload): string {
+  if (!payload || typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
+    throw new Error('encodeSessionId requires a non-empty `sessionId` (use newSessionId())')
+  }
+  const wire: Record<string, string> = { sid: payload.sessionId }
+  if (typeof payload.clientName === 'string' && payload.clientName.length > 0) {
+    wire.cn = payload.clientName.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  if (typeof payload.clientVersion === 'string' && payload.clientVersion.length > 0) {
+    wire.cv = payload.clientVersion.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  return utf8ToBase64Url(JSON.stringify(wire))
+}
+
+/**
+ * Decodes an `Mcp-Session-Id` value into a token payload. Returns `null` for
+ * anything that isn't one of our tokens (transport UUIDs, JWTs, garbage) and
+ * never throws.
+ */
+export function decodeSessionId(value: unknown): SessionTokenPayload | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_TOKEN_LENGTH) {
+    return null
+  }
+  // JWTs carry dots; UUIDs pass this check but fail JSON.parse below.
+  if (!BASE64URL_PATTERN.test(value)) {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(base64UrlToUtf8(value))
+  } catch {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null
+  }
+  const wire = parsed as Record<string, unknown>
+  if (typeof wire.sid !== 'string' || wire.sid.length === 0 || wire.sid.length > MAX_SESSION_ID_LENGTH) {
+    return null
+  }
+  const payload: SessionTokenPayload = { sessionId: wire.sid }
+  // A bad cn/cv just means no client info — it does not reject the token.
+  if (typeof wire.cn === 'string' && wire.cn.length > 0) {
+    payload.clientName = wire.cn.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  if (typeof wire.cv === 'string' && wire.cv.length > 0) {
+    payload.clientVersion = wire.cv.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  return payload
+}
+
+/**
+ * Reads the `mcp-session-id` header off `extra.requestInfo.headers`. The SDK
+ * 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
+}
+
+/**
+ * Puts a minted token on the transport so it goes out as the `Mcp-Session-Id`
+ * response header. The Node transport's `sessionId` is a getter backed by an
+ * inner web-standard transport, so verify the write by reading back and fall
+ * back to writing the inner one. Returns whether the write stuck; never throws.
+ */
+export function writeSessionIdToTransport(transport: unknown, token: string): boolean {
+  if (!transport || typeof transport !== 'object') {
+    return false
+  }
+  const outer = transport as { sessionId?: string; _webStandardTransport?: unknown }
+  try {
+    outer.sessionId = token
+  } catch {
+    // getter-only wrapper — try the inner transport below
+  }
+  if (outer.sessionId === token) {
+    return true
+  }
+  const inner = outer._webStandardTransport
+  if (inner && typeof inner === 'object') {
+    try {
+      ;(inner as { sessionId?: string }).sessionId = token
+    } catch {
+      // read-only inner transport — the final read-back decides
+    }
+  }
+  return outer.sessionId === token
+}
+
+// base64url without assuming Node: Buffer where available, TextEncoder/btoa on
+// edge runtimes. Must survive non-ASCII client names.
+
+function utf8ToBase64Url(input: string): string {
+  if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
+    return Buffer.from(input, 'utf8').toString('base64url')
+  }
+  const bytes = new TextEncoder().encode(input)
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i])
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function base64UrlToUtf8(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
+    return Buffer.from(padded, 'base64').toString('utf8')
+  }
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return new TextDecoder().decode(bytes)
+}

package/src/extensions/session.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { version } from '../version'
 import type {
@@ -13,6 +14,7 @@ import type {
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from './constants'
 import { deterministicPrefixedId, newPrefixedId } from './ids'
 import { getServerTrackingData, setServerTrackingData } from './internal'
+import { decodeSessionId, readMcpSessionHeader } from './session-token'
 
 export function newSessionId(): string {
   return newPrefixedId('ses')
@@ -27,58 +29,58 @@ export function deriveSessionIdFromMCPSession(mcpSessionId: string): string {
 }
 
 /**
- * Resolves the session id for a request, preferring the MCP protocol sessionId
- * over an SDK-generated one so a transport-supplied session wins.
+ * Resolves the session id for a request: from the replayed session token, from
+ * the transport's MCP session id, or — when the request carries nothing — from
+ * this instance's memory. Also saves the token's client name/version so events
+ * built later in the request can use them (see getSessionInfo).
  */
-export function getServerSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string {
+export function getSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string {
   const data = getServerTrackingData(server)
-
   if (!data) {
     throw new Error('Server tracking data not found')
   }
 
-  const mcpSessionId = extra?.sessionId
-
-  if (mcpSessionId) {
-    data.sessionId = deriveSessionIdFromMCPSession(mcpSessionId)
-    data.lastMcpSessionId = mcpSessionId
+  // Our token rides the `mcp-session-id` request header, which stateless
+  // transports ignore — so read it ourselves.
+  const sessionHeader = readMcpSessionHeader(extra?.requestInfo?.headers)
+  const token = decodeSessionId(sessionHeader)
+
+  let sessionId: string
+  if (token) {
+    // Token we minted at `initialize` (see session-token.ts).
+    data.sessionSource = 'token'
+    data.sessionInfo.clientName = token.clientName
+    data.sessionInfo.clientVersion = token.clientVersion
+    sessionId = token.sessionId
+  } else if (extra?.sessionId) {
+    // Session id issued by a stateful transport: hash it so the same MCP
+    // session maps to the same SDK session across restarts.
     data.sessionSource = 'mcp'
-    setServerTrackingData(server, data)
-    setLastActivity(server)
-    return data.sessionId
+    sessionId = deriveSessionIdFromMCPSession(extra.sessionId)
+  } else {
+    sessionId = getSessionIdFromMemory(data)
   }
 
-  // Once a session has been MCP-derived, keep that id even if a later request
-  // arrives without the MCP sessionId, so the session doesn't fragment.
-  if (data.sessionSource === 'mcp' && data.lastMcpSessionId) {
-    setLastActivity(server)
-    return data.sessionId
-  }
+  data.sessionId = sessionId
+  data.lastActivity = new Date()
+  setServerTrackingData(server, data)
+  return sessionId
+}
 
-  // SDK-generated sessions roll over after an inactivity timeout.
-  const now = Date.now()
+/**
+ * Nothing replayed on this request: keep the id we already have. Only
+ * generated sessions roll over on inactivity — token/MCP ids live as long as
+ * the client replays them, and regenerating one would split the session.
+ */
+function getSessionIdFromMemory(data: MCPAnalyticsData): string {
   const timeoutMs = INACTIVITY_TIMEOUT_IN_MINUTES * 60 * 1000
-  if (now - data.lastActivity.getTime() > timeoutMs) {
-    data.sessionId = newSessionId()
-    data.sessionSource = 'generated'
-    setServerTrackingData(server, data)
+  const isStale = Date.now() - data.lastActivity.getTime() > timeoutMs
+  if (data.sessionSource === 'generated' && isStale) {
+    return newSessionId()
   }
-  setLastActivity(server)
-
   return data.sessionId
 }
 
-export function setLastActivity(server: MCPServerLike): void {
-  const data = getServerTrackingData(server)
-
-  if (!data) {
-    throw new Error('Server tracking data not found')
-  }
-
-  data.lastActivity = new Date()
-  setServerTrackingData(server, data)
-}
-
 /**
  * Builds the session metadata stamped onto an event. The caller passes the
  * session id resolved for *this* request so identity attribution can't be

package/src/extensions/sink.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { PostHog } from 'posthog-node'
 import { uuidv7 } from '@posthog/core'

package/src/extensions/tools.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// 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 { log } from './logger'

package/src/extensions/tracing-helpers.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, McpEvent } from '../types'
 import { resolveEventProperties } from './internal'

package/src/extensions/truncation.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { ErrorProperties, Event, StackFrame, McpEvent } from '../types'