# PostHog setup for PopMCP

One PostHog personal API key starting with phx_, plus the region your project lives in (us, eu or selfhosted) and a host URL if you run PostHog yourself.

- Auth: API credentials
- Setup time: 4 min
- API base URL: https://us.posthog.com/api
- Credentials screen: https://us.posthog.com/settings/user-api-keys
- Provider docs: https://posthog.com/docs/api

## Before you begin

- PostHog account on any plan, including the free tier
- Membership of the organization and project you want PopMCP to reach, because a personal API key never exceeds your own access
- Know whether your project is on US Cloud, EU Cloud or a self-hosted instance

## Get your credentials

### 1. Open the Personal API keys page

Sign in to PostHog, open Settings from the sidebar and pick Personal API keys under User. On EU Cloud replace `us.posthog.com` with `eu.posthog.com`.

Screen: https://us.posthog.com/settings/user-api-keys?preset=mcp_server

### 2. Create the key and give it a label

Click + Create a personal API Key and type a label such as `PopMCP`.

### 3. Choose the scopes

Pick All access, or switch to scoped access and tick read and write on `insight`, `dashboard`, `feature_flag`, `query`, `person`, `cohort`, `experiment`, `survey` and `annotation`. Add read on `user`, `organization` and `project`.

### 4. Limit the organization and project

In the same dialog set Organization & project access to the one organization and one project PopMCP should reach, then click Create key.

### 5. Copy the key value

The new key appears at the top of the list with its full value shown once. Copy it before you refresh the page.

### 6. Paste the key and region into PopMCP

Paste the value into Personal API Key and type `us`, `eu` or `selfhosted` into Region. Fill Self-hosted host only when the region is `selfhosted`.

## Fields PopMCP asks for

- Personal API Key (apiKey) [required]: PostHog → Settings → Personal API keys → + Create a personal API key (direct: https://us.posthog.com/settings/user-api-keys?preset=mcp_server; use the eu. host for EU). Pick "All access" (or read+write scopes for insight, dashboard, feature_flag, query, person, cohort, experiment, survey, annotation, plus user/organization/project read). The key is shown only once. Stored encrypted.
- Region (us, eu, or selfhosted) (region): Where your PostHog data lives: us (default, us.posthog.com), eu (eu.posthog.com), or selfhosted. A key only works against its own region. If you pick the wrong cloud region we'll auto-correct it on connect.
- Self-hosted host (only if region = selfhosted) (host): Your self-hosted PostHog URL. Leave blank for US/EU Cloud.

## Verify

PopMCP shows the connector as Connected with your PostHog project name and region, and a test call to the projects endpoint returns your project ID instead of a 401.

## Troubleshooting

### 401 Unauthorized on every call

Cause: The key was created on the other cloud. A us.posthog.com key never works against eu.posthog.com.

Fix: Set Region to match the host you signed in to, or create a fresh key on the correct cloud.

### 403 Forbidden on some tools only

Cause: The key uses scoped access and one specific scope is missing.

Fix: Open Settings, User, Personal API keys, click the key and add the missing read or write scope. Scopes are editable after creation.

### You refreshed the page before copying the key

Cause: PostHog displays the value once and stores only a hash.

Fix: Open the key from the list and choose Roll key, or delete it and create a new one.

### The key shows a Legacy tag

Cause: Keys created before February 2024 use the older PBKDF2 hashing.

Fix: Open the key and click Roll key to reissue it in the current format.

### 429 Too Many Requests

Cause: Private analytics endpoints allow 240 requests per minute and 1,200 per hour.

Fix: Space out bulk work and let PopMCP retry. The window resets on the hour.

### Self-hosted instance rejects the key

Cause: Region was left as us while the key belongs to your own deployment.

Fix: Set Region to selfhosted and put the full instance URL, including https://, in the host field.

---

Source: https://www.docs.popmcp.com/docs/integrations/posthog/