Installing the MCP analytics SDK

Requirements

• Node.js 18 or later (TypeScript/JavaScript), or Python 3.10+ — see Python below
• An MCP server built on @modelcontextprotocol/sdk (TS) or the mcp package (Python). (Running a custom dispatcher with no server object to wrap? See Custom servers.)
• A PostHog project API key (phc_…)

Install

npm install @posthog/mcp posthog-node
# or pnpm add @posthog/mcp posthog-node
# or yarn add @posthog/mcp posthog-node

You bring your own posthog-node client (the same pattern as @posthog/ai) and pass it to instrument() as the required second argument. You own its lifecycle — call posthog.shutdown() or posthog.flush() yourself.

Wrap your server

instrument(server, posthog, options?) is the only function you need to call. The posthog client is a required positional argument; options is optional. It returns an analytics handle (used for custom events). It's idempotent per server — calling it twice on the same server logs a warning and returns early.

Low-level Server

If you registered your tools against the raw protocol Server from @modelcontextprotocol/sdk/server/index.js:

import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const server = new Server({ name: "my-mcp-server", version: "1.0.0" })

const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY, {
  host: "https://us.i.posthog.com", // or https://eu.i.posthog.com
})

// register your tools as usual...

const analytics = instrument(server, posthog)

High-level McpServer

If you use the typed McpServer wrapper from @modelcontextprotocol/sdk/server/mcp.js, pass it in directly — the SDK will unwrap it and also install a proxy on _registeredTools, so any tool you register after instrument() is also wrapped:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
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_API_KEY, {
  host: "https://us.i.posthog.com",
})

const analytics = instrument(server, posthog)

server.tool("search_events", { /* ... */ }, async (args) => {
  // your handler runs untouched
})

Python

A Python SDK ships inside the posthog package (the same way posthog.ai does). Install it with the mcp extra:

pip install posthog[mcp]

instrument(server, posthog_client, options?) works with every common Python MCP server:

• FastMCP and the low-level Server from the official modelcontextprotocol/python-sdk (the mcp package)
• jlowin's standalone FastMCP 2.0 (the separate fastmcp package)
• PostHogMCP for custom dispatchers with no server object (see below)

from posthog import Posthog
from posthog.mcp import instrument
from mcp.server.fastmcp import FastMCP

posthog = Posthog(
    "phc_your_project_api_key",
    host="https://us.i.posthog.com",  # or https://eu.i.posthog.com
)
server = FastMCP("my-server")

# register your tools as usual...

analytics = instrument(server, posthog)

Options are passed as MCPAnalyticsOptions, the snake_case equivalent of the TypeScript options:

from posthog.mcp import instrument
from posthog.mcp.types import MCPAnalyticsOptions, UserIdentity

instrument(server, posthog, MCPAnalyticsOptions(
    context=True,                 # inject the `context` intent argument (default)
    report_missing=True,          # register the get_more_tools virtual tool
    enable_conversation_id=True,  # stitch calls across reconnects
    identify=lambda request, extra: UserIdentity(distinct_id="user_123"),
))

MCPAnalyticsOptions fields (the TypeScript Configuration table below uses camelCase — these are the Python names):

Flushing on exit

The posthog client batches events asynchronously and you own its lifecycle. On the instrument() path, auto-captured events are scheduled in the background — await analytics.flush() waits for in-flight events, then posthog.flush() / posthog.shutdown() sends them. Call this from your shutdown/SIGTERM handler so trailing events aren't dropped (see examples/mcp_analytics_demo.py for a runnable end-to-end example):

analytics = instrument(server, posthog)
# ... serve ...
await analytics.flush()   # drain in-flight auto-capture events
posthog.shutdown()        # flush + stop the posthog client

No server object to wrap (a custom HTTP/edge dispatcher)? Use PostHogMCP, a posthog client subclass with capture_tool_call(), capture_initialize(), prepare_tool_list(), and prepare_tool_call() — the Python equivalent of Custom servers.

Configuration

The posthog client is passed as the required second positional argument — not in this options object. instrument() accepts these options as an optional third argument:

Graceful shutdown

The posthog-node client queues and batches events asynchronously, and you own its lifecycle. Call posthog.shutdown() from your SIGTERM / beforeExit handler so in-flight events aren't dropped:

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

const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY)
instrument(server, posthog)

process.on("SIGTERM", async () => {
  await posthog.shutdown()
  process.exit(0)
})

If you only want to drain the queue without tearing the client down, call posthog.flush() instead.

In serverless or edge environments where SIGTERM isn't reliable, flush explicitly at the end of each invocation — await posthog.flush(), or ctx.waitUntil(posthog.flush()) on platforms that support it — rather than relying on a shutdown signal.

What happens after install

As soon as the wrapper is in place, every MCP request handled by the server emits a PostHog event:

• $mcp_tool_call per tool invocation
• $mcp_tools_list per tools/list response
• $mcp_initialize per client handshake
• $mcp_resource_read, $mcp_resources_list, $mcp_prompt_get, $mcp_prompts_list as applicable
• $exception whenever a tool throws or returns isError: true

All events share a $session_id derived from the MCP protocol session (so the same connection always maps to the same PostHog session). See the event reference for the full catalog.