feat(mcp): support MCP Python SDK v2 and cross-SDK parity with TS SDK

.github/workflows/ci.yml

@@ -151,6 +151,44 @@ jobs:
               run: |
                   pytest --verbose --timeout=30
 
+    tests-mcp-v2:
+        # The MCP suite again, against MCP Python SDK v2 (spec 2026-07-28). The
+        # `tests` matrix covers mcp 1.x on every Python version; this lane swaps
+        # in mcp>=2 (and drops jlowin fastmcp, which pins mcp<2) and runs only
+        # posthog/test/mcp — conftest.py there splits collection by major.
+        name: MCP SDK v2 tests (Python ${{ matrix.python-version }})
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ['3.10', '3.14']
+
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  fetch-depth: 1
+
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              with:
+                  python-version: ${{ matrix.python-version }}
+
+            - name: Install uv
+              uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+              with:
+                  version: "0.11.32"
+                  enable-cache: true
+
+            - name: Install test dependencies with MCP SDK v2
+              shell: bash
+              run: |
+                  UV_PROJECT_ENVIRONMENT=$pythonLocation uv sync --extra test
+                  uv pip uninstall --python $pythonLocation fastmcp
+                  uv pip install --python $pythonLocation 'mcp>=2,<3'
+
+            - name: Run MCP tests against SDK v2
+              run: |
+                  pytest posthog/test/mcp --verbose --timeout=30
+
     mutation-tests:
         name: Targeted mutation tests
         runs-on: ubuntu-latest

.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)