MCP SDK v2

The MCP TypeScript SDK has two majors. @posthog/mcp supports both and detects which one you're on at runtime — neither is a dependency of the package. The Python MCP SDK made the same split; see Python below.

Use @posthog/mcp 0.11.2 or later on v2. Earlier versions captured nothing, silently.

Setup

Same call as v1. The only difference is where McpServer comes from, and that v2 registers tools with registerTool() instead of the removed server.tool():

import { McpServer } from "@modelcontextprotocol/server"
import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" })
const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN)

instrument(server, posthog, {
  captureModel: true,
  enableConversationId: true,
})

server.registerTool("search_events", { /* ... */ }, async (args) => { /* ... */ })

The low-level Server works the same way. If you previously called instrument(server.server) to get past the old compatibility check, you can go back to instrument(server).

If your callbacks read headers, change them

Use the exported helper in identify, intentFallback, eventProperties and beforeSend. It handles both majors and returns a plain lowercase-keyed object:

import { instrument, getRequestHeaders } from "@posthog/mcp"

instrument(server, posthog, {
  identify: async (request, extra) => {
    const token = getRequestHeaders(extra)?.["authorization"]
    return token ? { distinctId: await resolveUserId(token) } : null
  },
})

Python

The Python SDK supports both official mcp majors (mcp>=1.26,<3) and detects them at runtime. MCP SDK 2.x support requires posthog 7.40.0 or later. On 2.x, FastMCP was renamed — the instrument() call stays the same:

from mcp.server.mcpserver import MCPServer
from posthog.mcp import instrument
from posthog.mcp.types import MCPAnalyticsOptions

server = MCPServer("my-server")
instrument(
    server,
    posthog,
    MCPAnalyticsOptions(enable_conversation_id=True),
)

The low-level Server works on both majors. jlowin's standalone fastmcp package pins mcp<2, so it stays on the 1.x adapter path.

The header gotcha above applies in Python too: request context reaches callbacks in a different shape on each major. Use the exported helper in identify, intent_fallback, and event_properties. It returns a lowercase-keyed dict on HTTP transports, None on stdio, and never raises:

from posthog.mcp import get_request_headers

def identify(request, extra):
    headers = get_request_headers(extra) or {}
    return resolve_user(headers.get("authorization"))

Sessions on 2026-07-28 work as described below. enable_conversation_id=True provides a shared $session_id on that revision, and both PostHog SDKs derive the same session id from the same conversation handle.

Sessions on 2026-07-28

That revision removed the initialize handshake and the Mcp-Session-Id header, so the stateless session token doesn't apply to it — and left alone, every request becomes its own $session_id:

• enableConversationId: true — the only way to get a shared $session_id on this revision. The SDK injects a conversation_id parameter, mints one when the agent doesn't send it, and derives $session_id from it, so a conversation's calls land in one session. Off by default; turn it on if you want sessions.
• identify — attributes calls to a person via distinct_id. Worth wiring up either way, but note it groups by user, not by session, and doesn't give you a $session_id.

Note that revision is a property of each request, not of your server: a v2 server serves 2025-11-25 traffic too, and most clients still negotiate it.

Capture model identity on both revisions

The MCP wire doesn't include the model behind a client on either revision. On TypeScript servers, captureModel: true injects a required llm_model tool argument so the agent can report it. The SDK strips the argument before your handler runs and captures $mcp_llm_model_source = "self_reported" with the answer.

This works on 2025-11-25 and 2026-07-28. The value is unverified, so use it to compare model-level quality and errors, not for billing or security. Model capture hasn't shipped in Python yet.

MCP Apps

@posthog/mcp preserves MCP App tool metadata, ui:// resources, structured tool output, result metadata, HTML, and content security policy metadata on both supported revisions. On the tested high-level McpServer path, injected context and llm_model arguments don't reach the App handler.

The App's tool call is captured with its intent, self-reported model, and protocol version. Automatic analytics for the App's resources/list and resources/read requests on the tested high-level server path haven't shipped yet. The resource payloads still pass through unchanged.

Not instrumented yet

These gaps apply to the TypeScript and Python SDKs alike.

The first two make numbers wrong rather than missing, so check them before trusting a dashboard for task-based or multi-round-trip tools.