@posthog/mcp: instrument() silently no-ops on MCP TypeScript SDK v2 servers (string setRequestHandler registrations are never wrapped)

[OrbitingBucket]

Environment

• @posthog/mcp 0.10.7
• @modelcontextprotocol/server 2.0.0 (the new modular SDK v2, stable)
• Server framework: @rekog/mcp-nest 2.0.0 (NestJS microservice strategy; stateless streamable HTTP — a fresh McpServer per request, handlers bound after serverMutator)
• Node 26

Symptom

instrument(server, posthog, options) produces zero telemetry on SDK v2 servers, silently. Because instrument() catches internally and returns a no-op handle, nothing throws — the integration looks healthy while $mcp_* events stop entirely. For a team relying on MCP analytics for adoption reporting, this failure mode is invisible until someone notices flat dashboards.

Three composition defects (in order encountered)

1. High-level compat check requires the removed .tool() method. isCompatibleServerType demands typeof server.tool === "function" for any object with a .server property. SDK v2's McpServer only has registerTool(), so the high-level entry throws (internally). The low-level server.server passes every low-level check (setRequestHandler, _requestHandlers Map, getClientVersion, _serverInfo) — so the gap is narrow.

2. The setRequestHandler patch only recognizes Zod-schema registrations. patchRequestHandlers derives the handler name via getObjectShape(requestSchema) + getLiteralValue(shape.method). SDK v2 (and frameworks built on it) register handlers with string method names: server.setRequestHandler("tools/call", handler). Those fall through unwrapped — so any handler registered after instrument() (the normal order for per-request/stateless servers, where instrumentation runs in a server-mutator hook before handlers are bound) silently replaces the analytics wrapper. Result: no $mcp_tool_call, no $mcp_tools_list, no intent injection.

3. Context/intent ownership is only learned in the tools/list wrapper. cacheToolAnalyticsParameterOwnership runs inside the wrapped tools/list. A stateless server instance serves exactly one request, so a tools/call never shares an instance with a tools/list → analyticsOwnsContext is always false → the context argument is never captured as $mcp_intent (and never stripped from the downstream request), even when wrapping works.

Validated fix (small)

Attached dist-level patch (~10 changed lines, both build variants) that we validated end-to-end through a real NestJS + SDK v2 server (supertest e2e: $mcp_tool_call captured with $mcp_tool_name, $mcp_intent from the injected context parameter, and identified distinct_id):

1. In the patched setRequestHandler, accept string method names:
   const handlerName = typeof requestSchema === "string" ? requestSchema : shape?.method ? getLiteralValue(shape.method) : undefined;
2. In captureToolCall, when data.toolAnalyticsParameterOwnership has no entry for the called tool, lazily resolve ownership by invoking the remembered original tools/list handler (same mechanism isToolAdvertised already uses) and running cacheToolAnalyticsParameterOwnership on the result.

Relaxing the .tool() requirement in isCompatibleServerType (accept registerTool as the high-level marker) would additionally make the documented instrument(mcpServer) / instrumentMutator usage work on SDK v2 instead of requiring callers to pass server.server.

Docs note for identify()

Under SDK v2 dispatch the handler extra no longer carries requestInfo; the HTTP request surfaces at extra.http.req as a web-standard Request (headers via .headers.get("authorization")). identify() implementations written against the v1 extra.requestInfo.headers shape silently return null (anonymous events). Worth documenting alongside v2 support.

Repro (minimal)

import { McpServer } from "@modelcontextprotocol/server";
import { instrument } from "@posthog/mcp";

const server = new McpServer(
  { name: "repro", version: "1.0.0" },
  { capabilities: { tools: { listChanged: true } } },
);
const low = server.server;

instrument(low, posthog, { context: { description: "goal" } }); // low-level entry: compat passes
// Framework binds handlers AFTER instrument, with string method names (SDK v2 style):
low.setRequestHandler("tools/list", () => ({ tools: [{ name: "t", description: "d", inputSchema: { type: "object" } }] }));
low.setRequestHandler("tools/call", async () => ({ content: [{ type: "text", text: "{}" }] }));
// -> wrappers replaced; tools/list advertises NO injected context param; tools/call captures nothing.
// instrument(server, ...) (high-level, as documented) throws internally and no-ops entirely.

Validated patch (dist-level, against 0.10.7)

Happy to port this to the TypeScript source in packages/mcp and open a PR if useful.

Cumulative diff vs pristine 0.10.7 (both build variants)

--- /private/tmp/claude-503/-Users-andreyzaytsev-dev-worktrees-platform-mcp-nest-v2-migration/5ce1d94f-66e6-4de7-9d06-daa14c4800ce/scratchpad/package/dist/extensions/instrumentation.js	1985-10-26 09:15:00
+++ node_modules/@posthog/mcp/dist/extensions/instrumentation.js	2026-08-06 14:38:28
@@ -51,6 +51,19 @@
 async function captureToolCall(params) {
     const { server, data, request, extra, execute, parameterOwnership, eventType, explicitContextIntent, takeCapturedError } = params;
     const resolvedEventType = eventType ?? external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpToolsCall;
+    const lazyToolName = request.params?.name;
+    if (lazyToolName && !data.toolAnalyticsParameterOwnership.has(lazyToolName)) {
+        const lazyListHandler = originalRequestHandlers.get(server)?.get('tools/list');
+        if (lazyListHandler) try {
+            const lazyList = await lazyListHandler({
+                method: 'tools/list',
+                params: {}
+            }, extra);
+            if (lazyList && Array.isArray(lazyList.tools)) cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, lazyList.tools);
+        } catch (lazyError) {
+            data.logger(`Warning: PostHog MCP analytics could not resolve context ownership for "${lazyToolName}" - ${lazyError}`);
+        }
+    }
     const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership, resolvedEventType === external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpMissingCapability);
     const conversation = (0, external_conversation_id_js_namespaceObject.resolveConversationId)(ownership.conversationId, request.params?.arguments, request.params?.name, resolvedEventType === external_event_types_js_namespaceObject.MCPAnalyticsEventType.mcpMissingCapability ? (0, external_tools_js_namespaceObject.resolveMissingCapabilityToolName)(data.options) : '');
     const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership);
@@ -171,7 +184,7 @@
     const originalSetRequestHandler = server.setRequestHandler.bind(server);
     server.setRequestHandler = (requestSchema, originalHandler)=>{
         const shape = (0, external_mcp_sdk_compat_js_namespaceObject.getObjectShape)(requestSchema);
-        const handlerName = shape?.method ? (0, external_mcp_sdk_compat_js_namespaceObject.getLiteralValue)(shape.method) : void 0;
+        const handlerName = 'string' == typeof requestSchema ? requestSchema : shape?.method ? (0, external_mcp_sdk_compat_js_namespaceObject.getLiteralValue)(shape.method) : void 0;
         const patch = 'string' == typeof handlerName ? patches[handlerName] : void 0;
         if (!patch || 'string' != typeof handlerName) return originalSetRequestHandler(requestSchema, originalHandler);
         const result = originalSetRequestHandler(requestSchema, originalHandler);
--- /private/tmp/claude-503/-Users-andreyzaytsev-dev-worktrees-platform-mcp-nest-v2-migration/5ce1d94f-66e6-4de7-9d06-daa14c4800ce/scratchpad/package/dist/extensions/instrumentation.mjs	1985-10-26 09:15:00
+++ node_modules/@posthog/mcp/dist/extensions/instrumentation.mjs	2026-08-06 14:38:28
@@ -16,6 +16,19 @@
 async function captureToolCall(params) {
     const { server, data, request, extra, execute, parameterOwnership, eventType, explicitContextIntent, takeCapturedError } = params;
     const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall;
+    const lazyToolName = request.params?.name;
+    if (lazyToolName && !data.toolAnalyticsParameterOwnership.has(lazyToolName)) {
+        const lazyListHandler = originalRequestHandlers.get(server)?.get('tools/list');
+        if (lazyListHandler) try {
+            const lazyList = await lazyListHandler({
+                method: 'tools/list',
+                params: {}
+            }, extra);
+            if (lazyList && Array.isArray(lazyList.tools)) cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, lazyList.tools);
+        } catch (lazyError) {
+            data.logger(`Warning: PostHog MCP analytics could not resolve context ownership for "${lazyToolName}" - ${lazyError}`);
+        }
+    }
     const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership, resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability);
     const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments, request.params?.name, resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability ? resolveMissingCapabilityToolName(data.options) : '');
     const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership);
@@ -136,7 +149,7 @@
     const originalSetRequestHandler = server.setRequestHandler.bind(server);
     server.setRequestHandler = (requestSchema, originalHandler)=>{
         const shape = getObjectShape(requestSchema);
-        const handlerName = shape?.method ? getLiteralValue(shape.method) : void 0;
+        const handlerName = 'string' == typeof requestSchema ? requestSchema : shape?.method ? getLiteralValue(shape.method) : void 0;
         const patch = 'string' == typeof handlerName ? patches[handlerName] : void 0;
         if (!patch || 'string' != typeof handlerName) return originalSetRequestHandler(requestSchema, originalHandler);
         const result = originalSetRequestHandler(requestSchema, originalHandler);

[github-actions]

AI triage for #4449

Status: Applying triage results

Conclusion: Confirmed MCP SDK v2 compatibility bug in 0.10.7; handler registration and high-level-server support are fixed in later releases, but the stateless low-level context-ownership gap remains.. Applying labels and evaluating fix/close gates.

---

Generated by posthog-watcher-action. This comment will update as the run progresses.

[dustinbyrne]

cc @PostHog/team-mcp-analytics

[lucasheriques]

Hey @OrbitingBucket! We're currently working on the SDK v2 support, which changes how we need to manage state / how to track sessions and instrument the analytics SDK.

We already have some work in progress, so I'll let @gesh answer here since he's the one handling it. Thanks for reporting!

[gesh]

Hey @OrbitingBucket! Thanks for opening the issue.

Currently, we're actively working on supporting SDK v2. I've opened some PRs to update our SDK - they'll be shipped next week.
I'll follow up when it's ready. :))

[p6l-richard]

Hey @gesh following up on your changes, I noticed an issue with the createConversationId feature, so I went ahead an opened an issue about it:
#4483

[OrbitingBucket]

Additional finding from production: $mcp_client_name / $mcp_protocol_version are lost on every event except initialize (stateless SDK v2 servers)

We've now shipped an SDK-v2 server to production (@rekog/mcp-nest 2.0.0 on @modelcontextprotocol/server 2.0.0, streamable HTTP, stateless — one McpServer per request — serving 2025-era clients), so this is measured against real traffic rather than a repro. Sharing because it looks related to the session.ts / transport-identity.ts work in #4462.

Observation. Same production deployment, same clients, @posthog/mcp 0.10.0 → 0.10.7 at the cutover. Client attribution survives on initialize and disappears everywhere else:

Event	SDK	Events	$mcp_client_name filled
$mcp_initialize	0.10.0 (before)	578	100%
$mcp_initialize	0.10.7 (after)	89	100%
$mcp_tool_call	0.10.0 (before)	334	100%
$mcp_tool_call	0.10.7 (after)	29	0%
$mcp_tools_list	0.10.0 (before)	468	100%
$mcp_tools_list	0.10.7 (after)	63	0%

$mcp_protocol_version follows exactly the same pattern (100% → 0% on non-initialize events). Everything else is healthy — identify() resolves correctly (26/29 tool calls carry a real user; the other 3 are a machine-identity runner), $mcp_is_error is 0/29, and $mcp_intent is at 100%.

Why we think it happens. stampMetaClientInfo(event, request) reads client identity off the request. On the 2025-era protocol, clientInfo is only present in the initialize payload — later requests don't carry it. On a stateful/long-lived server that's fine because the connection remembers it, but a stateless server builds a fresh McpServer per request, so there is no session state to carry it forward, and every non-initialize event ends up with nothing to stamp. That the same SDK version still fills initialize at 100% is what points at state carry-over rather than a capability regression: the SDK can read it, there's just nothing to read after the handshake.

Consistent with that, per-request instrumentation also means a new PostHog session id per request — the 63 $mcp_tools_list events above have 63 distinct anonymous ses_* distinct-ids — so the lost client attribution can't be recovered by joining on session either. (Anonymous tools_list isn't new; the 0% client fill is.)

Impact for us. Analytics only, nothing user-facing: we lose the ability to break tool calls down by client, which is how we'd normally notice one client regressing. Worth flagging that it also degrades PostHog's own MCP-analytics surfaces that segment by client for any stateless v2 server.

Possible directions (whatever fits your architecture): carry client identity forward per logical caller — e.g. cache what initialize reported keyed on something stable across requests (the transport/session id where one exists, or the authenticated principal) and stamp subsequent events from that; or, if that's out of scope for stateless servers, document that only initialize carries client attribution there so dashboards can be built accordingly.

Happy to test a candidate fix against our production traffic — we can measure fill rates within minutes of a release. Note this is independent of the $mcp_intent gap on stateless servers we're currently working around locally (context-parameter ownership is only learned inside the tools/list wrapper, which a per-request server never shares with a tools/call).

[gesh]

Hey @OrbitingBucket,
Thanks for flagging this!

We released a few updates yesterday - @posthog/mcp is now on 0.11.4.
Tool calls and errors should be captured on SDK v2 now. Context capturing will be resolved soon as well.

Regarding the client and protocol metadata:

• Does this still reproduce on the latest version?
• Which transport do you use? mcp-nest's streamable HTTP with enableJsonResponse: true, or createMcpHandler directly?