PostHog - AgentCat

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

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

Configuration

agentcat.track(server, null, {
  exporters: {
    posthog: {
      type: "posthog",
      apiKey: process.env.POSTHOG_API_KEY,
      host: "https://us.i.posthog.com"
    }
  }
})

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

agentcat.Track(s, "", &agentcat.Options{
    Exporters: map[string]any{
        "posthog": map[string]any{
            "type":   "posthog",
            "apiKey": os.Getenv("POSTHOG_API_KEY"),
            "host":   "https://us.i.posthog.com",
        },
    },
})

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:

Identified user ID — if the user was identified via the identify callback
Session ID — falls back to the AgentCat session ID
"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:

Regular capture event — the standard event with all properties above
$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.

​Overview

​Prerequisites

​Configuration

​Configuration Fields

​Field Mapping

​Event Names

​Distinct ID

​Event Properties

​Person Properties

​Error Events