> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PostHog

> Send MCP analytics events to PostHog as product analytics.

## Overview

Integrate AgentCat with PostHog for product analytics. Events are sent as `capture` events via the PostHog `/batch` API, giving you full visibility into MCP tool usage within your existing PostHog dashboards.

## Prerequisites

1. A PostHog project with an API key (starts with `phc_...`)
2. Your PostHog host URL (default: `https://us.i.posthog.com`)

## Configuration

<CodeGroup>
  ```typescript TypeScript theme={null}
  agentcat.track(server, null, {
    exporters: {
      posthog: {
        type: "posthog",
        apiKey: process.env.POSTHOG_API_KEY,
        host: "https://us.i.posthog.com"
      }
    }
  })
  ```

  ```python Python theme={null}
  agentcat.track(server, None, agentcat.AgentCatOptions(
    exporters={
      "posthog": {
        "type": "posthog",
        "api_key": os.getenv("POSTHOG_API_KEY"),
        "host": "https://us.i.posthog.com"
      }
    }
  ))
  ```

  ```go Go theme={null}
  mcpcat.Track(s, "", &mcpcat.Options{
      Exporters: map[string]any{
          "posthog": map[string]any{
              "type":   "posthog",
              "apiKey": os.Getenv("POSTHOG_API_KEY"),
              "host":   "https://us.i.posthog.com",
          },
      },
  })
  ```
</CodeGroup>

## Configuration Fields

| Field                | Type   | Required | Description                                                                                                                     |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `api_key` / `apiKey` | string | Yes      | Your PostHog project API key (starts with `phc_...`)                                                                            |
| `host`               | string | No       | PostHog host URL (default: `https://us.i.posthog.com`). Use `https://eu.i.posthog.com` for EU, or your own URL for self-hosted. |

## Field Mapping

### Event Names

AgentCat events are sent as PostHog `capture` events. Standard MCP event types are mapped to PostHog-friendly names. Any unmapped event types fall back to replacing colons and slashes with underscores.

| MCP Event Type       | PostHog Event Name   |
| -------------------- | -------------------- |
| `mcp:tools/call`     | `mcp_tool_call`      |
| `mcp:tools/list`     | `mcp_tools_list`     |
| `mcp:initialize`     | `mcp_initialize`     |
| `mcp:resources/read` | `mcp_resource_read`  |
| `mcp:resources/list` | `mcp_resources_list` |
| `mcp:prompts/get`    | `mcp_prompt_get`     |
| `mcp:prompts/list`   | `mcp_prompts_list`   |

### Distinct ID

PostHog's `distinct_id` is set using the following priority:

1. **Identified user ID** — if the user was identified via the `identify` callback
2. **Session ID** — falls back to the AgentCat session ID
3. **`"anonymous"`** — if neither is available

### Event Properties

Each event includes the following properties:

| Property         | Description                             |
| ---------------- | --------------------------------------- |
| `$session_id`    | AgentCat session ID                     |
| `resource_name`  | Resource or tool name                   |
| `tool_name`      | Tool name (only for tool call events)   |
| `duration_ms`    | Event duration in milliseconds          |
| `server_name`    | MCP server name                         |
| `server_version` | MCP server version                      |
| `client_name`    | AI client name (e.g., "Claude Desktop") |
| `client_version` | AI client version                       |
| `project_id`     | AgentCat project ID                     |
| `user_intent`    | Agent's stated intent for the tool call |
| `is_error`       | Whether the event was an error          |
| `parameters`     | Request parameters                      |
| `response`       | Tool response data                      |

### Person Properties

When a user is identified, PostHog person properties are set via `$set`:

* `name` — the identified user's name
* Any additional fields from `identifyActorData` are merged in

### Error Events

When `is_error` is `true`, AgentCat sends **two** events to PostHog:

1. **Regular capture event** — the standard event with all properties above
2. **`$exception` event** — a native PostHog exception event with:

| Property                | Description                                |
| ----------------------- | ------------------------------------------ |
| `$exception_message`    | Error message                              |
| `$exception_type`       | Error type or class                        |
| `$exception_stacktrace` | Stack trace (when available)               |
| `$exception_source`     | `"backend"` — marks this as a server error |

This ensures errors appear in PostHog's native error tracking and can trigger alerts.