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

* fix(mcp): capture standalone FastMCP on the v2 registry

Select the adapter by handler registry so standalone FastMCP 4 captures
tool calls without changing the customer's instrument() invocation.
Preserve application-owned arguments, including mounted tools, and use
native v2 model fields when FastMCP exposes deprecated v1 aliases.

Add HTTP regression coverage for both protocol eras, late tool registration,
repeat instrumentation, failed tools, unavailable capture, and mounted
argument ownership. Include FastMCP 4 in the existing MCP v2 CI matrix,
document adapter behavior, and add a Sampo patch changeset.

Validation on current main: MCP v1 suite 307 passed; MCP v2 suite 291 passed,
13 skipped. Ruff lint/format, filtered mypy (231 source files), import
warning check, and actionlint passed. Real stdio tools emitted HTTP capture
batches to a local receiver under both protocol eras, two events per run.
Authenticated wizard installation and hosted ingestion remain untested.

* fix(mcp): preserve FastMCP schemas across setup order and versions

Keep a weak reference to the standalone FastMCP wrapper in shared tracking
state so a later wrapper install enriches existing low-level instrumentation
without wrapping handlers twice. Resolve schemas for the client-requested
tool version before stripping analytics-owned arguments.

Consolidate adapter imports at the optional MCP dependency boundary instead
of repeating imports in dispatch branches. Keep FastMCP-specific imports
lazy so the official SDK remains usable without that optional package.

Validation: reproduced both setup-order failures and the versioned-tool
argument failure before fixing them. MCP v1 suite 307 passed; MCP v2 suite
296 passed, 13 skipped. Ruff format/lint and filtered mypy passed.
Fresh-process checks passed with MCP absent and with FastMCP absent.

* fix(mcp): strip FastMCP analytics arguments from what was advertised

Decide which analytics parameters to remove before dispatch from the tools/list
the process served, recorded per tool in mutate_tool_schema, instead of asking
FastMCP for the tool schema on every call. The live lookup remains only for tools
never listed here or when the client pins a tool version, and now logs when it
fails. Tools supplied by ToolInjectionMiddleware are listed but not resolvable via
get_tool(), so the per-call lookup advertised `context` and then forwarded it,
failing validation.

Tested: posthog/test/mcp under mcp 2.2.0 + fastmcp 4.0.3 (297 passed, 13
skipped, new middleware test red before the fix) and under mcp 1.30.0 + fastmcp
3.2.0 (307 passed); ruff, mypy-baseline clean.

Reviewer note: tool_model_parameter_injected still exists alongside the new
tool_injected_parameters set because four adapters read it; folding it in is a
follow-up.

Claude-Session: https://claude.ai/code/session_015wZCNFdfPNK9k4utwJ5bMu

* chore(mcp): verify middleware dispatch without schema lookup

Extend FastMCP HTTP coverage to prove middleware tools dispatch when get_tool returns None. Exercise calls before listing, all advertised analytics arguments after listing, and application-owned arguments in both paths. Document why unknown arguments remain intact.

Validation: MCP v1 suite 307 passed; MCP v2 suite 299 passed, 13 skipped. Ruff check and format checks passed for MCP source and tests. Repository-wide filtered mypy passed for 231 source files.

* fix(mcp): resolve FastMCP argument ownership per request

Remove the server-wide injected-parameter cache. Resolve effective schemas with the current request context, middleware, and requested tool version before stripping analytics arguments. Avoid using cached model ownership when schema resolution fails.

Add interleaved-client regression cases for dynamic providers, middleware tools, and middleware overrides in both listing orders. The provider and middleware cases reproduced a missing application-owned llm_model argument before the fix. Document the per-call schema lookup.

Validation: MCP v1 suite 307 passed; MCP v2 suite 305 passed, 13 skipped. Ruff check and format passed for MCP source and tests. Repository-wide filtered mypy passed for 231 files.

Author: lucasheriques

.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

@@ -256,6 +256,16 @@ 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.
+Each tool call resolves the schema through FastMCP's tool listing in the current request context, including middleware and session transforms.
+This adds a schema lookup per call so clients with different tool schemas cannot change how another client's arguments are handled.
+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
 
@@ -276,48 +277,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,11 +31,12 @@
 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
 
-from ._context_parameters import schema_has_param
+from ._context_parameters import is_context_enabled, schema_has_param
 from ._conversation_id import build_prompt_back
 from ._event_types import MCPAnalyticsEventType
 from ._instrumentation import (
@@ -109,7 +110,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)
@@ -422,6 +424,59 @@ 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]]:
+    """Resolve ownership in the current request, including middleware and versions.
+
+    Listings from other requests can have different application-owned parameters.
+    Without a schema, stripping could delete application arguments.
+    """
+    try:
+        from fastmcp.utilities.versions import VersionSpec, version_sort_key
+
+        version_spec = VersionSpec(eq=version) if version else None
+        # Middleware can shadow registered tools, so resolve the effective listing.
+        candidates = [
+            tool
+            for tool in await server.list_tools()
+            if tool.name == name
+            and (version_spec is None or version_spec.matches(tool.version))
+        ]
+        tool = max(candidates, key=version_sort_key, default=None)
+        if tool is None:
+            tool = await server.get_tool(name, version=version_spec)
+        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 = set()
+    if is_context_enabled(data.options.context):
+        injected.add("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):
@@ -431,6 +486,21 @@ 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:
+            version = _requested_tool_version(ctx)
+            injected = await _standalone_injected_parameters(
+                standalone, data, name, version
+            )
+            analytics_owns_model = injected is not None and "llm_model" in injected
+            if injected is not None:
+                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)
         )
@@ -439,9 +509,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

@@ -173,10 +173,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(

posthog/mcp/_internal.py

@@ -89,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

@@ -26,6 +26,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