tracer-cloud--opensre/docs/posthog-mcp.mdx

---
title: "PostHog (MCP)"
description: "Connect PostHog's hosted MCP server so OpenSRE can query analytics, feature flags, error tracking, and HogQL during investigations"
---

OpenSRE connects to PostHog's hosted [Model Context Protocol (MCP)](https://posthog.com/docs/model-context-protocol) server, exposing PostHog's products — product analytics, feature flags, error tracking, experiments, surveys, and HogQL queries — as tools the agent can call while investigating an incident.

This is distinct from the PostHog bounce-rate integration, which is a narrow REST client used for watchdog alerting. Use the MCP integration when you want the agent to explore PostHog data directly.

## Tools

| Tool | What it does |
| --- | --- |
| `list_posthog_tools` | List the tools the connected PostHog MCP server exposes (compact, filterable) |
| `call_posthog_tool` | Call a named PostHog MCP tool (e.g. run a HogQL query, list feature flags, inspect an error) |

The agent typically calls `list_posthog_tools` first to discover what is available for your project, then `call_posthog_tool` with the chosen tool name and arguments.

The hosted PostHog MCP server exposes 240+ tools, each with a full input schema. Returning all of them at once is far larger than any model's context window, so `list_posthog_tools` returns a **compact, bounded listing** — tool names plus short descriptions, without schemas. To work with it efficiently:

- Pass `name_filter` (space- or comma-separated terms, e.g. `"events query sql"`) to narrow the list to relevant tools.
- Pass `include_schema=true` on a narrowed list to fetch the full input schema for the specific tool you intend to call.

To query events for a person or across a project, call `call_posthog_tool` with `tool_name="execute-sql"` and a HogQL query (e.g. `SELECT event, count() FROM events WHERE ... GROUP BY event`). There is no `search_events` tool.

## Prerequisites

- A PostHog account (US or EU — the hosted server routes you automatically)
- A PostHog **personal API key** created with the **MCP Server** preset. See [PostHog's personal API keys docs](https://posthog.com/docs/api/personal-api-keys).

<Info>
OpenSRE defaults to **read-only** access (`x-posthog-read-only: true`) so investigations cannot mutate your PostHog project. Set `POSTHOG_MCP_READ_ONLY=false` only if you explicitly want the agent to perform writes.
</Info>

## Setup

### Option 1: Interactive CLI

```bash
opensre integrations setup
```

Select **PostHog (MCP)** when prompted, then paste your personal API key. The setup uses the hosted Streamable HTTP transport; keep the default URL unless you have a reason to change it. To run a local server instead, set `POSTHOG_MCP_MODE=stdio` via environment variables (see below).

To skip the menu, name the service directly. The canonical name is `posthog_mcp`, and `posthog` is accepted as a convenience alias:

```bash
opensre integrations setup posthog        # alias for posthog_mcp
opensre integrations verify posthog
```

### Option 2: Environment variables

Add to your `.env`:

```bash
POSTHOG_MCP_MODE=streamable-http
POSTHOG_MCP_URL=https://mcp.posthog.com/mcp
POSTHOG_MCP_AUTH_TOKEN=phx_your_personal_api_key
POSTHOG_MCP_PROJECT_ID=12345          # optional, scope to one project
POSTHOG_MCP_ORGANIZATION_ID=          # optional, scope to one organization
POSTHOG_MCP_FEATURES=                 # optional, comma-separated feature filter
POSTHOG_MCP_READ_ONLY=true            # optional, default true
```

| Variable | Default | Description |
| --- | --- | --- |
| `POSTHOG_MCP_AUTH_TOKEN` | — | **Required** (hosted). Personal API key with the `MCP Server` preset |
| `POSTHOG_MCP_URL` | `https://mcp.posthog.com/mcp` | MCP server URL (use `https://mcp-eu.posthog.com/mcp` to pin EU) |
| `POSTHOG_MCP_MODE` | `streamable-http` | Transport: `streamable-http`, `sse`, or `stdio` |
| `POSTHOG_MCP_PROJECT_ID` | — | Scope tools to a specific PostHog project |
| `POSTHOG_MCP_ORGANIZATION_ID` | — | Scope tools to a specific organization |
| `POSTHOG_MCP_FEATURES` | — | Comma-separated feature filter (e.g. `flags,error-tracking`) |
| `POSTHOG_MCP_READ_ONLY` | `true` | Send the read-only header so the agent cannot mutate PostHog |
| `POSTHOG_MCP_COMMAND` | — | Command to launch a local MCP server (`stdio` mode only) |
| `POSTHOG_MCP_ARGS` | — | Arguments for the local MCP command (`stdio` mode only) |

To run a local PostHog MCP server instead of the hosted endpoint, use `stdio` mode:

```bash
POSTHOG_MCP_MODE=stdio
POSTHOG_MCP_COMMAND=npx
POSTHOG_MCP_ARGS=-y @posthog/mcp-server@latest
POSTHOG_MCP_AUTH_TOKEN=phx_your_personal_api_key
```

### Option 3: Persistent store

```json
{
  "version": 1,
  "integrations": [
    {
      "id": "posthog-mcp-prod",
      "service": "posthog_mcp",
      "status": "active",
      "credentials": {
        "url": "https://mcp.posthog.com/mcp",
        "mode": "streamable-http",
        "auth_token": "phx_your_personal_api_key",
        "project_id": "12345",
        "read_only": true
      }
    }
  ]
}
```

## Verify

```bash
opensre integrations verify posthog_mcp
```

A successful check connects to the MCP server and reports how many tools it discovered. If it fails, the most common cause is a missing or invalid personal API key — confirm the key was created with the `MCP Server` preset and that outbound HTTPS to `mcp.posthog.com` is allowed.