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

# PostHog

> Connect PostHog to CloudThinker for product analytics, error triage, HogQL queries, and approval-gated feature flag, insight, dashboard, and survey changes

Connect your PostHog project to let [Alex](/guide/agents/alex) (Cloud Engineer) read what your product is doing: feature flags, insights, dashboards, surveys, tracked errors, and your event schema. Alex ranks error issues, summarizes event volume, and answers questions with bounded HogQL queries.

PostHog authenticates with a **personal API key** through its hosted MCP server. The key's own scopes decide what the agent can reach.

## Prerequisites

* A **PostHog account** with access to the project you want CloudThinker to read.
* Permission to create a **personal API key**. PostHog allows up to 10 personal API keys per user.
* A project that is **receiving events**. Analytics and error questions need ingested data; a project with no events returns an empty answer, not a broken connection.

<Info>
  PostHog does not charge for the MCP connection or for its tool calls. A few AI-powered tools bill as PostHog AI spend and need AI data processing enabled in your project.
</Info>

## Setup

<Steps>
  <Step title="Open the personal API key page">
    In PostHog, go to **Settings → Personal API keys**, or open [the MCP preset link](https://app.posthog.com/settings/user-api-keys?preset=mcp_server) directly.
  </Step>

  <Step title="Create the key">
    Click **+ Create a personal API Key** and give it a label such as `CloudThinker`.
  </Step>

  <Step title="Choose the scopes">
    Select the **MCP Server** preset. PostHog describes it as scoping access to a specific project. Without the preset, select only the scopes you need; PostHog recommends selecting only the scopes required for what you really use.
  </Step>

  <Step title="Copy the key value">
    Copy the value immediately. PostHog shows a personal API key once and never displays it again after you refresh the page. Keys begin with `phx_`.
  </Step>

  <Step title="Connect in CloudThinker">
    Go to **Connections → PostHog**, paste the key into **POSTHOG\_PERSONAL\_API\_KEY**, select your **POSTHOG\_REGION**, then click **Connect**.
  </Step>
</Steps>

## Connection details

| Field                           | Description                                                      |
| ------------------------------- | ---------------------------------------------------------------- |
| **POSTHOG\_PERSONAL\_API\_KEY** | The personal API key you created, starting with `phx_`           |
| **POSTHOG\_REGION**             | **US** or **EU**, matching the PostHog cloud that issued the key |

PostHog Cloud US and PostHog Cloud EU are separate instances that serve different hosts, and PostHog directs API requests to the host where the instance lives. Select **US** if you sign in at `us.posthog.com` and **EU** if you sign in at `eu.posthog.com`.

<Tip>
  One connection signs in as one account with one active project. To work across two projects, create a second PostHog connection with its own key and give it a distinct name.
</Tip>

## Required permissions

CloudThinker cannot reach anything the key's scopes exclude. A scope is a resource paired with read or write access, for example `insight:read`.

| Area                           | Why the agent needs it                                           |
| ------------------------------ | ---------------------------------------------------------------- |
| **Projects and organizations** | Name the account, list projects, and confirm which one is active |
| **Feature flags**              | Report which flags exist, their rollout, and their status        |
| **Insights and dashboards**    | Read saved insights and the dashboards that hold them            |
| **Surveys**                    | Report which surveys are running and what they ask               |
| **Error tracking**             | Rank issues, group them by status, and open issue details        |
| **Query**                      | Run HogQL and read the event schema                              |

<Warning>
  PostHog hides what the key's scopes exclude rather than announcing it: the capability is absent from the key's surface, and a call that reaches one anyway is refused for a missing scope. That is easy to mistake for a project with no flags or no errors. If the agent reports nothing where you expect data, check the key's scopes first.
</Warning>

## Agent capabilities

Once connected, Alex can:

| Capability                 | Description                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace discovery**    | Name the organization and active project, then list feature flags, insights, dashboards, surveys, and tracked errors                     |
| **Error triage**           | Rank error issues by occurrence, group them by status, and open the details of the worst offenders                                       |
| **Usage trends**           | Summarize event volume over a period and name the top events                                                                             |
| **Event schema**           | Report which events and properties your project actually records                                                                         |
| **HogQL queries**          | Answer a question with a bounded query that carries its own row limit                                                                    |
| **Approval-gated changes** | Create or update a feature flag, insight, dashboard, experiment, survey, annotation, cohort, or alert after you approve the exact inputs |

### Verify the connection

```text theme={null}
@alex #report summarize my PostHog setup: organization, active project, and whether feature flags and insights exist
```

### Example prompts

```text theme={null}
@alex which errors are hurting users most right now
@alex how has signup event volume moved over the last 7 days
@alex what feature flags are rolled out to more than half of users
```

## Every call asks for approval

PostHog's MCP server has hundreds of tools, so it serves them behind a single command tool that runs the rest. That one tool can reach every change PostHog allows, so CloudThinker classifies it as a write and never lets it run unattended.

The practical effect: PostHog calls pause for your decision, including ones that only read. In **Manual** mode the call waits for your approval. In **Auto** mode the classifier decides each call and records the outcome. See [Auto Mode](/guide/auto-mode) and [Approvals](/guide/approval).

<Warning>
  Changing the active project or organization is a write. Approve it only when you intend the rest of the conversation to look at the other project.
</Warning>

## Troubleshooting

<Accordion title="Every call fails with an authentication error">
  The key belongs to the other PostHog cloud, or it was revoked. Confirm **POSTHOG\_REGION** matches the host you sign in to, then create a fresh key on that instance and reconnect.
</Accordion>

<Accordion title="The agent says a capability is unavailable, or reports an empty project">
  The key is missing that scope, so PostHog does not offer the capability to it. Open the key in PostHog and confirm it carries the areas you expect, or create a new key with the **MCP Server** preset. Adding the scope needs a reconnect; the other areas keep working meanwhile.
</Accordion>

<Accordion title="The agent sees the wrong project">
  One connection has one active project. Ask the agent to switch projects and approve the change, or add a second PostHog connection scoped to the other project.
</Accordion>

<Accordion title="Calls start failing after heavy use">
  Calls run against PostHog's API and are subject to its rate limits, which are shared across all users and keys in your organization. There is no separate limit for this connection. Wait for the window to reset, then narrow the question so the agent reads less.
</Accordion>

<Accordion title="I lost the key value">
  PostHog shows a personal API key once. Create a new one and update the connection; you cannot recover the original.
</Accordion>

<Accordion title="A read paused for approval">
  That is expected. PostHog's whole tool surface arrives as one command tool that CloudThinker treats as a write, so reads pause too.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Scope the key tightly** — PostHog states a personal API key can enable full access to your account, like logging in with your email and password. Use the **MCP Server** preset, and keep the key dedicated to CloudThinker so you can revoke it alone.
- **Your project API token stays out of chat** — the agent reads project details through a path that drops the token, so it is never quoted back into a conversation.
- **Review before you approve** — PostHog advises reviewing MCP tool calls before running them. The approval prompt shows the exact inputs first.

## Related

<CardGroup cols={2}>
  <Card title="Alex Agent" icon="cloud" href="/guide/agents/alex">
    Cloud and observability investigation agent
  </Card>

  <Card title="Approvals" icon="shield-check" href="/guide/approval">
    How CloudThinker gates a write behind your confirmation
  </Card>
</CardGroup>