MCP analytics

MCP analytics helps you understand how AI agents actually use the MCP server you ship: which tools get called, how often, what intent the agent had, where calls are failing, what tools the agent asked for but you don't offer yet, and how individual sessions flow end to end.

The SDK wraps your existing MCP server and emits PostHog events on every tool call, resource read, prompt fetch, and initialize handshake. You can keep using whatever tooling you already have on top of PostHog — insights, dashboards, alerts, error tracking — without any additional ingestion plumbing.

What you can answer

• Which tools is each MCP client calling, and how often?
• What is the agent actually trying to do ($mcp_intent)?
• Which tools are advertised in tools/list responses but never get called?
• What's the error rate and p95 latency of a given tool?
• Did an agent hit get_more_tools because the right capability didn't exist?
• How does a single MCP session unfold across tool calls?

{/ TODO: ProductScreenshot of an MCP analytics dashboard showing tool call volume, error rate, latency, and intent samples /}

How it works

instrument(server, posthog, options?) patches your MCP server's request handlers and returns an analytics handle. The posthog client (a posthog-node instance) is a required positional argument. When the agent calls a tool, the SDK:

1. Builds a structured event with the tool name, parameters, response, duration, and error state.
2. Runs the payload through sanitization (image/audio/binary stubs, sensitive-key masking), truncation, and your optional beforeSend hook.
3. Sends it to PostHog via the posthog-node client you pass in, batched and flushed by that client.

Your tool handlers are untouched. The only payload change the agent sees is an optional injected context argument (see Capturing agent intent) and an optional injected conversation_id argument (see Conversation IDs).

Quick install

npm install @posthog/mcp posthog-node

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",
})

instrument(server, posthog)

That's the minimum. With this in place, every tools/call, tools/list, initialize, resources/read, and prompts/get request emits a PostHog event prefixed with $mcp_*.

Where to go next

• Getting started — the guided onboarding flow
• Installation — full setup, server type variants, BYO PostHog client
• Custom servers — PostHogMCP for hono/edge dispatchers with no server object to wrap
• Capturing agent intent — the context argument and intentFallback
• Conversation IDs — stitching multi-turn conversations together
• Identifying users — attaching events to your own users
• Missing capability tracking — the get_more_tools virtual tool
• Custom events and metadata — analytics.capture() and eventProperties
• Privacy and redaction — what's sanitized automatically, customer redaction hook
• Event and property reference — every event the SDK emits and what's on it
• Sample queries — HogQL recipes for the most common dashboards

Building in public

The SDK source lives in the posthog-js monorepo alongside the rest of PostHog's JavaScript and TypeScript SDKs. Issues, PRs, and feedback are welcome. We started from a duplicated copy of the MIT-licensed MCPcat TypeScript SDK — the event schema, identity model, and feature surface have since diverged.