Gentic Analytics — Documentation

Give your AI agent read access to your PostHog project. Analyze sessions, scroll depth, button clicks, and saved insights — or drop into raw HogQL when you need something custom. All through the Model Context Protocol, connected to your own PostHog workspace.

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Analytics, you need an API key to authenticate your requests.

Go to gentic.co/analytics and create an account.
Create an organization from your dashboard. API keys and billing are scoped to the organization.
Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/analytics. For Claude Code:

claude mcp add gentic-analytics \
  --transport http \
  https://mcp.gentic.co/analytics \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Analytics agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/analytics/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/analytics/gentic-analytics.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. Connecting Your PostHog Project

Gentic Analytics reads analytics from your own PostHog project. Connect it once from the dashboard:

Open the Gentic dashboard and go to the Integrations section.
In PostHog, go to Settings → Personal API Keys and create a read-only key with at minimum query:read, project:read, and insight:read scopes.
Paste the key, your Project ID, and your Host (https://us.i.posthog.com or https://eu.i.posthog.com) into the PostHog connect dialog.
Gentic will validate the key against PostHog and store it encrypted at rest. The key is scoped to your organization.

5. When to Apply

User is debugging a funnel, a landing page, or a campaign and wants to know what's actually happening on the site.
User wants to compare a recent period against a previous one — traffic, engagement, scroll, clicks.
User asks about a specific entry URL or pathname.
User wants to pull a saved PostHog insight or run a custom HogQL query against events / sessions / persons.

6. Workflow

1. Start with the entry pathname
If the user mentions a page, ad, or campaign, resolve it to a PostHog entry pathname (e.g. `/pages/qure-microinfusion-offer`). Almost every tool keys off this. If the user is vague, ask.
2. Use posthog_analyze_sessions first
For any 'how is this page doing' question, start with `posthog_analyze_sessions`. It gives you recent-vs-previous period volume, engagement, quality, performance, and traffic-source breakdowns in one call. This is almost always the right first move.
3. Drill down with scroll depth and button clicks
If sessions look thin or engagement drops, call `posthog_scroll_depth_analysis` to see where readers are dropping off, and `posthog_analyze_button_clicks` to see which CTAs are pulling. Run both in parallel — they're independent.
4. Pull saved insights
Use `posthog_get_insights` (free) to surface saved funnels and dashboards the team has already built. Prefer existing insights over ad-hoc HogQL when the answer already lives in one.
5. Drop into HogQL for custom questions
When the pre-built tools don't cover it — cross-event joins, custom aggregations, specific user segments — use `posthog_execute_hogql_query`. HogQL is PostHog's SQL dialect; syntax docs at https://posthog.com/docs/hogql. Keep queries bounded (LIMIT clauses) and read-only (this integration is scoped read-only anyway).

7. Tool Reference

9 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

northbeam_create_export

50¢ / call

Kick off a Northbeam Data Export job. Returns an export_id immediately; use northbeam_get_export to poll for the CSV download URL once ready (typically 30s-3min). Call northbeam_list_metrics / list_attribution_models / list_breakdowns first to discover valid IDs. Costs $0.50.

Parameter	Type	Description
`metrics` required	`string[]`	Metric IDs (from northbeam_list_metrics), e.g. ['attributed_revenue', 'spend', 'roas'].
`attribution_models` required	`string[]`	Attribution model IDs (from northbeam_list_attribution_models), e.g. ['northbeam_custom']. Pass multiple to compare models in one report.
`accounting_modes`	`string[]`	Accounting modes: 'cash' (revenue when transaction occurs) or 'accrual' (revenue when touchpoint occurs). Defaults to ['accrual'].
`attribution_windows`	`string[]`	Attribution windows in days, e.g. ['7'] or ['1','7','30']. Defaults to ['7'].
`level`	`string`	Granularity of the export. Defaults to Northbeam's API default. enum: ad, adset, campaign, account
`time_granularity`	`string`	Row time granularity. Defaults to DAILY. enum: DAILY, WEEKLY, MONTHLY
`period_type`	`string`	Reporting period. Defaults to YESTERDAY. enum: YESTERDAY, CUSTOM_RANGE
`period_starting_at`	`string`	ISO date (YYYY-MM-DD). Required when period_type='CUSTOM_RANGE'.
`period_ending_at`	`string`	ISO date (YYYY-MM-DD). Required when period_type='CUSTOM_RANGE'.
`breakdowns`	`object[]`	Optional breakdown groupings. Each item is {key, values?}. Discover valid keys via northbeam_list_breakdowns. Omit values to include all.
`remove_zero_spend`	`boolean`	Filter out zero-spend rows. Defaults to true.
`aggregate_data`	`boolean`	Aggregate across the period instead of returning per-period rows. Defaults to false.
`include_ids`	`boolean`	Include platform-side IDs in output rows. Defaults to true.
`include_kind_and_platform`	`boolean`	Include kind/platform columns. Defaults to false.
`export_aggregation`	`string`	BREAKDOWN: per-row data. TOTAL: a single aggregate row. Defaults to BREAKDOWN. enum: BREAKDOWN, TOTAL

northbeam_list_attribution_models

Free

List the attribution models available in your Northbeam account (e.g. northbeam_custom, last_touch, first_touch, linear). Use this before calling northbeam_create_export to pick a valid model. Free.

This tool takes no parameters.

northbeam_list_breakdowns

Free

List the breakdown dimensions available in your Northbeam account (e.g. platform, category, targeting, influencer_by_platform). Use this before calling northbeam_create_export to pick valid breakdown groupings. Free.

This tool takes no parameters.

northbeam_list_metrics

Free

List the metrics available in your Northbeam account (e.g. attributed_revenue, cac, roas, spend, transactions). Use this before calling northbeam_create_export to pick valid metric IDs. Free.

Parameter	Type	Description
`platform`	`string`	Optional platform filter (e.g. 'meta', 'google', 'tiktok'). If omitted, returns metrics for all connected platforms.

posthog_analyze_button_clicks

8¢ / call

Analyze button click breakdown for sessions that entered through a specific page. Returns click counts, unique users, and share-of-clicks per button text. Useful for identifying which CTAs on a landing page are driving engagement.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'
`days_back`	`number`	Days to look back. Defaults to 7. 1 – 180

entry_pathname

required

string

The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'

days_back

number

Days to look back. Defaults to 7.

1 – 180

posthog_analyze_sessions

10¢ / call

Analyze session metrics for a specific entry page, comparing recent vs previous period. Returns volume, engagement, quality, performance, and traffic-source breakdowns. Useful for spotting regressions or lifts after page/campaign changes.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'
`days_back`	`number`	Total days to analyze (2-180). Split in half for comparison (e.g. 14 = last 7 vs previous 7). Defaults to 14. 2 – 180

entry_pathname

required

string

The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'

days_back

number

Total days to analyze (2-180). Split in half for comparison (e.g. 14 = last 7 vs previous 7). Defaults to 14.

2 – 180

posthog_execute_hogql_query

10¢ / call

Execute a raw HogQL query against PostHog. Use for custom analytics queries on events, sessions, persons — e.g. "SELECT properties.$current_url, count() FROM events WHERE event = '$pageview' GROUP BY properties.$current_url LIMIT 50". Returns query results as JSON.

Parameter	Type	Description
`hogql_query` required	`string`	The HogQL query to execute. HogQL is PostHog's SQL dialect — see https://posthog.com/docs/hogql

posthog_get_insights

Free

List saved PostHog insights (dashboards, funnels, trends) for the connected project. Supports pagination. Free.

Parameter Type Description

Parameter	Type	Description
`limit`	`number`	Max insights to return (1-100). Defaults to 100. 1 – 100
`offset`	`number`	Number of insights to skip for pagination. Defaults to 0. min 0

limit

number

Max insights to return (1-100). Defaults to 100.

1 – 100

offset

number

Number of insights to skip for pagination. Defaults to 0.

min 0

posthog_scroll_depth_analysis

8¢ / call

Analyze scroll depth for sessions entering through a specific pathname. Returns avg/max scroll percent, time on page, and reader distribution (deep/medium/light). Useful for diagnosing which sections of a landing page users actually reach.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'
`days_back`	`number`	Days to look back. Defaults to 7. 1 – 180

entry_pathname

required

string

The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'

days_back

number

Days to look back. Defaults to 7.

1 – 180

8. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

Tool	Cost
northbeam_create_export	50¢ / call
northbeam_list_attribution_models	Free
northbeam_list_breakdowns	Free
northbeam_list_metrics	Free
posthog_analyze_button_clicks	8¢ / call
posthog_analyze_sessions	10¢ / call
posthog_execute_hogql_query	10¢ / call
posthog_get_insights	Free
posthog_scroll_depth_analysis	8¢ / call

9. Notes

All tools are organization-scoped and talk to the PostHog project connected in the Gentic dashboard.
The stored PostHog key is read-only — write/mutate queries will fail at the PostHog side, not Gentic's side.
Scroll depth, button clicks, and session analysis all default to a 7-14 day window. Pass `days_back` to widen it up to 180 days.

Gentic Analytics — Documentation

1. Getting Started

Sign Up & Get Your API Key

2. Connecting to the MCP Server

3. Agent Skill

4. Connecting Your PostHog Project

5. When to Apply

6. Workflow

1. Start with the entry pathname

2. Use posthog_analyze_sessions first

3. Drill down with scroll depth and button clicks

4. Pull saved insights

5. Drop into HogQL for custom questions

7. Tool Reference

northbeam_create_export

northbeam_list_attribution_models

northbeam_list_breakdowns

northbeam_list_metrics

posthog_analyze_button_clicks

posthog_analyze_sessions

posthog_execute_hogql_query

posthog_get_insights

posthog_scroll_depth_analysis

8. Pricing

9. Notes