feat(mcp): support MCP Python SDK v2 and the 2026-07-28 spec revision

instrument() now works on mcp 1.x and 2.x:

- New _instrument_v2 adapters: the high-level MCPServer (renamed FastMCP)
  wraps ToolManager.call_tool — the seam every dispatch routes through —
  and the low-level Server wraps the string-keyed handler registry through
  the public add_request_handler/get_request_handler API, late
  registrations included (the posthog-js#4449 lesson). Strip-vs-leave
  policy per entry point matches the 1.x pair: the high-level path strips
  injected context/conversation_id (v2 validates against the function
  signature), the raw low-level path leaves them optional in the schema.
- _compatibility probes are import-tolerant and shape-based (posthog-js
  ADR-0005): the old module-level `from mcp.server.fastmcp import ...`
  raised ImportError straight out of instrument() on mcp>=2, crashing the
  host app. Unsupported servers now degrade to a logged no-op handle.
- Conversation-anchored sessions (posthog-js ADR-0004): with
  enable_conversation_id, $session_id is derived deterministically from
  the agent-echoed conversation_id — the only correlation that survives
  2026-07-28's per-request instances. Byte-for-byte parity with
  @posthog/mcp (new export derive_session_id_from_conversation), the
  minted-shape (uuidv7) guard so invented handles can't merge unrelated
  callers, lowercased echoes, and the prompt-back riding errored results
  so a first-call failure keeps the conversation together. Applies to the
  1.x adapters too — anchoring is not era-gated.
- Dual-shape attribute reads (isError/is_error, inputSchema/input_schema,
  clientInfo/client_info); captured payloads dump by_alias so both majors
  emit the camelCase wire shape.
- Version advisory widened to mcp>=1.26,<3.

No new runtime dependencies; mcp stays a lazily-imported peer dependency.
jlowin's fastmcp keeps the 1.x seams (it pins mcp<2).

Generated-By: PostHog Code
Task-Id: ebafcb71-b03b-443d-b40c-d527ed4a04f4

Author: gesh

.sampo/changesets/mcp-sdk-v2-support.md

@@ -0,0 +1,5 @@
+---
+posthog: minor
+---
+
+feat(mcp): support the MCP Python SDK 2.x and the 2026-07-28 spec revision. `instrument()` now wraps `mcp.server.mcpserver.MCPServer` (the renamed FastMCP) and the v2 low-level `Server` (constructor-injected handlers, string-keyed registry, late `add_request_handler` registrations included), capturing tool calls, tools/list, errors, intent, client identity, and `$mcp_protocol_version` on both protocol eras — SDK 1.x paths are unchanged. Conversation-anchored sessions land as the cross-pod correlation for the stateless era (parity with `@posthog/mcp`): with `enable_conversation_id`, `$session_id` is derived deterministically from the agent-echoed `conversation_id` (new export `derive_session_id_from_conversation`), only handles the SDK could have minted (uuidv7) anchor, and the prompt-back now rides errored results too so a first-call failure keeps the conversation together. `instrument()` also no longer crashes on an unsupported or unrecognized MCP SDK — it degrades to a logged no-op.

examples/mcp_analytics_demo.py

@@ -19,6 +19,9 @@
 import os
 
 import mcp.types as mcp_types
+
+# MCP SDK 1.x. On mcp>=2 the class moved: `from mcp.server.mcpserver import
+# MCPServer` — instrument() works the same on both.
 from mcp.server.fastmcp import FastMCP
 
 from posthog import Posthog

posthog/mcp/__init__.py

@@ -4,15 +4,23 @@
 
 """PostHog MCP analytics SDK — product analytics for Model Context Protocol servers.
 
-Wrap a Python MCP server (``FastMCP`` or low-level ``mcp.server.Server``) so every
-tool call, agent intent, and failure is captured to PostHog as a ``$mcp_*`` event::
+Wrap a Python MCP server so every tool call, agent intent, and failure is
+captured to PostHog as a ``$mcp_*`` event. Works with the MCP Python SDK 1.x
+*and* 2.x (the 2026-07-28 spec revision) — the high-level server class moved
+between majors, but ``instrument()`` is the same::
 
     from posthog import Posthog
     from posthog.mcp import instrument
-    from mcp.server.fastmcp import FastMCP
+
+    # MCP SDK 2.x (spec 2026-07-28)
+    from mcp.server.mcpserver import MCPServer
+    server = MCPServer("my-server")
+
+    # MCP SDK 1.x
+    # from mcp.server.fastmcp import FastMCP
+    # server = FastMCP("my-server")
 
     posthog = Posthog("phc_...", host="https://us.i.posthog.com")
-    server = FastMCP("my-server")
     analytics = instrument(server, posthog)
 
 Install is just ``pip install posthog``. ``instrument()`` needs the MCP SDK at runtime,
@@ -43,7 +51,11 @@
 )
 from .logger import log, set_logger
 from .posthog_mcp import PostHogMCP
-from .session import derive_session_id_from_mcp_session, new_session_id
+from .session import (
+    derive_session_id_from_conversation,
+    derive_session_id_from_mcp_session,
+    new_session_id,
+)
 from .session_token import (
     MCP_SESSION_HEADER,
     SessionTokenPayload,
@@ -77,6 +89,10 @@
     "PreparedToolCall",
     "get_more_tools_result",
     "derive_session_id_from_mcp_session",
+    # Conversation-anchored sessions: the cross-SDK derivation contract with
+    # posthog-js (the 2026-07-28 revision has no protocol sessions, so the
+    # agent-echoed conversation_id is the only cross-pod session carrier).
+    "derive_session_id_from_conversation",
     # Self-encoded session tokens for stateless / multi-pod servers. Minted onto
     # the `Mcp-Session-Id` response header by PostHogMcpStatelessSessionMiddleware
     # and decoded on every request; codec is exported for custom HTTP layers.
@@ -157,30 +173,35 @@ def _resolve_client(posthog_client: Optional[Client]) -> Optional[Client]:
 
 
 def _warn_if_unsupported_mcp_version() -> None:
-    """The adapters hook private MCP SDK seams (``_tool_manager``, ``_mcp_server``,
-    ``request_handlers``) tested against ``mcp>=1.26,<2``. Since ``mcp`` is a peer
-    dependency we don't pin, advise at runtime when the installed version is outside
-    that range rather than failing hard (older/newer may still mostly work)."""
+    """The adapters hook private MCP SDK seams (``_tool_manager``, ``_mcp_server``
+    / ``_lowlevel_server``, the request-handler registries) tested against
+    ``mcp>=1.26,<3`` — both the 1.x line and the 2.x line (spec 2026-07-28).
+    Since ``mcp`` is a peer dependency we don't pin, advise at runtime when the
+    installed version is outside that range rather than failing hard (older/newer
+    may still mostly work)."""
     try:
         from importlib.metadata import version
 
         installed = version("mcp")
         major, minor = (int(p) for p in installed.split(".")[:2])
     except Exception:  # noqa: BLE001 - never let a version probe break instrument()
         return
-    if (major, minor) < (1, 26) or major >= 2:
+    if (major, minor) < (1, 26) or major >= 3:
         log(
-            f"Warning: PostHog MCP analytics is tested against mcp>=1.26,<2; found {installed}. "
+            f"Warning: PostHog MCP analytics is tested against mcp>=1.26,<3; found {installed}. "
             "Instrumentation hooks private SDK internals and may behave unexpectedly."
         )
 
 
 def _canonical_server(server: Any) -> Any:
-    """The underlying low-level server for high-level wrappers (official FastMCP and
-    jlowin's fastmcp 2.0 both expose ``_mcp_server``), else the server itself. Used as
-    the tracking key so instrumenting a wrapper and its underlying server resolve to
-    one state instead of two divergent ones (matching the TS SDK)."""
-    low_level = getattr(server, "_mcp_server", None)
+    """The underlying low-level server for high-level wrappers (SDK 1.x FastMCP and
+    jlowin's fastmcp expose ``_mcp_server``; SDK 2.x MCPServer renamed it
+    ``_lowlevel_server``), else the server itself. Used as the tracking key so
+    instrumenting a wrapper and its underlying server resolve to one state instead
+    of two divergent ones (matching the TS SDK)."""
+    low_level = getattr(server, "_mcp_server", None) or getattr(
+        server, "_lowlevel_server", None
+    )
     return low_level if low_level is not None else server
 
 
@@ -197,8 +218,9 @@ def instrument(
     state instead of double-wrapping. Degrades to a no-op handle on any failure so
     the host application keeps working.
 
-    :param server: A ``FastMCP`` server (official ``mcp.server.fastmcp`` or jlowin's
-        ``fastmcp`` 2.0) or a low-level ``mcp.server.Server``.
+    :param server: A high-level server — SDK 1.x ``mcp.server.fastmcp.FastMCP``,
+        SDK 2.x ``mcp.server.mcpserver.MCPServer``, or jlowin's ``fastmcp.FastMCP``
+        — or a low-level ``mcp.server.lowlevel.Server`` (either SDK major).
     :param posthog_client: A posthog ``Client`` you construct and own (call
         ``shutdown()`` on exit to flush). Falls back to the global client.
     :param options: Optional :class:`MCPAnalyticsOptions`.
@@ -222,13 +244,20 @@ def instrument(
             "(PostHogMCP for custom dispatchers works without it.)"
         )
     _warn_if_unsupported_mcp_version()
-    from ._compatibility import is_fastmcp, is_fastmcp_v2, is_low_level_server
-    from ._instrument_fastmcp import instrument_fastmcp
-    from ._instrument_lowlevel import instrument_fastmcp_v2, instrument_low_level
 
     key = _canonical_server(server)
 
     try:
+        # Imported inside the try: the adapters touch major-specific modules, and
+        # an import error must degrade to the no-op handle, not crash the host.
+        from ._compatibility import (
+            is_fastmcp,
+            is_fastmcp_v2,
+            is_low_level_server,
+            is_mcpserver,
+            uses_v2_handler_registry,
+        )
+
         client = _resolve_client(posthog_client)
         if client is None:
             log("Warning: no PostHog client available; MCP events will not be sent.")
@@ -242,15 +271,31 @@ def instrument(
         set_server_tracking_data(key, data)
 
         if is_fastmcp(server):
+            from ._instrument_fastmcp import instrument_fastmcp
+
             instrument_fastmcp(server, data)
+        elif is_mcpserver(server):
+            from ._instrument_v2 import instrument_mcpserver_v2
+
+            instrument_mcpserver_v2(server, data)
         elif is_fastmcp_v2(server):
+            from ._instrument_lowlevel import instrument_fastmcp_v2
+
             instrument_fastmcp_v2(server, data)
         elif is_low_level_server(server):
-            instrument_low_level(server, data)
+            if uses_v2_handler_registry(server):
+                from ._instrument_v2 import instrument_lowlevel_v2
+
+                instrument_lowlevel_v2(server, data)
+            else:
+                from ._instrument_lowlevel import instrument_low_level
+
+                instrument_low_level(server, data)
         else:
             raise TypeError(
-                f"Unsupported server type: {type(server)!r}. Pass a FastMCP (official or jlowin's "
-                "fastmcp 2.0) or a low-level mcp.server.Server."
+                f"Unsupported server type: {type(server)!r}. Pass a high-level server "
+                "(mcp.server.fastmcp.FastMCP on SDK 1.x, mcp.server.mcpserver.MCPServer "
+                "on SDK 2.x, or jlowin's fastmcp.FastMCP) or a low-level mcp.server.Server."
             )
 
         # Zero-config stateless minting: wrap the server's ASGI-app factories so a

posthog/mcp/_compatibility.py

@@ -2,21 +2,40 @@
 # Copyright (c) 2025 MCPcat
 # Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
 
-"""Detect which kind of MCP server was passed to ``instrument()``."""
+"""Detect which kind of MCP server was passed to ``instrument()``.
+
+Every probe is import-tolerant: the classes live at different paths per MCP SDK
+major (``mcp.server.fastmcp.FastMCP`` on 1.x, ``mcp.server.mcpserver.MCPServer``
+on 2.x), so a probe whose class doesn't exist on the installed major answers
+``False`` instead of raising — an unconditional import here is exactly what
+would crash ``instrument()`` on the other major.
+"""
 
 from __future__ import annotations
 
 from typing import Any
 
-from mcp.server.fastmcp import FastMCP
-from mcp.server.lowlevel import Server as LowLevelServer
-
 
 def is_fastmcp(server: Any) -> bool:
-    """The official SDK's high-level server (``mcp.server.fastmcp.FastMCP``)."""
+    """The MCP SDK 1.x high-level server (``mcp.server.fastmcp.FastMCP``).
+    The module was renamed in 2.x, so this is False whenever mcp>=2 is installed."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        return False
     return isinstance(server, FastMCP)
 
 
+def is_mcpserver(server: Any) -> bool:
+    """The MCP SDK 2.x high-level server (``mcp.server.mcpserver.MCPServer``,
+    the renamed FastMCP). False whenever mcp<2 is installed."""
+    try:
+        from mcp.server.mcpserver import MCPServer
+    except ImportError:
+        return False
+    return isinstance(server, MCPServer)
+
+
 def is_fastmcp_v2(server: Any) -> bool:
     """jlowin's standalone FastMCP 2.0 (``fastmcp.FastMCP``), a separate package
     from the official SDK. Returns False if ``fastmcp`` isn't installed."""
@@ -28,4 +47,23 @@ def is_fastmcp_v2(server: Any) -> bool:
 
 
 def is_low_level_server(server: Any) -> bool:
+    """The low-level ``mcp.server.lowlevel.Server`` — the import path is the
+    same on both majors; use :func:`uses_v2_handler_registry` to tell which
+    handler seam it carries."""
+    try:
+        from mcp.server.lowlevel import Server as LowLevelServer
+    except ImportError:
+        return False
     return isinstance(server, LowLevelServer)
+
+
+def uses_v2_handler_registry(server: Any) -> bool:
+    """Which major's handler seam a low-level server carries, decided by shape
+    rather than package version (a la posthog-js ADR-0005): 1.x exposes the
+    public ``request_handlers`` dict keyed by request class; 2.x replaced it
+    with ``add_request_handler``/``get_request_handler`` keyed by method string."""
+    if hasattr(server, "add_request_handler") and hasattr(
+        server, "get_request_handler"
+    ):
+        return True
+    return not hasattr(server, "request_handlers")

posthog/mcp/_conversation_id.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import copy
+import re
 from typing import Any, Dict, Optional, Tuple
 
 from .constants import DEFAULT_CONVERSATION_ID_DESCRIPTION
@@ -18,6 +19,16 @@
 
 CONVERSATION_ID_PARAM_NAME = "conversation_id"
 
+# The shape of every id we mint: a uuidv7. Used to tell an echo of our own
+# handle from a value the agent made up. The shape check matters because the
+# handle becomes ``$session_id`` — without it, two unrelated users both sending
+# "conv-1" would share a session (byte-parity with posthog-js's
+# MINTED_CONVERSATION_ID).
+_MINTED_CONVERSATION_ID = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
 
 def add_conversation_id_to_schema(
     input_schema: Optional[Dict[str, Any]], tool_name: str = "unknown"
@@ -71,20 +82,28 @@ def resolve_conversation_id(
     missing_capability_tool_name: str,
 ) -> Tuple[Optional[str], bool]:
     """Return ``(conversation_id, minted)``. Disabled or get_more_tools → ``(None, False)``;
-    agent supplied → ``(value, False)``; agent omitted → ``(new uuid, True)``."""
+    agent echoed a handle we could have minted → ``(value, False)``; anything
+    else (omitted, or a value the agent made up) → ``(new uuid, True)``.
+
+    Lowercased on the way in: the shape test is case-insensitive but the hash
+    behind ``$session_id`` is not, so an uppercased echo (some hosts normalise
+    uuids) would land in a different session than the call that minted it."""
     if not enabled or tool_name == missing_capability_tool_name:
         return None, False
     supplied = extract_conversation_id(args)
-    if supplied:
-        return supplied, False
+    if supplied and _MINTED_CONVERSATION_ID.match(supplied):
+        return supplied.lower(), False
     return _uuid7(), True
 
 
 def can_inject_prompt_back(result: Any) -> bool:
+    """Whether the prompt-back can ride this result's ``content`` — the only
+    requirement is a list to append to. Errored results included on purpose: a
+    tool that fails on the first call of a conversation is exactly when the
+    agent needs the handle, or the retry starts a fresh conversation and the
+    failure and its fix land in different sessions."""
     if not isinstance(result, dict):
         return False
-    if result.get("isError") is True:
-        return False
     return isinstance(result.get("content"), list)
 
 

posthog/mcp/_instrument_fastmcp.py

@@ -101,6 +101,15 @@ async def wrapped(
         request = build_tool_call_request(name, arguments)
         extra: Dict[str, Any] = {"session_id": mcp_session_id}
 
+        # Resolve the conversation handle before the session: when the agent
+        # carries (or is about to receive) one, it anchors $session_id for every
+        # event of this request (ADR-0004) — the only correlation that survives
+        # the 2026-07-28 revision's per-request server instances.
+        missing_name = resolve_missing_capability_tool_name(data.options)
+        conversation_id, minted = resolve_conversation_id(
+            data.options.enable_conversation_id, arguments, name, missing_name
+        )
+
         session_id = await prepare_request(
             data,
             mcp_session_id=mcp_session_id,
@@ -110,9 +119,9 @@ async def wrapped(
             request=request,
             extra=extra,
             token=token,
+            conversation_id=conversation_id,
         )
 
-        missing_name = resolve_missing_capability_tool_name(data.options)
         if data.options.report_missing and name == missing_name:
             await record_missing_capability(
                 data,
@@ -129,10 +138,6 @@ async def wrapped(
                 mcp_types.TextContent(type="text", text=get_more_tools_result_text())
             ]
 
-        conversation_id, minted = resolve_conversation_id(
-            data.options.enable_conversation_id, arguments, name, missing_name
-        )
-
         # Strip each injected key independently. A tool can declare its own
         # `context` (kept) while `conversation_id` is still SDK-injected (stripped),
         # so coupling both to context-ownership leaked conversation_id into the tool.
@@ -328,20 +333,18 @@ def _inject_prompt_back(result: Any, conversation_id: str) -> Any:
     """Append the conversation_id prompt-back to a tool result so the agent echoes
     it on later calls. Handles every shape ToolManager.call_tool can return:
     a ``(content_list, structured)`` tuple (the convert_result=True production path),
-    a bare content list, or a ``{content: [...]}`` dict. Returns the result unchanged
-    (so the caller can detect non-delivery) for shapes we can't append to."""
+    a bare content list, or a ``{content: [...]}`` dict — errored dicts included on
+    purpose (a first-call failure is exactly when the agent needs the handle).
+    Returns the result unchanged (so the caller can detect non-delivery) for
+    shapes we can't append to."""
     block = mcp_types.TextContent(
         type="text", text=build_prompt_back(conversation_id)["text"]
     )
     if isinstance(result, tuple) and len(result) == 2 and isinstance(result[0], list):
         return ([*result[0], block], result[1])
     if isinstance(result, list):
         return [*result, block]
-    if (
-        isinstance(result, dict)
-        and isinstance(result.get("content"), list)
-        and not result.get("isError")
-    ):
+    if isinstance(result, dict) and isinstance(result.get("content"), list):
         return {**result, "content": [*result["content"], block]}
     return result