fix(mcp): restore analytics capture for standalone FastMCP 4

.github/workflows/ci.yml

@@ -155,10 +155,11 @@ jobs:
         # The MCP suite as a named gate per MCP Python SDK major. The v1 leg uses
         # the lockfile's mcp 1.x (also exercised incidentally by the `tests`
         # matrix — this leg exists as an explicit, named signal); the v2 leg
-        # (spec 2026-07-28) swaps in mcp>=2 and drops jlowin fastmcp, which pins
-        # mcp<2. posthog/test/mcp/conftest.py splits collection by major.
+        # (spec 2026-07-28) swaps in mcp>=2 and standalone FastMCP 4, which uses
+        # the v2 registry. posthog/test/mcp/conftest.py splits collection by major.
         name: MCP SDK ${{ matrix.mcp-major }} (Python ${{ matrix.python-version }})
         runs-on: ubuntu-latest
+        timeout-minutes: 20
         strategy:
             matrix:
                 python-version: ['3.10', '3.14']
@@ -189,8 +190,8 @@ jobs:
               if: matrix.mcp-major == 'v2'
               shell: bash
               run: |
-                  uv pip uninstall --python $pythonLocation fastmcp
-                  uv pip install --python $pythonLocation 'mcp>=2,<3'
+                  uv pip uninstall --python "$pythonLocation" fastmcp
+                  uv pip install --python "$pythonLocation" 'mcp>=2,<3' 'fastmcp>=4,<5'
 
             - name: Run MCP tests against SDK ${{ matrix.mcp-major }}
               run: |

.sampo/changesets/chivalrous-witch-goulven.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: patch
+---
+
+Fix missing MCP analytics events with standalone FastMCP 4 while preserving tool arguments and compatibility with MCP SDK v1.

posthog/mcp/README.md

@@ -162,6 +162,14 @@ Neither fires for stdio, for a correctly-wired server, or for a conversation-anc
 session. The instrument-time check can't see whether you added the middleware yourself
 (the app is already built by then), so ignore it if you did.
 
+Standalone `fastmcp` 4 uses the MCP SDK v2 handler registry. `instrument()` detects
+that registry automatically and captures tool calls over stdio and streamable HTTP,
+including the stateless protocol. Mounted tools retain their own arguments; analytics
+parameters are removed before dispatch only when the tool does not declare them.
+Instrumenting both the wrapper and its underlying server works in either order.
+For versioned tools, argument ownership follows the version requested by the client.
+The same installation code continues to support standalone FastMCP 2.x/3.x on MCP SDK v1.
+
 Two gaps worth knowing: jlowin's `fastmcp` 2.x/3.x doesn't expose the attribute the
 instrument-time check reads, so those servers get the runtime warning only. And the
 deprecated SSE transport is excluded — it keys sessions off a query parameter, and the

posthog/mcp/__init__.py

@@ -31,6 +31,7 @@
 
 from __future__ import annotations
 
+import weakref
 from datetime import datetime, timezone
 from typing import Any, Optional
 
@@ -257,48 +258,57 @@ def instrument(
     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.
+        # MCP is an optional peer: load adapters only when instrumentation is
+        # requested, inside the no-crash boundary. Class probes stay major-specific.
         from ._compatibility import (
             is_fastmcp,
             is_fastmcp_v2,
             is_low_level_server,
             is_mcpserver,
             uses_v2_handler_registry,
         )
+        from ._instrument_fastmcp import instrument_fastmcp
+        from ._instrument_lowlevel import instrument_fastmcp_v2, instrument_low_level
+        from ._instrument_v2 import instrument_lowlevel_v2, instrument_mcpserver_v2
 
         client = _resolve_client(posthog_client)
         if client is None:
             log("Warning: no PostHog client available; MCP events will not be sent.")
 
-        if get_server_tracking_data(key) is not None:
+        existing_data = get_server_tracking_data(key)
+        data = existing_data
+        if data is None:
+            sink = McpEventSink(client) if client is not None else None
+            data = MCPAnalyticsData(
+                options=opts, sink=sink, session_id=new_session_id()
+            )
+
+        if is_fastmcp_v2(server) and uses_v2_handler_registry(key):
+            data.standalone_fastmcp = weakref.ref(server)
+
+        # A standalone FastMCP wrapper and its low-level server share one tracking
+        # key, so instrumenting the second of the pair must still attach what only
+        # that object provides: the wrapper's schema lookup and ASGI app factories.
+        if existing_data is not None:
+            autowire_stateless_mint(server)
             log("instrument() - server already instrumented, skipping initialization")
             return McpAnalytics(key)
 
-        sink = McpEventSink(client) if client is not None else None
-        data = MCPAnalyticsData(options=opts, sink=sink, session_id=new_session_id())
         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)
+            if uses_v2_handler_registry(server._mcp_server):
+                instrument_lowlevel_v2(server._mcp_server, data)
+            else:
+                instrument_fastmcp_v2(server, data)
         elif is_low_level_server(server):
             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(

posthog/mcp/_exceptions.py

@@ -56,7 +56,7 @@ def _is_call_tool_result(value: Any) -> bool:
     dict or a pydantic model from the ``mcp`` SDK."""
     if isinstance(value, dict):
         return "isError" in value and isinstance(value.get("content"), list)
-    return hasattr(value, "isError") and isinstance(
+    return (hasattr(value, "is_error") or hasattr(value, "isError")) and isinstance(
         getattr(value, "content", None), list
     )
 

posthog/mcp/_instrument_v2.py

@@ -31,7 +31,8 @@
 from __future__ import annotations
 
 import time
-from typing import Any, Dict, Optional, Tuple
+from collections.abc import Mapping
+from typing import Any, Dict, FrozenSet, Optional, Tuple
 
 import mcp.types as mcp_types
 
@@ -93,7 +94,8 @@ def instrument_lowlevel_v2(server: Any, data: MCPAnalyticsData) -> None:
     """Instrument a raw v2 low-level ``Server``. ``context`` is injected as an
     *optional* schema property and NOT stripped — the schema doubles as the
     call's validation surface, and a typical ``(ctx, params)`` handler ignores
-    extra argument keys."""
+    extra argument keys. For standalone FastMCP, the shared tracking state supplies
+    the tool schemas so injected arguments are removed before validation."""
     data.server_name = getattr(server, "name", None)
     data.server_version = getattr(server, "version", None)
     _wrap_v2_call_tool(server, data)
@@ -394,6 +396,49 @@ def _deliver_conversation_id(
 # --- low-level: tools/call ------------------------------------------------------
 
 
+def _requested_tool_version(ctx: Any) -> Optional[str]:
+    """The FastMCP tool version a client pinned via request ``_meta``, if any."""
+    try:
+        # Standalone FastMCP is optional even when the official MCP SDK is installed.
+        from fastmcp.server.dependencies import extract_version_spec
+
+        params = getattr(ctx, "params", None)
+        meta = params.get("_meta") if isinstance(params, Mapping) else None
+        return extract_version_spec(meta)
+    except Exception:  # noqa: BLE001 - version parsing must not prevent dispatch
+        return None
+
+
+async def _standalone_injected_parameters(
+    server: Any, data: MCPAnalyticsData, name: str, version: Optional[str]
+) -> Optional[FrozenSet[str]]:
+    """Which analytics parameters to strip, derived from the tool's own schema, for
+    a tool this process never listed or a client-pinned version. ``None`` when the
+    tool cannot be resolved. Without a schema, stripping could delete application
+    arguments. Middleware tools normally use the recorded tools/list ownership
+    instead, since they can dispatch without resolving through get_tool()."""
+    try:
+        from fastmcp.utilities.versions import VersionSpec
+
+        tool = await server.get_tool(
+            name, version=VersionSpec(eq=version) if version else None
+        )
+        schema = getattr(tool, "parameters", None)
+    except Exception as error:  # noqa: BLE001 - schema lookup must not prevent dispatch
+        log(f"PostHog MCP: could not resolve schema for tool {name!r} - {error}")
+        return None
+    if not isinstance(schema, dict):
+        return None
+    injected = {"context"}
+    if data.options.enable_conversation_id:
+        injected.add("conversation_id")
+    if is_capture_model_enabled(data.options.capture_model) and (
+        can_inject_model_parameter(schema)
+    ):
+        injected.add("llm_model")
+    return frozenset(key for key in injected if not schema_has_param(schema, key))
+
+
 def _wrap_v2_call_tool(server: Any, data: MCPAnalyticsData) -> None:
     entry = server.get_request_handler(_CALL_METHOD)
     if entry is None or getattr(entry.handler, _WRAPPED_FLAG, False):
@@ -403,6 +448,26 @@ def _wrap_v2_call_tool(server: Any, data: MCPAnalyticsData) -> None:
     async def handler(ctx: Any, params: Any) -> Any:
         name = params.name
         arguments = dict(params.arguments or {})
+        analytics_owns_model = data.tool_model_parameter_injected.get(name, False)
+        standalone = data.standalone_fastmcp() if data.standalone_fastmcp else None
+        if standalone is not None:
+            # The listing this process served is the source of truth for what was
+            # advertised. A client-pinned version may differ from the listed one,
+            # so only then is the tool's own schema consulted.
+            version = _requested_tool_version(ctx)
+            injected = data.tool_injected_parameters.get(name)
+            if injected is None or version is not None:
+                injected = await _standalone_injected_parameters(
+                    standalone, data, name, version
+                )
+            if injected is not None:
+                analytics_owns_model = "llm_model" in injected
+                call_arguments = {
+                    key: value
+                    for key, value in arguments.items()
+                    if key not in injected
+                }
+                params = params.model_copy(update={"arguments": call_arguments})
         token, client_name, client_version, protocol_version, mcp_session_id = (
             _resolve_ctx(ctx)
         )
@@ -411,9 +476,7 @@ async def handler(ctx: Any, params: Any) -> Any:
             name=name,
             arguments=arguments,
             request_meta=request_meta_from_context(ctx),
-            allow_self_reported_model=data.tool_model_parameter_injected.get(
-                name, False
-            ),
+            allow_self_reported_model=analytics_owns_model,
             mcp_session_id=mcp_session_id,
             token=token,
             client_name=client_name,

posthog/mcp/_instrumentation.py

@@ -164,10 +164,10 @@ def is_tool_result_error(result: Any) -> bool:
     (wire JSON unchanged); check both shapes."""
     if isinstance(result, dict):
         return result.get("isError") is True or result.get("is_error") is True
-    return (
-        getattr(result, "isError", None) is True
-        or getattr(result, "is_error", None) is True
-    )
+    is_error = getattr(result, "is_error", None)
+    if is_error is not None:
+        return is_error is True
+    return getattr(result, "isError", None) is True
 
 
 def build_tool_call_request(
@@ -670,6 +670,7 @@ def mutate_tool_schema(
     """
     schema = getattr(tool, schema_attribute, None)
     original_schema = schema
+    injected = set()
     if (
         tool.name != GET_MORE_TOOLS_NAME
         and is_context_enabled(data.options.context)
@@ -681,6 +682,7 @@ def mutate_tool_schema(
             get_context_description(data.options.context),
             required=context_required,
         )
+        injected.add("context")
     if is_capture_model_enabled(data.options.capture_model):
         model_was_injected = data.tool_model_parameter_injected.get(tool.name, False)
         app_owns_model = (
@@ -696,12 +698,16 @@ def mutate_tool_schema(
         data.tool_model_parameter_injected[tool.name] = (
             not app_owns_model and schema_has_param(schema, "llm_model")
         )
+        if data.tool_model_parameter_injected[tool.name]:
+            injected.add("llm_model")
     if (
         tool.name != GET_MORE_TOOLS_NAME
         and data.options.enable_conversation_id
         and not schema_has_param(schema, "conversation_id")
     ):
         schema = add_conversation_id_to_schema(schema, tool.name)
+        injected.add("conversation_id")
+    data.tool_injected_parameters[tool.name] = frozenset(injected)
     if schema is not original_schema:
         try:
             setattr(tool, schema_attribute, schema)

posthog/mcp/_internal.py

@@ -17,7 +17,7 @@
 from collections import OrderedDict
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, Dict, Optional
+from typing import Any, Dict, FrozenSet, Optional
 
 from .logger import log
 from ._sink import McpEventSink
@@ -73,6 +73,11 @@ class MCPAnalyticsData:
     # True only when PostHog added llm_model to this tool's advertised schema.
     # Missing/False fails closed so an application-owned field is never read or stripped.
     tool_model_parameter_injected: Dict[str, bool] = field(default_factory=dict)
+    # Every analytics parameter PostHog added to a tool's advertised schema at
+    # tools/list. Standalone FastMCP validates arguments against the tool's own
+    # schema, so exactly these keys are stripped before dispatch. Absent means
+    # "never served a listing for this tool" and falls back to a live lookup.
+    tool_injected_parameters: Dict[str, FrozenSet[str]] = field(default_factory=dict)
     # Which tools got `_mcp_instructions` declared on their advertised output
     # schema at tools/list. Only those may be mirrored into on a call — writing
     # an undeclared key fails the customer's whole result under
@@ -84,6 +89,8 @@ class MCPAnalyticsData:
     initialized_sessions: "OrderedDict[str, None]" = field(default_factory=OrderedDict)
     server_name: Optional[str] = None
     server_version: Optional[str] = None
+    # A strong wrapper reference would retain the low-level WeakKeyDictionary key.
+    standalone_fastmcp: Optional["weakref.ReferenceType[Any]"] = None
     session_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
 
     def mark_session_initialized(self, session_id: str) -> None:

posthog/mcp/_output_instructions.py

@@ -37,8 +37,8 @@
 _CONVERSATION_ID_FIELD_DESCRIPTION = "The server-issued conversation identifier."
 
 # `outputSchema` on MCP SDK 1.x models, `output_schema` on 2.x (same wire field).
-_OUTPUT_SCHEMA_ATTRS = ("outputSchema", "output_schema")
-_STRUCTURED_CONTENT_ATTRS = ("structuredContent", "structured_content")
+_OUTPUT_SCHEMA_ATTRS = ("output_schema", "outputSchema")
+_STRUCTURED_CONTENT_ATTRS = ("structured_content", "structuredContent")
 
 
 def _read_attr(obj: Any, names: Tuple[str, ...]) -> Tuple[Optional[str], Any]:

posthog/test/mcp/conftest.py

@@ -25,6 +25,7 @@
     "test_v2_mcpserver.py",
     "test_v2_lowlevel.py",
     "test_v2_wire_dual_era.py",
+    "test_fastmcp_v4.py",
 ]
 
 collect_ignore = _V2_ONLY if MCP_MAJOR < 2 else _V1_ONLY