Installing the MCP analytics SDK

Requirements

• Node.js 18 or later
• A TypeScript or JavaScript MCP server built on @modelcontextprotocol/sdk. (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
})

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.