@posthog/mcp 0.7.0 → 0.9.0

package/dist/extensions/session-token.js

@@ -0,0 +1,122 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    MCP_SESSION_HEADER: ()=>MCP_SESSION_HEADER,
+    decodeSessionId: ()=>decodeSessionId,
+    encodeSessionId: ()=>encodeSessionId,
+    readMcpSessionHeader: ()=>readMcpSessionHeader,
+    writeSessionIdToTransport: ()=>writeSessionIdToTransport
+});
+const MCP_SESSION_HEADER = 'mcp-session-id';
+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}$/;
+function encodeSessionId(payload) {
+    if (!payload || 'string' != typeof payload.sessionId || 0 === payload.sessionId.length) throw new Error('encodeSessionId requires a non-empty `sessionId` (use newSessionId())');
+    const wire = {
+        sid: payload.sessionId
+    };
+    if ('string' == typeof payload.clientName && payload.clientName.length > 0) wire.cn = payload.clientName.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    if ('string' == typeof payload.clientVersion && payload.clientVersion.length > 0) wire.cv = payload.clientVersion.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    return utf8ToBase64Url(JSON.stringify(wire));
+}
+function decodeSessionId(value) {
+    if ('string' != typeof value || 0 === value.length || value.length > MAX_TOKEN_LENGTH) return null;
+    if (!BASE64URL_PATTERN.test(value)) return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(base64UrlToUtf8(value));
+    } catch  {
+        return null;
+    }
+    if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) return null;
+    const wire = parsed;
+    if ('string' != typeof wire.sid || 0 === wire.sid.length || wire.sid.length > MAX_SESSION_ID_LENGTH) return null;
+    const payload = {
+        sessionId: wire.sid
+    };
+    if ('string' == typeof wire.cn && wire.cn.length > 0) payload.clientName = wire.cn.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    if ('string' == typeof wire.cv && wire.cv.length > 0) payload.clientVersion = wire.cv.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    return payload;
+}
+function readMcpSessionHeader(headers) {
+    if (!headers || 'object' != typeof headers) return;
+    const record = headers;
+    let value = record[MCP_SESSION_HEADER];
+    if (void 0 === value) {
+        const key = Object.keys(record).find((k)=>k.toLowerCase() === MCP_SESSION_HEADER);
+        value = void 0 === key ? void 0 : record[key];
+    }
+    const first = Array.isArray(value) ? value[0] : value;
+    if ('string' != typeof first) return;
+    const trimmed = first.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+}
+function writeSessionIdToTransport(transport, token) {
+    if (!transport || 'object' != typeof transport) return false;
+    const outer = transport;
+    try {
+        outer.sessionId = token;
+    } catch  {}
+    if (outer.sessionId === token) return true;
+    const inner = outer._webStandardTransport;
+    if (inner && 'object' == typeof inner) try {
+        inner.sessionId = token;
+    } catch  {}
+    return outer.sessionId === token;
+}
+function utf8ToBase64Url(input) {
+    if ('undefined' != typeof Buffer && 'function' == typeof Buffer.from) 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) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+    const padded = normalized + '='.repeat((4 - normalized.length % 4) % 4);
+    if ('undefined' != typeof Buffer && 'function' == typeof Buffer.from) 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);
+}
+exports.MCP_SESSION_HEADER = __webpack_exports__.MCP_SESSION_HEADER;
+exports.decodeSessionId = __webpack_exports__.decodeSessionId;
+exports.encodeSessionId = __webpack_exports__.encodeSessionId;
+exports.readMcpSessionHeader = __webpack_exports__.readMcpSessionHeader;
+exports.writeSessionIdToTransport = __webpack_exports__.writeSessionIdToTransport;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "MCP_SESSION_HEADER",
+    "decodeSessionId",
+    "encodeSessionId",
+    "readMcpSessionHeader",
+    "writeSessionIdToTransport"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/extensions/session-token.mjs

@@ -0,0 +1,76 @@
+const MCP_SESSION_HEADER = 'mcp-session-id';
+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}$/;
+function encodeSessionId(payload) {
+    if (!payload || 'string' != typeof payload.sessionId || 0 === payload.sessionId.length) throw new Error('encodeSessionId requires a non-empty `sessionId` (use newSessionId())');
+    const wire = {
+        sid: payload.sessionId
+    };
+    if ('string' == typeof payload.clientName && payload.clientName.length > 0) wire.cn = payload.clientName.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    if ('string' == typeof payload.clientVersion && payload.clientVersion.length > 0) wire.cv = payload.clientVersion.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    return utf8ToBase64Url(JSON.stringify(wire));
+}
+function decodeSessionId(value) {
+    if ('string' != typeof value || 0 === value.length || value.length > MAX_TOKEN_LENGTH) return null;
+    if (!BASE64URL_PATTERN.test(value)) return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(base64UrlToUtf8(value));
+    } catch  {
+        return null;
+    }
+    if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) return null;
+    const wire = parsed;
+    if ('string' != typeof wire.sid || 0 === wire.sid.length || wire.sid.length > MAX_SESSION_ID_LENGTH) return null;
+    const payload = {
+        sessionId: wire.sid
+    };
+    if ('string' == typeof wire.cn && wire.cn.length > 0) payload.clientName = wire.cn.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    if ('string' == typeof wire.cv && wire.cv.length > 0) payload.clientVersion = wire.cv.slice(0, MAX_CLIENT_FIELD_LENGTH);
+    return payload;
+}
+function readMcpSessionHeader(headers) {
+    if (!headers || 'object' != typeof headers) return;
+    const record = headers;
+    let value = record[MCP_SESSION_HEADER];
+    if (void 0 === value) {
+        const key = Object.keys(record).find((k)=>k.toLowerCase() === MCP_SESSION_HEADER);
+        value = void 0 === key ? void 0 : record[key];
+    }
+    const first = Array.isArray(value) ? value[0] : value;
+    if ('string' != typeof first) return;
+    const trimmed = first.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+}
+function writeSessionIdToTransport(transport, token) {
+    if (!transport || 'object' != typeof transport) return false;
+    const outer = transport;
+    try {
+        outer.sessionId = token;
+    } catch  {}
+    if (outer.sessionId === token) return true;
+    const inner = outer._webStandardTransport;
+    if (inner && 'object' == typeof inner) try {
+        inner.sessionId = token;
+    } catch  {}
+    return outer.sessionId === token;
+}
+function utf8ToBase64Url(input) {
+    if ('undefined' != typeof Buffer && 'function' == typeof Buffer.from) 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) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+    const padded = normalized + '='.repeat((4 - normalized.length % 4) % 4);
+    if ('undefined' != typeof Buffer && 'function' == typeof Buffer.from) 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);
+}
+export { MCP_SESSION_HEADER, decodeSessionId, encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport };

package/dist/extensions/session.d.ts

@@ -6,11 +6,12 @@ export declare function newSessionId(): string;
  */
 export declare 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 declare function getServerSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string;
-export declare function setLastActivity(server: MCPServerLike): void;
+export declare function getSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string;
 /**
  * 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/dist/extensions/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AAKjB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,6BAA6B,GAAG,MAAM,CAoCvG;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAgCb"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/extensions/session.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,UAAU,CAAA;AAMjB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,6BAA6B,GAAG,MAAM,CA+BjG;AAgBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAgCb"}

package/dist/extensions/session.js

@@ -24,8 +24,7 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    setLastActivity: ()=>setLastActivity,
-    getServerSessionId: ()=>getServerSessionId,
+    getSessionId: ()=>getSessionId,
     deriveSessionIdFromMCPSession: ()=>deriveSessionIdFromMCPSession,
     getSessionInfo: ()=>getSessionInfo,
     newSessionId: ()=>newSessionId
@@ -34,43 +33,38 @@ const external_version_js_namespaceObject = require("../version.js");
 const external_constants_js_namespaceObject = require("./constants.js");
 const external_ids_js_namespaceObject = require("./ids.js");
 const external_internal_js_namespaceObject = require("./internal.js");
+const external_session_token_js_namespaceObject = require("./session-token.js");
 function newSessionId() {
     return (0, external_ids_js_namespaceObject.newPrefixedId)('ses');
 }
 function deriveSessionIdFromMCPSession(mcpSessionId) {
     return (0, external_ids_js_namespaceObject.deterministicPrefixedId)('ses', mcpSessionId);
 }
-function getServerSessionId(server, extra) {
+function getSessionId(server, extra) {
     const data = (0, external_internal_js_namespaceObject.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;
+    const sessionHeader = (0, external_session_token_js_namespaceObject.readMcpSessionHeader)(extra?.requestInfo?.headers);
+    const token = (0, external_session_token_js_namespaceObject.decodeSessionId)(sessionHeader);
+    let sessionId;
+    if (token) {
+        data.sessionSource = 'token';
+        data.sessionInfo.clientName = token.clientName;
+        data.sessionInfo.clientVersion = token.clientVersion;
+        sessionId = token.sessionId;
+    } else if (extra?.sessionId) {
         data.sessionSource = 'mcp';
-        (0, external_internal_js_namespaceObject.setServerTrackingData)(server, data);
-        setLastActivity(server);
-        return data.sessionId;
-    }
-    if ('mcp' === data.sessionSource && data.lastMcpSessionId) {
-        setLastActivity(server);
-        return data.sessionId;
-    }
-    const now = Date.now();
-    const timeoutMs = 60 * external_constants_js_namespaceObject.INACTIVITY_TIMEOUT_IN_MINUTES * 1000;
-    if (now - data.lastActivity.getTime() > timeoutMs) {
-        data.sessionId = newSessionId();
-        data.sessionSource = 'generated';
-        (0, external_internal_js_namespaceObject.setServerTrackingData)(server, data);
-    }
-    setLastActivity(server);
-    return data.sessionId;
-}
-function setLastActivity(server) {
-    const data = (0, external_internal_js_namespaceObject.getServerTrackingData)(server);
-    if (!data) throw new Error('Server tracking data not found');
+        sessionId = deriveSessionIdFromMCPSession(extra.sessionId);
+    } else sessionId = getSessionIdFromMemory(data);
+    data.sessionId = sessionId;
     data.lastActivity = new Date();
     (0, external_internal_js_namespaceObject.setServerTrackingData)(server, data);
+    return sessionId;
+}
+function getSessionIdFromMemory(data) {
+    const timeoutMs = 60 * external_constants_js_namespaceObject.INACTIVITY_TIMEOUT_IN_MINUTES * 1000;
+    const isStale = Date.now() - data.lastActivity.getTime() > timeoutMs;
+    if ('generated' === data.sessionSource && isStale) return newSessionId();
+    return data.sessionId;
 }
 function getSessionInfo(server, data, sessionId) {
     let clientInfo;
@@ -97,16 +91,14 @@ function getSessionInfo(server, data, sessionId) {
     return data.sessionInfo;
 }
 exports.deriveSessionIdFromMCPSession = __webpack_exports__.deriveSessionIdFromMCPSession;
-exports.getServerSessionId = __webpack_exports__.getServerSessionId;
+exports.getSessionId = __webpack_exports__.getSessionId;
 exports.getSessionInfo = __webpack_exports__.getSessionInfo;
 exports.newSessionId = __webpack_exports__.newSessionId;
-exports.setLastActivity = __webpack_exports__.setLastActivity;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "deriveSessionIdFromMCPSession",
-    "getServerSessionId",
+    "getSessionId",
     "getSessionInfo",
-    "newSessionId",
-    "setLastActivity"
+    "newSessionId"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/extensions/session.mjs

@@ -2,43 +2,38 @@ import { version } from "../version.mjs";
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from "./constants.mjs";
 import { deterministicPrefixedId, newPrefixedId } from "./ids.mjs";
 import { getServerTrackingData, setServerTrackingData } from "./internal.mjs";
+import { decodeSessionId, readMcpSessionHeader } from "./session-token.mjs";
 function newSessionId() {
     return newPrefixedId('ses');
 }
 function deriveSessionIdFromMCPSession(mcpSessionId) {
     return deterministicPrefixedId('ses', mcpSessionId);
 }
-function getServerSessionId(server, extra) {
+function getSessionId(server, extra) {
     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;
+    const sessionHeader = readMcpSessionHeader(extra?.requestInfo?.headers);
+    const token = decodeSessionId(sessionHeader);
+    let sessionId;
+    if (token) {
+        data.sessionSource = 'token';
+        data.sessionInfo.clientName = token.clientName;
+        data.sessionInfo.clientVersion = token.clientVersion;
+        sessionId = token.sessionId;
+    } else if (extra?.sessionId) {
         data.sessionSource = 'mcp';
-        setServerTrackingData(server, data);
-        setLastActivity(server);
-        return data.sessionId;
-    }
-    if ('mcp' === data.sessionSource && data.lastMcpSessionId) {
-        setLastActivity(server);
-        return data.sessionId;
-    }
-    const now = Date.now();
-    const timeoutMs = 60 * INACTIVITY_TIMEOUT_IN_MINUTES * 1000;
-    if (now - data.lastActivity.getTime() > timeoutMs) {
-        data.sessionId = newSessionId();
-        data.sessionSource = 'generated';
-        setServerTrackingData(server, data);
-    }
-    setLastActivity(server);
-    return data.sessionId;
-}
-function setLastActivity(server) {
-    const data = getServerTrackingData(server);
-    if (!data) throw new Error('Server tracking data not found');
+        sessionId = deriveSessionIdFromMCPSession(extra.sessionId);
+    } else sessionId = getSessionIdFromMemory(data);
+    data.sessionId = sessionId;
     data.lastActivity = new Date();
     setServerTrackingData(server, data);
+    return sessionId;
+}
+function getSessionIdFromMemory(data) {
+    const timeoutMs = 60 * INACTIVITY_TIMEOUT_IN_MINUTES * 1000;
+    const isStale = Date.now() - data.lastActivity.getTime() > timeoutMs;
+    if ('generated' === data.sessionSource && isStale) return newSessionId();
+    return data.sessionId;
 }
 function getSessionInfo(server, data, sessionId) {
     let clientInfo;
@@ -64,4 +59,4 @@ function getSessionInfo(server, data, sessionId) {
     setServerTrackingData(server, data);
     return data.sessionInfo;
 }
-export { deriveSessionIdFromMCPSession, getServerSessionId, getSessionInfo, newSessionId, setLastActivity };
+export { deriveSessionIdFromMCPSession, getSessionId, getSessionInfo, newSessionId };

package/dist/extensions/sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/extensions/sink.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAE7D,OAAO,EAAE,KAAK,mBAAmB,EAA6B,MAAM,kBAAkB,CAAA;AAKtF,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,OAAO,CAAA;IACnC,kFAAkF;IAClF,UAAU,CAAC,EAAE,YAAY,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CA2BnE;AA4BD;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,OAAO;IAE7C;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAmC1E"}
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/extensions/sink.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAE7D,OAAO,EAAE,KAAK,mBAAmB,EAA6B,MAAM,kBAAkB,CAAA;AAKtF,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,OAAO,CAAA;IACnC,kFAAkF;IAClF,UAAU,CAAC,EAAE,YAAY,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CA2BnE;AA4BD;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,OAAO;IAE7C;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAmC1E"}

package/dist/extensions/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/extensions/tools.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAA;AAG9F,eAAO,MAAM,mBAAmB,EAAG,gBAAyB,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,CAAC,EAAE;IAAE,yBAAyB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEzG;AAED,KAAK,2BAA2B,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,wBAAgB,8BAA8B,CAAC,IAAI,GAAE,MAA4B,GAAG,2BAA2B,CA6B9G;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CASnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAG7E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/extensions/tools.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAA;AAG9F,eAAO,MAAM,mBAAmB,EAAG,gBAAyB,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,CAAC,EAAE;IAAE,yBAAyB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEzG;AAED,KAAK,2BAA2B,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,wBAAgB,8BAA8B,CAAC,IAAI,GAAE,MAA4B,GAAG,2BAA2B,CA6B9G;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CASnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAG7E"}

package/dist/extensions/tracing-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing-helpers.d.ts","sourceRoot":"","sources":["../../src/extensions/tracing-helpers.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,6BAA6B,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGzG;;;;;;GAMG;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAExD"}
+{"version":3,"file":"tracing-helpers.d.ts","sourceRoot":"","sources":["../../src/extensions/tracing-helpers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,6BAA6B,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGzG;;;;;;GAMG;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAExD"}

package/dist/extensions/truncation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../../src/extensions/truncation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAmB,KAAK,EAAc,QAAQ,EAAE,MAAM,UAAU,CAAA;AAG5E,eAAO,MAAM,SAAS,KAAK,CAAA;AAC3B,eAAO,MAAM,WAAW,MAAM,CAAA;AAC9B,eAAO,MAAM,iBAAiB,QAAS,CAAA;AACvC,eAAO,MAAM,eAAe,SAAU,CAAA;AAgBtC;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,MAAkB,EACzB,UAAU,GAAE,MAAoB,EAChC,eAAe,GAAE,MAA0B,GAC1C,OAAO,CAGT;AAkXD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAmCrE"}
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../../src/extensions/truncation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,KAAK,EAAc,QAAQ,EAAE,MAAM,UAAU,CAAA;AAG5E,eAAO,MAAM,SAAS,KAAK,CAAA;AAC3B,eAAO,MAAM,WAAW,MAAM,CAAA;AAC9B,eAAO,MAAM,iBAAiB,QAAS,CAAA;AACvC,eAAO,MAAM,eAAe,SAAU,CAAA;AAgBtC;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,MAAkB,EACzB,UAAU,GAAE,MAAoB,EAChC,eAAe,GAAE,MAA0B,GAC1C,OAAO,CAGT;AAkXD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAoCrE"}

package/dist/extensions/truncation.js

@@ -250,6 +250,7 @@ function truncateEvent(event) {
     result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH);
     result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH);
     result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH);
+    result.errorType = truncateString(result.errorType, MAX_METADATA_LENGTH);
     if (null != result.error && 'object' == typeof result.error) result.error = truncateExceptionList(result.error);
     result.response = truncateResponseContent(result.response);
     if (null != result.parameters) result.parameters = normalize(result.parameters);

package/dist/extensions/truncation.mjs

@@ -217,6 +217,7 @@ function truncateEvent(event) {
     result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH);
     result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH);
     result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH);
+    result.errorType = truncateString(result.errorType, MAX_METADATA_LENGTH);
     if (null != result.error && 'object' == typeof result.error) result.error = truncateExceptionList(result.error);
     result.response = truncateResponseContent(result.response);
     if (null != result.parameters) result.parameters = normalize(result.parameters);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { PostHog } from 'posthog-node';
-import { deriveSessionIdFromMCPSession } from './extensions/session';
+import { deriveSessionIdFromMCPSession, newSessionId } from './extensions/session';
 import type { McpAnalytics, MCPAnalyticsOptions } from './types';
 /**
  * Instruments an MCP server so PostHog auto-captures tool calls, tool listings, initialize
@@ -47,7 +47,8 @@ declare function instrument(server: unknown, posthog: PostHog, options?: MCPAnal
  * @returns A `(server) => server` mutator that instruments the server and returns it.
  */
 declare function instrumentMutator<TServer>(posthog: PostHog, options?: MCPAnalyticsOptions): (server: TServer) => TServer;
-export { deriveSessionIdFromMCPSession };
+export { deriveSessionIdFromMCPSession, newSessionId };
+export { MCP_SESSION_HEADER, decodeSessionId, encodeSessionId, type SessionTokenPayload, } from './extensions/session-token';
 export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, } from './extensions/constants';
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp';
 export { getMoreToolsResult } from './extensions/tools';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAQ3C,OAAO,EAAE,6BAA6B,EAAgC,MAAM,sBAAsB,CAAA;AAGlG,OAAO,KAAK,EAGV,YAAY,EAEZ,mBAAmB,EAGpB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAkCtG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAKjH;AAmFD,OAAO,EAAE,6BAA6B,EAAE,CAAA;AACxC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAI/C,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3D,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,GACb,MAAM,SAAS,CAAA;AAChB,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAQ3C,OAAO,EAAE,6BAA6B,EAAkB,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGlG,OAAO,KAAK,EAGV,YAAY,EAEZ,mBAAmB,EAGpB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAkCtG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAKjH;AAmFD,OAAO,EAAE,6BAA6B,EAAE,YAAY,EAAE,CAAA;AAItD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAI/C,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3D,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,GACb,MAAM,SAAS,CAAA;AAChB,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/index.js

@@ -24,14 +24,18 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    setLogger: ()=>logger_js_namespaceObject.setLogger,
     PostHog: ()=>external_posthog_node_namespaceObject.PostHog,
     PostHogMCP: ()=>posthog_mcp_js_namespaceObject.PostHogMCP,
-    deriveSessionIdFromMCPSession: ()=>session_js_namespaceObject.deriveSessionIdFromMCPSession,
     POSTHOG_MCP_ANALYTICS_SOURCE: ()=>constants_js_namespaceObject.POSTHOG_MCP_ANALYTICS_SOURCE,
+    deriveSessionIdFromMCPSession: ()=>session_js_namespaceObject.deriveSessionIdFromMCPSession,
     instrument: ()=>instrument,
+    decodeSessionId: ()=>session_token_js_namespaceObject.decodeSessionId,
+    newSessionId: ()=>session_js_namespaceObject.newSessionId,
+    MCP_SESSION_HEADER: ()=>session_token_js_namespaceObject.MCP_SESSION_HEADER,
     instrumentMutator: ()=>instrumentMutator,
-    setLogger: ()=>logger_js_namespaceObject.setLogger,
     PostHogMCPAnalyticsEvent: ()=>constants_js_namespaceObject.PostHogMCPAnalyticsEvent,
+    encodeSessionId: ()=>session_token_js_namespaceObject.encodeSessionId,
     getMoreToolsResult: ()=>tools_js_namespaceObject.getMoreToolsResult,
     PostHogMCPAnalyticsProperty: ()=>constants_js_namespaceObject.PostHogMCPAnalyticsProperty
 });
@@ -45,6 +49,7 @@ const lib_identity_js_namespaceObject = require("./extensions/lib-identity.js");
 const session_js_namespaceObject = require("./extensions/session.js");
 const instrument_lowlevel_js_namespaceObject = require("./extensions/instrument-lowlevel.js");
 const instrument_highlevel_js_namespaceObject = require("./extensions/instrument-highlevel.js");
+const session_token_js_namespaceObject = require("./extensions/session-token.js");
 const constants_js_namespaceObject = require("./extensions/constants.js");
 const posthog_mcp_js_namespaceObject = require("./extensions/posthog-mcp.js");
 const tools_js_namespaceObject = require("./extensions/tools.js");
@@ -132,26 +137,34 @@ async function captureCustomEvent(lowLevelServer, eventData) {
     await (0, capture_js_namespaceObject.captureEvent)(lowLevelServer, event);
     (0, logger_js_namespaceObject.log)(`Captured event "${eventData.event}" for session ${trackingData.sessionId}`);
 }
+exports.MCP_SESSION_HEADER = __webpack_exports__.MCP_SESSION_HEADER;
 exports.POSTHOG_MCP_ANALYTICS_SOURCE = __webpack_exports__.POSTHOG_MCP_ANALYTICS_SOURCE;
 exports.PostHog = __webpack_exports__.PostHog;
 exports.PostHogMCP = __webpack_exports__.PostHogMCP;
 exports.PostHogMCPAnalyticsEvent = __webpack_exports__.PostHogMCPAnalyticsEvent;
 exports.PostHogMCPAnalyticsProperty = __webpack_exports__.PostHogMCPAnalyticsProperty;
+exports.decodeSessionId = __webpack_exports__.decodeSessionId;
 exports.deriveSessionIdFromMCPSession = __webpack_exports__.deriveSessionIdFromMCPSession;
+exports.encodeSessionId = __webpack_exports__.encodeSessionId;
 exports.getMoreToolsResult = __webpack_exports__.getMoreToolsResult;
 exports.instrument = __webpack_exports__.instrument;
 exports.instrumentMutator = __webpack_exports__.instrumentMutator;
+exports.newSessionId = __webpack_exports__.newSessionId;
 exports.setLogger = __webpack_exports__.setLogger;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "MCP_SESSION_HEADER",
     "POSTHOG_MCP_ANALYTICS_SOURCE",
     "PostHog",
     "PostHogMCP",
     "PostHogMCPAnalyticsEvent",
     "PostHogMCPAnalyticsProperty",
+    "decodeSessionId",
     "deriveSessionIdFromMCPSession",
+    "encodeSessionId",
     "getMoreToolsResult",
     "instrument",
     "instrumentMutator",
+    "newSessionId",
     "setLogger"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/index.mjs

@@ -8,6 +8,7 @@ import { applyMcpLibIdentity } from "./extensions/lib-identity.mjs";
 import { deriveSessionIdFromMCPSession, getSessionInfo, newSessionId } from "./extensions/session.mjs";
 import { instrumentLowLevelServer } from "./extensions/instrument-lowlevel.mjs";
 import { instrumentHighLevelServer } from "./extensions/instrument-highlevel.mjs";
+import { MCP_SESSION_HEADER, decodeSessionId, encodeSessionId } from "./extensions/session-token.mjs";
 import { POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty } from "./extensions/constants.mjs";
 import { PostHogMCP } from "./extensions/posthog-mcp.mjs";
 import { getMoreToolsResult } from "./extensions/tools.mjs";
@@ -95,4 +96,4 @@ async function captureCustomEvent(lowLevelServer, eventData) {
     await captureEvent(lowLevelServer, event);
     log(`Captured event "${eventData.event}" for session ${trackingData.sessionId}`);
 }
-export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHog, PostHogMCP, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, deriveSessionIdFromMCPSession, getMoreToolsResult, instrument, instrumentMutator, setLogger };
+export { MCP_SESSION_HEADER, POSTHOG_MCP_ANALYTICS_SOURCE, PostHog, PostHogMCP, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, decodeSessionId, deriveSessionIdFromMCPSession, encodeSessionId, getMoreToolsResult, instrument, instrumentMutator, newSessionId, setLogger };

package/dist/types.d.ts

@@ -114,6 +114,13 @@ export interface Event {
     conversationId?: string;
     duration?: number;
     error?: ErrorProperties | null;
+    /**
+     * Coarse failure category → `$mcp_error_type`. An explicit, low-cardinality
+     * label the host can supply (e.g. `validation`, `permission`, `timeout`).
+     * When omitted on an errored call, it falls back to the thrown error's type
+     * (the `$exception_list` entry's `type`).
+     */
+    errorType?: string;
     eventId?: string;
     eventType: MCPAnalyticsEventType;
     groups?: Record<string, string>;
@@ -148,9 +155,16 @@ export interface Event {
 }
 /** A partially-built MCP event as it flows through the SDK before capture. */
 export type McpEvent = Partial<Event>;
+/** HTTP request info the SDK's Streamable HTTP transports attach per request. */
+export interface CompatibleRequestInfoLike {
+    headers?: Record<string, string | string[] | undefined>;
+    [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;
     [key: string]: unknown;
 }
 export interface ServerClientInfoLike {
@@ -170,9 +184,16 @@ export interface HighLevelMCPServerLike {
     tool?(name: string, paramsSchema: unknown, cb: ToolCallback): void;
     tool?(name: string, description: string, paramsSchema: unknown, cb: ToolCallback): void;
 }
+/** The connected transport as exposed by the SDK's `Protocol.transport` getter. */
+export interface CompatibleTransportLike {
+    sessionId?: string;
+    [key: string]: unknown;
+}
 export interface MCPServerLike {
     _requestHandlers: Map<string, (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>>;
     _serverInfo?: ServerClientInfoLike;
+    /** Optional so older SDKs (and bare test doubles) still validate. */
+    transport?: CompatibleTransportLike;
     getClientVersion(): ServerClientInfoLike | undefined;
     setRequestHandler(schema: unknown, handler: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>): void;
 }
@@ -210,11 +231,11 @@ export interface MCPAnalyticsData {
     sink: McpEventSink | undefined;
     identifiedSessions: IdentityCache;
     lastActivity: Date;
-    lastMcpSessionId?: string;
     options: MCPAnalyticsOptions;
     sessionId: string;
     sessionInfo: SessionInfo;
-    sessionSource: 'generated' | 'mcp';
+    /** `token` = recovered from a self-encoded `Mcp-Session-Id` token (see session-token.ts). */
+    sessionSource: 'generated' | 'mcp' | 'token';
     toolCategories: Map<string, string>;
     toolDescriptions: Map<string, string>;
 }
@@ -286,6 +307,13 @@ export interface ToolCallCaptureData extends McpCaptureCommon {
      * synthesized from the tool name.
      */
     error?: unknown;
+    /**
+     * Coarse failure category → `$mcp_error_type` (e.g. `validation`,
+     * `permission`, `timeout`, `rate_limited`). A low-cardinality label that lets
+     * the dashboard break failures down by reason without joining to `$exception`.
+     * When omitted on an error, the SDK falls back to the thrown error's type.
+     */
+    errorType?: string;
 }
 /** Payload for {@link PostHogMCP.captureInitialize}. Emits `$mcp_initialize`. */
 export interface InitializeCaptureData extends McpCaptureCommon {
@@ -317,6 +345,8 @@ export interface ToolsListCaptureData extends McpCaptureCommon {
     isError?: boolean;
     /** The thrown value when `isError` is true → fans out an `$exception` sibling. */
     error?: unknown;
+    /** Coarse failure category → `$mcp_error_type`. Falls back to the thrown error's type. */
+    errorType?: string;
 }
 /** Options for {@link PostHogMCP.prepareToolList}. */
 export interface PrepareToolListOptions {