Merge Unified's PostHog integration Merge Agent Handler's PostHog MCP server

Connect your AI Agents to PostHog in minutes

Merge lets you securely connect your agents to PostHog and thousands of tools instantly

Start building for free

Read docs

PostHog

Learn more about Merge Agent Handler

Available tools

list_actions

List actions with pagination. Use offset from page_info for next page.

get_action

Get an action by ID. Use list_actions to find valid IDs.

create_action

Create a new action. Define matching criteria using steps (event name, URL, CSS selector, etc.).

update_action

Update an action's name, description, or matching steps. Use list_actions to find valid IDs.

delete_action

Soft-delete an action by marking it as deleted. Use list_actions to find valid IDs.

list_activity_log

List activity log entries showing recent changes to the project (data management, events, properties, surveys, actions).

list_annotations

List annotations with pagination. Use offset from page_info for next page.

get_annotation

Get an annotation by ID. Use list_annotations to find valid IDs.

create_annotation

Create an annotation at a specific date. Useful for marking deployments, incidents, or notable events on charts.

update_annotation

Update an annotation's content, date, or scope. Use list_annotations to find valid IDs.

delete_annotation

Soft-delete an annotation by marking it as deleted. Use list_annotations to find valid IDs.

list_batch_exports

List batch export configurations with pagination. Use offset from page_info for next page.

get_batch_export

Get a batch export configuration by ID. Use listbatchexports to find valid IDs.

create_batch_export

Create a batch export to regularly export data to a destination (S3, BigQuery, Snowflake, etc.).

delete_batch_export

Delete a batch export configuration permanently. Use listbatchexports to find valid IDs.

list_cohorts

List cohorts with pagination. Use offset from page_info for next page.

get_cohort

Get a cohort by ID. Use list_cohorts to find valid IDs.

create_cohort

Create a new cohort. Use groups to define membership criteria with property filters.

update_cohort

Update a cohort's name, description, or filter groups. Use list_cohorts to find valid IDs.

delete_cohort

Soft-delete a cohort by marking it as deleted. Use list_cohorts to find valid IDs.

list_dashboards

List dashboards with pagination. Use offset from page_info for next page.

get_dashboard

Get a dashboard by ID with its tiles. Use list_dashboards to find valid IDs.

create_dashboard

Create a new dashboard. Add insights to it later using update_insight.

update_dashboard

Update a dashboard's name, description, or pinned status. Use list_dashboards to find valid IDs.

delete_dashboard

Soft-delete a dashboard by marking it as deleted. Use list_dashboards to find valid IDs.

list_event_definitions

List event definitions with pagination. Shows event names, volumes, and metadata tracked in the project.

get_event_definition

Get an event definition by ID. Use listeventdefinitions to find valid IDs.

update_event_definition

Update an event definition's description or tags. Use listeventdefinitions to find valid IDs.

list_experiments

List experiments with pagination. Use offset from page_info for next page.

get_experiment

Get an experiment by ID. Use list_experiments to find valid IDs.

create_experiment

Create a new experiment. Requires name and featureflagkey. The feature flag will be auto-created if it doesn't exist.

update_experiment

Update an experiment's name, description, parameters, or filters. Use list_experiments to find valid IDs.

delete_experiment

Soft-delete an experiment by marking it as deleted. Use list_experiments to find valid IDs.

list_feature_flags

List feature flags with pagination. Use offset from page_info for next page.

get_feature_flag

Get a feature flag by ID. Use listfeatureflags to find valid IDs.

create_feature_flag

Create a new feature flag. Requires a unique key. Use filters to set release conditions.

update_feature_flag

Update a feature flag's key, name, active status, or filters. Use listfeatureflags to find valid IDs.

delete_feature_flag

Soft-delete a feature flag by marking it as deleted. Use listfeatureflags to find valid IDs.

list_insights

List saved insights with pagination. Use offset from page_info for next page.

get_insight

Get an insight by ID. Use list_insights to find valid IDs.

create_insight

Create a new insight. Use filters for legacy insights or query for HogQL-based insights.

update_insight

Update an insight's name, description, filters, or query. Use list_insights to find valid IDs.

delete_insight

Soft-delete an insight by marking it as deleted. Use list_insights to find valid IDs.

list_persons

List persons with pagination. Optionally search by name/distinct ID or filter by properties.

get_person

Get a person by ID with their properties and distinct IDs. Use list_persons to find valid IDs.

delete_person

Delete a person and their data permanently. Use list_persons to find valid IDs.

list_projects

List all projects in the organization. Use offset from page_info for next page.

get_project

Get a specific project by ID. Use list_projects to find valid project IDs.

update_project

Update a project's name or timezone. Use list_projects to find valid project IDs.

list_property_definitions

List property definitions with pagination. Optionally filter by type (event, person, group).

get_property_definition

Get a property definition by ID. Use listpropertydefinitions to find valid IDs.

update_property_definition

Update a property definition's description, tags, or type. Use listpropertydefinitions to find valid IDs.

run_query

Execute a HogQL query. Pass a query object like {'kind': 'HogQLQuery', 'query': 'SELECT count() FROM events'}. Max 50k rows.

list_session_recordings

List session recordings with pagination. Use offset from page_info for next page.

get_session_recording

Get a session recording by ID. Use listsessionrecordings to find valid IDs.

delete_session_recording

Delete a session recording permanently. Use listsessionrecordings to find valid IDs.

list_surveys

List surveys with pagination. Use offset from page_info for next page.

get_survey

Get a survey by ID. Use list_surveys to find valid IDs.

create_survey

Create a new survey. Define questions with type (open, multiple_choice, rating, etc.) and targeting filters.

update_survey

Update a survey's name, description, questions, or schedule. Use list_surveys to find valid IDs.

delete_survey

Delete a survey permanently. Use list_surveys to find valid IDs.

get_current_user

Get the currently authenticated user's profile including email, name, organization, and team details.

validate_credential

Validate PostHog credentials by fetching the current user profile. Returns success status and authenticated user email.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's PostHog MCP server

What is a PostHog MCP?

A PostHog MCP is a server that gives AI agents direct access to your PostHog instance through callable tools. Your agents can invoke these tools to query event data, manage feature flags, run HogQL queries, retrieve experiment results, and more.

PostHog offers an official MCP server, but you can also connect to a fully-managed, third-party hosted PostHog MCP server via a platform like like Merge Agent Handler.

How can I use the PostHog MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Feature flag automation: When a new feature ships, an agent can create or update a feature flag in PostHog, set rollout conditions based on cohort definitions, and confirm the flag is active, without anyone logging into the PostHog dashboard

Experiment result summarization: An agent can pull active experiment data from PostHog, calculate conversion rates across variants, and post a formatted results summary to a Slack channel or Notion doc for the product team to review

Anomaly detection and alerting: An agent can run a scheduled HogQL query against event data, compare results to a baseline, and trigger an alert when a key metric drops below a defined threshold

Cohort-based reporting: An agent can retrieve cohort definitions from PostHog, cross-reference them with CRM data, and generate a breakdown of product usage by customer segment for a weekly stakeholder digest

What are popular tools for PostHog's MCP server?

Here are some of the most commonly used tools:

<code class="blog_inline-code">execute_hogql_query</code> runs a HogQL query directly against PostHog event data. Use this when you need custom analytics results that standard endpoints don't expose
<code class="blog_inline-code">list_feature_flags</code> returns all feature flags for a project along with their current rollout state. This is helpful for agents that audit flag status or coordinate releases across teams
<code class="blog_inline-code">create_feature_flag</code> creates a new feature flag in PostHog with defined rollout conditions. This can be useful for agents that provision flags automatically as part of a deployment workflow
<code class="blog_inline-code">list_experiments</code> returns active and completed experiments with their variant configurations. Your agents can leverage this to monitor test status or compile results for reporting
<code class="blog_inline-code">list_cohorts</code> fetches cohort definitions from PostHog. Adopt this when your agents need to segment users before running a targeted analysis or cross-referencing with external data
<code class="blog_inline-code">list_insights</code> retrieves saved insight configurations and their underlying queries. This can be useful for agents that need to reference existing analytics definitions before building a new report‍

What makes Merge Agent Handler's PostHog MCP server better than alternative PostHog MCP servers?

There are a few compelling reasons to use Merge Agent Handler's PostHog MCP server rather than building or maintaining your own:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For PostHog, this means person-level data, session recordings, and user properties can be masked even when the agent has broad query access

Managed authentication and credentials: Merge stores and refreshes PostHog credentials on your behalf. You never expose API keys to an agent or build logic to handle token expiry yourself

Real-time observability and audit trail: Every tool call against PostHog is logged with timestamp, tool name, inputs, and response metadata. Product and engineering teams get a full record of what the agent queried or modified without any custom instrumentation

Tool Packs and controlled access: Tool Packs let you define exactly which PostHog tools an agent can call, and combine them with tools from other connectors in a single scoped MCP endpoint. A feature release agent gets flag tools. An analytics agent gets query and insight tools. Neither gets access beyond its defined scope

How can I start using Merge Agent Handler's PostHog MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs.

2. Create a new Tool Pack (a collection of connectors and tools that maps to a use case) and enable the PostHog connector. Choose which tools to include. Read and query tools cover most analytics and reporting workflows, while write tools are available if your agent needs to create feature flags, experiments, or cohorts.

3. Add a Registered User to the Tool Pack. Merge generates a unique MCP URL tied to this user, defining the identity context your agent operates under.

4. From the Registered User detail page, complete the PostHog credential flow. Merge takes over credential storage and refresh from that point forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key under Settings. You will need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your PostHog tools are available through that endpoint immediately.