How to set up MCP analytics and error tracking

Jul 07, 2026

Contents

New: instrument your MCP server in one command

Since this tutorial was published, we've shipped @posthog/mcp – an official (beta) SDK that captures every tool call, error, and the agent's intent automatically. You can set it up with a single instrument(server, posthog) call, or let our wizard do it for you with one command. No wrapper code required. The manual approach below still works and is a great way to understand what's happening under the hood, but most servers should reach for the SDK first.

MCP servers give LLMs powerful capabilities, but without analytics and error tracking you're flying blind with no visibility into usage or performance. Which tools get called? How often? Where are the bottlenecks? What's failing?

There are two ways to add this to your MCP server:

  1. The quick way – install the official @posthog/mcp SDK and call instrument() once. This is the recommended path for most servers.
  2. The manual way – wrap each tool handler yourself with a small higher-order function. This takes more code, but it's a great way to understand the mechanics and gives you full control.

We'll cover the SDK first, then walk through the manual pattern so you can see exactly what the SDK does for you.

The full source code for the manual approach is available in this GitHub repository.

The quick way: the @posthog/mcp SDK

@posthog/mcp wraps your MCP server and captures analytics automatically – no per-tool instrumentation. It supports any TypeScript MCP server built on @modelcontextprotocol/sdk.

The fastest way to set it up is our wizard, which installs the package, adds your posthog-node client, and wires up the instrument() call for you (it also works with LLM coding agents like Cursor):

Learn more

Prefer to do it by hand, or want to see exactly what the wizard wires up? Install the SDK alongside the PostHog Node.js SDK:

Terminal
npm install @posthog/mcp posthog-node

Then call instrument(server, posthog) once at startup. You bring your own posthog-node client and pass it in as the second argument:

typescript
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", // or https://eu.i.posthog.com
})


// Register your tools as usual – their handlers run untouched.
instrument(server, posthog)

That's it. From the first tool call, the SDK emits PostHog events automatically, all prefixed with $mcp_* so they never collide with your other data and all sharing a $session_id derived from the MCP protocol session:

  • $mcp_tool_call for every tool invocation (with parameters, response, duration, and error status)
  • $mcp_tools_list for every tools/list response, so you can compare advertised vs. called tools
  • $mcp_initialize for every client handshake (including the MCP client name and version)
  • $exception whenever a tool throws or returns isError: true, wired into error tracking

It also unlocks signals the manual approach can't easily capture, each a one-line option on instrument():

Remember to drain queued events on shutdown by calling posthog.shutdown() (or posthog.flush()) from your SIGTERM handler, since you own the client's lifecycle.

Note: @posthog/mcp is in beta (pre-1.0). The API may still change – including breaking changes in minor 0.x releases – so pin a specific version while we iterate. Running a custom dispatcher with no server object to wrap? See Custom servers.

To go deeper, see the getting started guide, the installation docs, and the event reference.

Building it yourself (how it works under the hood)

Prefer full control, want to understand the mechanics, or building something the SDK doesn't cover yet? The rest of this tutorial walks through the manual wrapper pattern – essentially a hand-rolled version of what instrument() does for you. This implementation tracks every tool execution without touching core business logic.

In the finished setup, the MCP server:

  • Tracks execution time for every tool call
  • Captures errors with context
  • Sends data to PostHog

Prerequisites

  • Node.js 18+
  • PostHog account (sign up for free)
  • Claude Desktop or another MCP client to test your MCP server
  • Basic TypeScript knowledge
  • Code editor (e.g., VS Code, Cursor)

MCP's design and the wrapper pattern

MCP servers have an architecture that makes the wrapper pattern a natural fit for extended functionality like analytics and error tracking.

Why? MCP's functional design means wrapper patterns work seamlessly, unlike other web frameworks with middleware pipelines or class-based systems with decorators.

Here's what the boilerplate code looks like for MCP tool registration:

typescript
// This is how MCP tools are registered, already functional style
server.tool(
  "toolName",
  { /* schema */ },
  { /* metadata */ },
  async (args) => { /* handler function */ }
);

Since MCP tools are mostly just async functions passed to server.tool(), wrapping the handler function is a clean and lightweight way of adding or extending functionality – in this case, analytics and error tracking.

1. MCP server setup

To get us started quickly, we've built an MCP server for you to add product analytics and error tracking to. Start by cloning the repository.

Terminal
git clone https://github.com/arda-e/mcp-posthog-analytics.git

Next, install the dependencies.

Terminal
npm install

Finally, build the server.

Terminal
npm run build

You should see a /build directory with the compiled MCP server in the root of the project. Your directory structure should look like this:

MCP-POSTHOG-ANALYTICS/
├── build/
│   ├── analytics.js
│   ├── index.js
│   ├── posthog.js
│   ├── server.js
│   └── tools.js
├── node_modules/
├── src/
├── .env.example
├── .gitignore
├── claude_desktop_config_example.json
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

2. Tool definitions

Now that we built our MCP server, let's take a look our MCP tools in the tools.ts file.

For this tutorial, we've hardcoded simple datasets and results for the tools to fetch.

./src/tools.ts
/**
* In-memory inventory (pretend this is a database)
*/
const products = [
  { id: "1", name: "Laptop", price: 999, stock: 5 },
  { id: "2", name: "Mouse", price: 29, stock: 50 },
  { id: "3", name: "Keyboard", price: 79, stock: 25 }
];


export async function getInventory() {
  console.error("[Tool] getInventory called");
  return {
    content: [
      { type: "text" as const, text: JSON.stringify(products, null, 2) }
    ]
  };
}


export async function checkStock(productId: string) {
  console.error(`[Tool] checkStock called for product: ${productId}`);


  const product = products.find((p) => p.id === productId);
  if (!product) {
    throw new Error(`Product ${productId} not found`);
  }


  return {
    content: [
      { type: "text" as const, text: `${product.name}: ${product.stock} units in stock` }
    ]
  };
}


export async function analyzeData(data: string) {
  console.error(`[Tool] analyzeData called with data: ${data}`);
  await new Promise(resolve => setTimeout(resolve, 1000));
  return {
    content: [
      { type: "text" as const, text: `Analyzed data: ${data}` }
    ]
  };
}


export async function riskyOperation() {
  console.error("[Tool] riskyOperation called");
  const success = Math.random() > 0.5;
  if (!success) {
    throw new Error("Risky operation failed");
  }
  return {
    content: [
      { type: "text" as const, text: "Risky operation succeeded" }
    ]
  };
}

Notice that these tools contain only business logic, with zero dependencies on analytics or error tracking libraries. Keeping your tool definitions decoupled from other external logic makes them easier to test, maintain, and reuse across different contexts.

3. MCP analytics provider interface

Next, let's take a look at the TypeScript interface for the MCP analytics provider in the analytics.ts file. It defines a standard set of methods for sending analytics data from your MCP server.

It has three core abilities:

  1. Track tool calls
  2. Capture errors
  3. Close the analytics client
./src/analytics.ts
export interface AnalyticsProvider {
  /**
   * Track a successful tool execution with timing information
   * @param toolName - Name of the tool that was executed
   * @param result - Execution results including duration and success status
   */
  trackTool(toolName: string, result: any): Promise<void>;
  
  /**
   * Track an error that occurred during tool execution
   * @param error - The error object that was thrown
   * @param context - Additional context about the error (tool name, duration, etc.)
   */
  trackError(error: Error, context: any): Promise<void>;
  
  /**
   * Gracefully shut down the analytics client and flush pending events
   */
  close(): Promise<void>;
}

This approach makes your code testable and flexible.

Think of the interface as a generic adapter for analytics calls. Want to use a different analytics provider? Write a new implementation. Need to debug locally? Create a file-based logger. Running tests? Use a no-emit version that tracks calls without sending data.

4. withAnalytics() wrapper

In the same analytics.ts file, let's explore the core design pattern: the withAnalytics() wrapper that intercepts every tool call. The wrapper function is responsible for invoking the analytics provider methods defined in the previous step.

The withAnalytics() function:

  • Times every tool call execution
  • Tracks success/failure
  • Preserves normal error handling
  • Works without an analytics provider
./src/analytics.ts
export async function withAnalytics<T>(
  analytics: AnalyticsProvider | undefined,
  toolName: string,
  handler: () => Promise<T>
): Promise<T> {
  const start = Date.now();
  
  try {
    const result = await handler();
    const duration_ms = Date.now() - start;
    
    // Track successful execution
    await analytics?.trackTool(toolName, { 
      duration_ms, 
      success: true 
    });
    
    return result;
    
  } catch (error) {
    const duration_ms = Date.now() - start;
    
    // Track the error with context
    await analytics?.trackError(error as Error, {
      tool_name: toolName,
      duration_ms
    });
    
    throw error; // Re-throw so MCP handles it normally
  }
}

5. PostHog product analytics and error tracking

Now let's send those analytics somewhere useful. In the posthog.ts file, we initialize the PostHog client that implements the AnalyticsProvider interface and extends it with the necessary calls to capture data and send it to PostHog.

The PostHogAnalyticsProvider class leverages the PostHog Node.js SDK to capture custom events for product analytics and exceptions for built-in error tracking.

./src/posthog.ts
import { PostHog } from "posthog-node";
import { AnalyticsProvider } from "./analytics.js";


export class PostHogAnalyticsProvider implements AnalyticsProvider {
  private client: PostHog | null;
  private mcpInteractionId: string;


  /**
   * Initializes the analytics client with a unique session ID.
   */
  constructor(
    apiKey: string,
    options?: { host?: string; }
  ) {
    this.client = new PostHog(apiKey, { host: options?.host });
    this.mcpInteractionId = `mcp_${Date.now()}_${process.pid}`;


    console.error(
      `[Analytics] Initialized with session ID: ${this.mcpInteractionId}`
    );
  }


  async trackTool(
    toolName: string,
    result: {
      duration_ms: number;
      success: boolean;
      [key: string]: any;
    }
  ): Promise<void> {
    this.client?.capture({
      distinctId: this.mcpInteractionId,
      event: "tool_executed",
      properties: { tool_name: toolName, ...result },
    });


    console.error(
      `[Analytics] ${toolName}: ${result.success ? "✓" : "✗"} (${
        result.duration_ms
      }ms)`
    );
  }


  async trackError(
    error: Error,
    context: {
      tool_name: string;
      duration_ms: number;
      args?: Record<string, unknown>;
      [key: string]: any;
    }
  ): Promise<void> {


    this.client?.captureException(error, this.mcpInteractionId, {
      duration_ms: context.duration_ms,
      tool_name: context.tool_name,
    });


    console.error(
      `[Analytics] ERROR in ${context.tool_name}: ${error.message}`
    );
  }


  async close(): Promise<void> {
    try {
      // If you wish to continue using PostHog after closing the client,
      // you can use client.flush() instead of client.shutdown()
      await this.client?.shutdown();
      console.error("[Analytics] Closed");
    } catch (error) {
      console.error("[Analytics] Error during close:", error);
    }
  }
}

6. Registering tools using withAnalytics()

Now let's see how these tools are registered with the MCP server in the server.ts file.

src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import * as tools from "./tools.js";
import { z } from "zod";
import { AnalyticsProvider, withAnalytics } from "./analytics.js";


export interface StdioServerHandle {
  server: McpServer;
  transport: StdioServerTransport;
}


async function buildStdioServer(analytics?: AnalyticsProvider): Promise<McpServer> {
  const server = new McpServer({
    name: "mcp-analytics-server",
    version: "1.0.0",
    capabilities: {
      resources: {},
      tools: {},
    },
  });


  server.tool(
    "getInventory",
    {},
    { title: "Get product inventory" },
    async () => withAnalytics(analytics, "getInventory", () => tools.getInventory())
  );


  server.tool(
    "checkStock",
    { productId: z.string() },
    { title: "Get stock for a specified product" },
    async (args) => withAnalytics(analytics, "checkStock", () => tools.checkStock(args.productId))
  );


  server.tool(
    "analyze_data",
    { data: z.string() },
    { title: "Analyze data (slow)" },
    async (args) => withAnalytics(analytics, "analyze_data", () => tools.analyzeData(args.data))
  );




  server.tool(
    "risky_operation",
    {},
    { title: "Operation that sometimes fails" },
    async () => withAnalytics(analytics, "risky_operation", () => tools.riskyOperation())
  );


  return server;
}

Notice how each tool handler function is wrapped with the withAnalytics() wrapper we saw earlier. Every tool call is tracked by the PostHogAnalyticsProvider class, capturing analytics, tracking errors, and sending data to PostHog.

7. Injecting the PostHogAnalyticsProvider

In the main index.tsx file, the PostHogAnalyticsProvider is injected into the MCP server on initialization.

./src/index.ts
import "dotenv/config";
import { startStdioServer, stopStdioServer } from "./server.js";
import { AnalyticsProvider } from "./analytics.js";
import { PostHogAnalyticsProvider } from "./posthog.js";


const apiKey = process.env.POSTHOG_API_KEY;
const host = process.env.POSTHOG_HOST;


async function main() {
  let analytics: AnalyticsProvider | undefined = undefined;
  
  if(!apiKey) {
    console.error("[SERVER] POSTHOG_API_KEY is not set, continue without analytics");
  }


  try {
    if(apiKey) analytics = new PostHogAnalyticsProvider(apiKey, { host });
    const handle = await startStdioServer(analytics);


    process.on("SIGINT", async () => await stopStdioServer(handle,analytics));
    process.on("SIGTERM", async () => await stopStdioServer(handle, analytics));


    await new Promise(() => {});


  } catch (err) {
    console.error("[SERVER] Error during server startup:", err);
    process.exit(1);
  }
}


(async () => {
  await main();
})();

8. Testing the MCP server

Now we can test our MCP server with Claude Desktop, or any compatible MCP client, to see MCP analytics in action.

Note: The client will run our server as a child process so we don't need to run our server in our terminal. We modify the Claude's config file to make sure the Claude Desktop can run our build.

Open Claude Desktop's Settings > Developer. Then select Edit Config to open the configuration file.

Update the claude_desktop_config.json file to include the following:

JSON
{
  "mcpServers": {
    "analytics-demo": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-posthog-analytics/build/index.js"],
      "env": {
        "POSTHOG_API_KEY": "<ph_project_token>",
        "POSTHOG_HOST": "https://us.i.posthog.com"
      }
    }
  }
}

It should look like the following in Claude Desktop's Settings > Developer:

Claude Desktop config file

You can then try these prompts:

  • "Show me the inventory" → Should successfully return the inventory.
  • "Check stock for product 999" → Should throw an error.
  • "Analyze this data: quarterly sales" → Simulates a slow operation.
Our MCP server executing tool calls.

9. Create MCP analytics dashboards

Now that our MCP server is creating MCP analytics and sending them as events to PostHog, we can build insights and dashboards in PostHog to visualize the data. We can set up:

  • Performance dashboards
  • Reliability dashboards
  • Usage dashboards
MCP analytics PostHog events
MCP analytics sent to PostHog as captured events and exceptions

P95 latency by tool
P95 duration by tool (ms)

Tool calls over time
Tool calls over time to understand usage

Tool calls over time
Tool call error tracking with stack traces

Further reading

This tutorial was written by Arda Eren, a very rad member of the PostHog community.

PostHog is the leading platform for building self-driving products. With a full suite of developer tools – AI observability, product analytics, session replay, feature flags, experiments, error tracking, logs, and more – PostHog captures all the context agents need to diagnose problems, uncover opportunities, and ship fixes. A data warehouse and CDP tie it all together, unifying that context into one source agents can read across. You can steer it all from Slack, the web app, the desktop (PostHog Desktop), or your own editor via the MCP.

Community questions