Posthog Release Notes

4.63.0

Minor Changes

#4436 80f15a3 Thanks @jakesciotto! - feat(surveys): optional intro screen shown before the first question

Surveys can now display an intro screen before question 1, configured via the new displayIntroScreen, introScreenHeader, introScreenDescription, introScreenDescriptionContentType, and introScreenButtonText appearance fields.

The intro is dismissed with a button and records no response, does not affect completion or partial-response metrics, does not re-fire "survey shown", and is skipped when a survey is resumed with answers in progress. Intro copy is translatable like the thank-you message. renderSurveysPreview accepts previewPageIndex: -1 (exported as INTRO_SCREEN_PREVIEW_INDEX) to preview the intro screen. (2026-08-10)

Patch Changes

Updated dependencies [80f15a3]:

• @posthog/[email protected]

1.415.0

Minor Changes

#4436 80f15a3 Thanks @jakesciotto! - feat(surveys): optional intro screen shown before the first question

Surveys can now display an intro screen before question 1, configured via the new displayIntroScreen, introScreenHeader, introScreenDescription, introScreenDescriptionContentType, and introScreenButtonText appearance fields.

The intro is dismissed with a button and records no response, does not affect completion or partial-response metrics, does not re-fire "survey shown", and is skipped when a survey is resumed with answers in progress. Intro copy is translatable like the thank-you message. renderSurveysPreview accepts previewPageIndex: -1 (exported as INTRO_SCREEN_PREVIEW_INDEX) to preview the intro screen. (2026-08-10)

Patch Changes

Updated dependencies [80f15a3]:

• @posthog/[email protected]

0.11.4

Patch Changes

• #4482 9dd5e6c Thanks @gesh! - Keep the conversation-id prompt-back out of $mcp_error_message.

  With enableConversationId on, a [SERVER]: Reuse conversation_id=… block is appended to a tool result so the agent echoes the handle back on later calls. The captured error was read from that already-appended result, so a failed call reported "intentional failure [SERVER]: Reuse conversation_id=019f…" — a fresh uuid inside the error message on every call, which splits one recurring failure into a new error group each time it happens.

  The error is now read from the result as the tool produced it, before the handle is written in. It bites hardest on MCP SDK v2, where a thrown error is flattened into an isError result before the SDK hands it to us, so that result is the only description of the failure available. The agent still receives the prompt-back on failed calls — that is when it matters most, since otherwise the retry starts a new conversation and the failure and its fix land in different sessions. (2026-08-10)

• #4466 fe3ea18 Thanks @gesh! - Gate Mcp-Session-Id minting on the protocol revision the request declares.

  The 2026-07-28 revision removed protocol-level sessions: a server must not mint or echo Mcp-Session-Id under it. Until now that held only by accident — the mint hangs off the initialize handler and 2026-07-28 has no handshake — so compliance depended on an SDK routing detail rather than on anything the SDK checks.

  The era is now resolved per request, from the version an initialize body declares or, failing that, from the same fallback chain that resolves client identity. Nothing branches on which SDK major is installed: one v2 server serves both revisions, request by request. An unknown version counts as legacy, so a v1 client that declares nothing keeps the session header it has always had. (2026-08-10)

0.11.3

Patch Changes

#4465 9ffdb00 Thanks @gesh! - Record the protocol version for 2025-11-25 traffic served by a per-request server.

That revision carries the negotiated version at the initialize handshake, so an MCP SDK v2 server built per HTTP request has no way to know it: the instance handling a later tools/call never saw the handshake, and a legacy-era request carries no _meta envelope for the identity chain to read. Those events went out with no $mcp_protocol_version.

The chain gains the one carrier that era does have — the MCP-Protocol-Version request header, which 2025-11-25 requires a client to send on every request after initialize. It is read after the protocol-level envelope and params._meta and before the server's own accessors, so a modern-era request still prefers the value the protocol gives it, and no era is branched on. (2026-08-10)

Patch Changes

• #4463 b8e5d06 Thanks @gesh! - Resolve client name, version and protocol version through a fallback chain, so events from an MCP SDK v2 server carry them.

  MCP SDK v2 lifts the reserved io.modelcontextprotocol/* keys — clientInfo, protocolVersion, clientCapabilities — out of params._meta while parsing a request, and puts them on the request envelope. We only read params._meta, which is empty by the time a handler runs, so $mcp_client_name, $mcp_client_version and $mcp_protocol_version went missing on exactly the modern-era traffic that carries them per request rather than at initialize.

  Identity is now resolved field by field through three sources in order: the v2 request envelope, then params._meta, then the server's own getClientVersion() and (v2-only) getNegotiatedProtocolVersion(). A chain rather than a branch, because the same v2 server serves 2025-era requests routinely — era is a per-request property, never a module constant — and because a field one source cannot answer may still be known to the next. (2026-08-10)

• #4464 8b5165e Thanks @gesh! - Install and type-check cleanly on a project that has only MCP SDK v2.

  @modelcontextprotocol/sdk (v1) was a required peer, so installing @posthog/mcp into a project built on @modelcontextprotocol/server (v2) pulled the entire v1 SDK in as an auto-installed peer — 87 packages where 1 was wanted — and tooling that walks the dependency tree reported it as missing when it was absent. Both majors are now declared and both are optional, which is what the code has always assumed: no @modelcontextprotocol/* package is imported at runtime, and server shapes are detected structurally.

  Making the peer optional exposed a second half of the same problem. The published type declarations still imported CallToolResult and ListToolsResult from @modelcontextprotocol/sdk/types.js, so a consumer without the v1 SDK hit TS2307 on an install that otherwise worked — fine at runtime, broken under tsc without skipLibCheck. Those MCP wire shapes are now declared structurally in types.ts too.

  The shapes we read are open-ended, so a value typed by either SDK assigns to them. What the package hands back is typed precisely and stays assignable to the SDK's own CallToolResult, so getMoreToolsResult() can still be returned straight from a tool callback. (2026-08-10)

0.11.1

Patch Changes

#4462 2fc1211 Thanks @gesh! - Instrument high-level McpServer instances from MCP TypeScript SDK v2, and read request headers from either SDK major.

The compatibility gate required typeof server.tool === 'function'. SDK v2 dropped the deprecated tool() in favour of registerTool(), so every v2 high-level server failed the check — and since instrument() catches compatibility failures and returns a working-looking handle, it failed silently: no throw, no warning at the call site, and no $mcp_* events at all. The gate now accepts either registration method, and every shape question it asks is answered by a structural probe in the new detect.ts rather than by a version or protocol constant.

Opening the gate is also what first sends v2-shaped request context to header reads, so both halves ship together. The SDK's own reads go through a new getRequestHeaders(extra), which takes headers from v2's ctx.http.req (a WHATWG Request, whose headers only answer to .get()) as well as v1's extra.requestInfo.headers, and returns a plain lowercase-keyed object either way. It is duck-typed on .entries rather than instanceof Headers, so a Headers from another realm — workerd and other edge runtimes — is read correctly.

getRequestHeaders is exported, because identify, intentFallback, eventProperties and beforeSend still receive the SDK's extra unchanged — we deliberately do not synthesise a v1 requestInfo on v2, as a partially faked shape is worse than an absent one. Hosts reading headers in a callback migrate in one line:

import { getRequestHeaders } from '@posthog/mcp'
identify: async (request, extra) => {
const auth = getRequestHeaders(extra)?.['authorization']
// ...
}

(2026-08-10)

1.47.0

Minor Changes

#4436 80f15a3 Thanks @jakesciotto! - feat(surveys): optional intro screen shown before the first question

Surveys can now display an intro screen before question 1, configured via the new displayIntroScreen, introScreenHeader, introScreenDescription, introScreenDescriptionContentType, and introScreenButtonText appearance fields. The intro is dismissed with a button and records no response, does not affect completion or partial-response metrics, does not re-fire "survey shown", and is skipped when a survey is resumed with answers in progress. Intro copy is translatable like the thank-you message. renderSurveysPreview accepts previewPageIndex: -1 (exported as INTRO_SCREEN_PREVIEW_INDEX) to preview the intro screen. (2026-08-10)

1.414.0

Minor Changes

#4330 5bd8b83 Thanks @darkopia! - Add posthog.conversations.getUnavailableReason() to expose why the conversations API is unavailable (bundle blocked/failed to load, disabled in project, remote config pending/failed, still initializing, …) instead of collapsing every case into isAvailable() === false. Lets callers that fall back to another channel record the specific cause. ConversationsUnavailableReason is exported from the package entry points, so consumers can name the type.

(2026-08-07)

0.11.0

Minor Changes

#4419 e3be62f Thanks @lucasheriques! - Capture the calling client's User-Agent and vendor client header on every auto-captured MCP event, as $mcp_client_user_agent and $mcp_vendor_client.

MCP's own clientInfo can't tell a vendor's products apart — Anthropic reports clientInfo.name = "claude-code" from the CLI, the Agent SDK, the VS Code extension and the desktop app alike, so $mcp_client_name collapses them into one bucket. The surface is only visible in the User-Agent parenthetical (claude-code/2.1.0 (cli) vs (sdk-ts) vs (claude-vscode)), so capturing it is what lets you see which of your integrations traffic actually comes from.

Automatic on HTTP transports (instrument() reads the headers per request); stdio and in-memory servers, which have no headers, are unchanged. On the PostHogMCP custom-dispatcher path, pass clientUserAgent / vendorClient on your capture calls. Both values are recorded raw — PostHog resolves them to friendly product labels at query time, so labels keep improving without an SDK upgrade. (2026-08-07)

Patch Changes

• #4461 f457521 Thanks @gesh! - Wrap request handlers registered with a method string, and stop breaking three-argument registrations. MCP TypeScript SDK v2 calls setRequestHandler('tools/call', handler) where v1 passed a Zod schema, so instrument() could not name those registrations and left them unwrapped — a handler bound after instrument() silently replaced the analytics wrapper, and no $mcp_tool_call or $mcp_tools_list was captured. Frameworks that attach handlers post-construction, such as @rekog/mcp-nest, do exactly this on every request.

  The patched setRequestHandler now also forwards every argument it is given. v2's three-argument form for custom methods — setRequestHandler(method, { params, result }, handler) — previously lost its handler and threw setRequestHandler: handler is required, taking down the host server rather than just instrumentation. (2026-08-07)

• #4450 69e47bd Thanks @gesh! - Register the synthetic tools/call fallback by writing into the server's handler map instead of calling setRequestHandler. Instrumenting a low-level Server that never declared a tools capability no longer fails with Server does not support tools and leaves instrumentation half-applied — it now instruments cleanly, and answers a call for a tool no dispatcher claims with Unknown tool: <name>. This also removes the last runtime @modelcontextprotocol/sdk import from the published bundle; the SDK is now referenced only as a type.

  (2026-08-07)