Use the data warehouse over PostHog MCP
The PostHog MCP server lets your AI coding agent run HogQL queries, manage data warehouse views, sync import sources, annotate tables and columns, and explore your schema directly from your code editor. Query events, create and materialize views, configure Postgres/Stripe/HubSpot imports, add semantic descriptions to your data, and work with warehouse tables – without switching to the PostHog app.
This works in any MCP client – Cursor, Codex, Claude Code, Windsurf, VS Code, and others.
Before you start
- Set up the Data Warehouse – link a source so there are tables to query.
- Connect the MCP server – install it in your AI tool and give it access to your project.
What you can do here
With MCP, your coding agent can:
- Run ad-hoc queries – "How many
purchase_completedevents happened this week?" to quickly check data - Explore your schema – "What tables do I have?" or "Show me the columns in
stripe_charges" to discover available data - Generate queries from questions – "Write a HogQL query to find the top users by event count" to get a query you can refine
- Query across sources – Join PostHog events with Stripe, HubSpot, or any linked warehouse table
- Manage views – Create, update, materialize, and delete saved views in your data warehouse programmatically
- Manage import sources – Create, configure, and sync data warehouse sources like Postgres, Stripe, and HubSpot
- Annotate tables and columns – Add semantic descriptions to views and warehouse tables so PostHog AI understands your data
SQL tools
The MCP server provides these tools for running SQL:
| Tool | Description |
|---|---|
execute-sql | Run a HogQL query and return results. Supports any valid HogQL syntax including joins, CTEs, subqueries, and window functions. |
read-data-schema | List the events and properties in your project, including person, session, and group properties. Useful before writing a query. |
View management tools
The MCP server also provides tools for managing data warehouse views:
| Tool | Description |
|---|---|
view-list | List all saved views in your project with their materialization status, sync frequency, column schema, and descriptions. |
view-get | Get full details of a specific view by ID, including its HogQL query, run history, and descriptions. |
view-create | Create a new view from a HogQL query with an optional description. Upserts by name if a view with the same name exists. |
view-update | Update a view's name, HogQL query, sync frequency, or description. |
view-delete | Delete a view (soft delete). |
view-materialize | Enable materialization for a view with a 24-hour refresh schedule. |
view-unmaterialize | Revert a materialized view back to a virtual query. |
view-run | Trigger a manual refresh of a materialized view. Set direction to upstream or downstream to include related views in dependency order. |
view-run-history | Get the last 5 materialization run statuses for a view. |
view-resume | Resume a suspended view whose materialization was paused after repeated failures. Set engine to clickhouse or trino to resume only that engine; omit it to resume all. |
Source management tools
These tools manage data warehouse import sources – external databases and services that sync data into PostHog:
| Tool | Description |
|---|---|
external-data-sources-list | List configured import sources with source health and a summary per table by default. |
external-data-sources-retrieve | Get one source by ID with source health and a summary per table by default. |
external-data-sources-create | Create a new source connection. Use external-data-sources-wizard first to discover available source types and required fields. |
external-data-sources-partial-update | Update a source's prefix, description, or connection credentials. |
external-data-sources-destroy | Delete a source and all its synced data. This can't be undone. |
external-data-sources-reload | Trigger a sync for all enabled tables in a source. |
external-data-sources-refresh-schemas | Fetch the latest table list from the remote database and add any new tables. |
external-data-sources-wizard | Get configuration metadata for all supported source types (required fields, OAuth flows, etc.). |
external-data-sources-revenue-config-update | Update enabled or include_invoiceless_charges for a source's Revenue Analytics configuration. Rebuilds managed revenue views without changing synced source tables. |
external-data-sources-draft-custom-manifest | Draft and validate a Custom REST source manifest from docs_url or docs_text. Creates no source and needs no credentials. Review and test the manifest before creating a source. |
Compact responses
The external-data-sources-list and external-data-sources-retrieve MCP tools default to compact: true. They return source health and one summary per table, without connection settings or full sync configuration. Pass include_schemas: false to omit tables entirely. Pass compact: false for source configuration with secrets redacted. Retrieve also returns full per-table sync configuration. Per-table column definitions are omitted from these MCP responses. Use external-data-schemas-retrieve for a table's columns.
The external-data-schemas-list MCP tool also defaults to compact: true. Each row contains id, name, source_id, should_sync, sync_type, status, last_synced_at, and latest_error. Pass compact: false for full sync configuration. Compact responses truncate long errors after 500 characters and add a truncation marker.
These are MCP defaults. The REST API defaults remain compact=false and, for source list/retrieve, include_schemas=true.
CDC management tools
These tools manage Postgres change data capture (CDC):
| Tool | Description |
|---|---|
external-data-sources-cdc-status-retrieve | Read live CDC health, including replication slot and publication existence, lag, and whether extraction is paused. Connects to the source database and changes nothing. |
external-data-sources-enable-cdc-create | Enable CDC on an existing source using its stored credentials. Checks prerequisites and provisions replication resources. Switch each table to sync_type=cdc separately. |
external-data-sources-disable-cdc-create | Disable CDC for the entire source and reset all its CDC tables. Destructive: requires confirmation. |
external-data-sources-resume-cdc-create | Resume paused extraction after fixing the cause, when the slot and publication still exist. Continues from the saved position without a new snapshot. |
external-data-sources-update-cdc-settings-create | Update cdc_auto_drop_slot, cdc_lag_warning_threshold_mb, or cdc_lag_critical_threshold_mb. Does not change management mode or replication resource names. |
The agent checks external-data-sources-cdc-status-retrieve first. If extraction is paused and the slot and publication exist, fix the cause and resume. If replication resources are missing, use repair instead of disable. Enabling CDC does not change any table's sync method or start a table sync.
Before disabling CDC, the agent must get your confirmation for the entire source. Disable cancels running CDC jobs, removes the extraction schedule, drops the replication slot (and the publication in PostHog-managed mode), deletes buffered changes, clears CDC settings, and soft-deletes CDC history tables. It clears the sync type and turns syncing off for every CDC table. Choose a new sync method and enable syncing for each table to resume. Re-enabling CDC requires a full resync and cannot recover changes missed while it was off.
Schema management tools
These tools manage individual table schemas within a data warehouse source:
| Tool | Description |
|---|---|
external-data-schemas-list | List table schemas across sources with compact health rows by default. Pass compact: false for full sync configuration. |
external-data-schemas-retrieve | Get a single table schema by ID with full sync details. |
external-data-schemas-partial-update | Update a table's sync type, frequency, incremental field, column masking, or enable/disable syncing. |
external-data-schemas-reload | Trigger a sync for a single table using its configured sync method. |
external-data-schemas-resync | Discard all synced data and re-import a table from scratch. |
external-data-schemas-cancel | Cancel a currently running sync job for a table. |
external-data-schemas-delete-data | Delete synced table data from PostHog but keep the schema entry for re-syncing. |
external-data-schemas-delete-history-table | Permanently delete a table's CDC history after it stops writing history and no sync is running. Keeps the live synced table and settings. Requires confirmation because past row versions cannot be recovered. |
external-data-schemas-destinations-update | Set a table's full destination_ids override, or pass null to inherit its source's destinations. Omitted destinations are detached. An empty list is rejected. |
Destination management tools
These tools manage warehouse destinations:
| Tool | Description |
|---|---|
external-data-destinations-update | Rename a destination or change non-target settings. Configuration merges with saved values. The integration and target cannot change. A successful update also resumes a paused destination. |
external-data-destinations-delete | Delete a destination and detach all linked sources and tables. Rows already written to the external system stay there, and running syncs finish. The PostHog warehouse destination cannot be deleted. |
Before changing a table's destinations, read its current override with external-data-schemas-destinations-retrieve. Do not update while a destination is paused: hidden links can be lost, and selecting a paused destination resumes it. New destinations receive future rows; resync the table to copy history.
Before deleting a destination, the agent must list the affected sources and tables and get your confirmation. If a source loses its last destination, it falls back to the PostHog warehouse.
Column annotation tools
These tools add semantic descriptions to your tables, views, and columns, helping PostHog AI understand your data:
| Tool | Description |
|---|---|
saved-query-column-annotations-create | Add or replace a description for a view (saved query) or one of its columns. Use for views (table_type = 'view' in information_schema). |
saved-query-column-annotations-list | List descriptions for views and their columns. Filter by ?saved_query_id=<uuid> to scope to one view. |
warehouse-column-annotations-create | Add or replace a description for an imported warehouse table or column. Use for physical tables (table_type = 'data_warehouse'). |
warehouse-column-annotations-list | List descriptions for warehouse tables and columns. Filter by ?table_id=<uuid> to scope to one table. |
warehouse-column-annotations-partial-update | Edit an existing warehouse table or column description by annotation ID. |
Note: Core PostHog tables (events, persons, groups, sessions) cannot be annotated – they have built-in descriptions.
Example prompts
Try these with your MCP-enabled agent:
Run a HogQL query to find the top 10 events by count today.What tables are available in my data warehouse?Write a query joining events with stripe_subscriptions to find revenue per user.Generate a HogQL query to calculate weekly active users by cohort.Show me 5 sample rows from the hubspot_contacts table.What properties are available on the purchase_completed event?
For schema discovery:
Query system.information_schema.tables to list all available tables with their descriptions.What columns does the events table have? Use system.information_schema.columns.Show me all relationships from the events table using system.information_schema.relationships.List all HogQL data types from system.information_schema.data_types.
For querying alerts:
Query system.alerts to find all enabled alerts in the project.Show me alerts that check hourly and their last check results.Write a HogQL query to find alerts that fired in the last week.
For schema discovery using system.information_schema:
Query system.information_schema.columns to find all columns in the events table with their types and descriptions.Use system.information_schema.relationships to show me how the events table joins to other tables.Search system.information_schema.tables for any table related to subscriptions.
For view management:
List all my saved views in the data warehouse.Create a view called 'daily_active_users' that counts distinct user_ids per day.Materialize my 'revenue_summary' view for faster queries.Trigger a refresh of my 'user_metrics' materialized view.Show me the run history for my 'sales_data' view.Set the description for my 'daily_active_users' view to explain what it calculates.Refresh my 'user_metrics' view and all its upstream dependencies.Run my 'sales_data' view and all downstream views that depend on it.
For source management:
List all my data warehouse sources.What tables are available in my Stripe source?Trigger a sync for my Postgres source.Show me the sync status for all my import schemas.Cancel the running sync on the hubspot_contacts table.
For column annotations:
Add a description to my 'revenue_summary' view explaining it calculates monthly recurring revenue.Describe the 'amount' column in my stripe_charges table as 'Transaction amount in cents'.List all column descriptions for my user_metrics view.What descriptions exist for my imported Stripe tables?
Install the MCP server
The recommended way to install is with the AI wizard:
The wizard supports Claude, Cursor, Windsurf, VS Code, and more. You can also configure it manually.
See the MCP server docs for full setup instructions.
Related
- Use the data warehouse in the web app for the SQL editor, source setup, and insights.
- Use the data warehouse over the API for the same operations from your own scripts.
- Self-driving reports in the web app to work through failing models and syncs.
- Manage data quality over MCP and SQL to create checks, start runs, and inspect results.
- Views and materialized views for what the view tools manage.
- Sources for what the source and schema tools configure.





