By Ira Bodnar, Ryze AI · Updated · Connector tested November 13, 2026
Quick answer
The main way to connect Claude Code to PostHog is the Ryze AI connector. Save a PostHog personal API key and its host in the PostHog card in Ryze AI, run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp in your shell, then open Claude Code, run /mcp, select ryze and sign in. Start a new session and ask a question about your PostHog project.
- In PostHog create a personal API key with the Query and Insight scopes
- In Ryze AI open Integrations, click Connect on PostHog, paste the key, enter the host and pick the project
- In your terminal run the claude mcp add command, then /mcp in Claude Code to sign in
- Allow the workspace on the Ryze AI page and ask your first question
Claude Code to PostHog at a glance
| Question | Answer |
|---|---|
| Main way to connect | The Ryze AI connector, a hosted MCP server added with one claude mcp add command |
| Server address | https://connector.get-ryze.ai/mcp |
| Sign-in to Ryze AI | OAuth in the browser from /mcp or claude mcp login ryze. A Ryze AI API key with --header suits scripts |
| What PostHog needs | A phx_ personal API key with read access to the project, the Query and Insight scopes, and your host |
| PostHog tools | 3: posthog__read, posthog__write and posthog__delete |
| Can Claude Code change PostHog | Only when the key carries write scopes. With read scopes alone, PostHog rejects every change |
| Projects | One PostHog project per Ryze AI workspace |
| Claude Code plan | Pro, Max, Ultra, Team, Enterprise or Console. The free claude.ai plan has no Claude Code |
| Ryze AI price | Paid Ads is $89 per month with a 7-day free trial. Adding the connector is free; the PostHog tools need a plan or trial |
| PostHog's own route | Its free hosted MCP server at https://mcp.posthog.com/mcp, added with claude mcp add or the PostHog plugin |
| Last checked | Connector tested November 13, 2026, sources read November 14, 2026. No PostHog call and no Claude Code step was run |
Before you start
- A Claude Code account. Anthropic says Claude Code requires a Pro, Max, Ultra, Team, Enterprise or Console account; the free claude.ai plan does not include it. It can also run through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. Anthropic's MCP page names no extra plan for remote MCP servers.
- A PostHog personal API key. It starts with phx_ and needs read access to the project, including the Query and Insight scopes. Add write scopes only if Claude Code should change objects. PostHog shows the key value once, when you create it, and each user can hold up to 10 keys. You also need the host of your instance: https://us.posthog.com, https://eu.posthog.com or a self-hosted URL.
- A Ryze AI workspace on a plan or free trial. Paid Ads is $89 per month with a 7-day free trial; SEO Starter is $129 per month with a 3-day free trial; Agency is $279 per month. Connecting the connector is free, but the PostHog tools need an active plan or trial.
How to connect Claude Code to PostHog
Two steps happen in PostHog and Ryze AI, four in Claude Code. The connector URL is the same for every user.
Create a personal API key in PostHog
In PostHog go to Settings, Personal API keys and click Create key. Grant read access to the project with the Query and Insight scopes, add write scopes only for objects Claude Code should change, and copy the phx_ key.
Connect PostHog in Ryze AI
Create a Ryze AI account or sign in, open Integrations, click Connect on the PostHog card, paste the key, enter the Host (US Cloud, EU Cloud or your self-hosted URL) and click Continue. Pick the Project and click Save.
Register the connector in Claude Code
In your terminal, not inside a claude session, run: claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp. The server is stored with local scope by default; add --scope user to make it available in all your projects. Until you sign in, claude mcp list shows it as Needs authentication.
Sign in from Claude Code
Inside Claude Code run /mcp, select ryze and choose Authenticate, or run claude mcp login ryze in the shell. Add --no-browser to print the sign-in URL instead of opening a browser, for example over SSH; that paste step needs an interactive terminal, so connect with ssh -t.
Allow the workspace
On the Ryze AI page, sign in if asked, choose the workspace that holds PostHog and click Allow connection. Check the result with claude mcp get ryze.
Start a new session and ask your first question
Tool search is on by default in Claude Code, so MCP tools load on demand. Ask: List my saved PostHog insights, then run a HogQL query for daily pageview counts over the last 14 days with a LIMIT of 100.
The Ryze AI PostHog guide covers the PostHog side of the connection, and the Claude Code MCP docs cover the client commands.
Sources: Claude Code MCP documentation, Claude Code MCP quickstart, Ryze AI PostHog guide. Checked November 14, 2026.
OAuth, API key and claude.ai connectors
Claude Code accepts the Ryze AI connector three ways. Pick the one that matches where the session runs.
CLI with OAuth (a personal machine)
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope userThis is the flow in the steps above. The default local scope keeps the server to the current project, --scope user loads it in all your projects, and --scope project writes a .mcp.json file the team can share. Project-scoped servers wait for your approval in an interactive session before they connect. The scope is fixed when you add the server: to move it, remove the entry and add it again with the new flag.
CLI with a Ryze AI API key
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --header "Authorization: Bearer rk_live_..."This key belongs to Ryze AI and is separate from the PostHog phx_ key. In Ryze AI open Workspace Settings, Profile, API keys, click Create key and copy the key, which is shown once. The Ryze AI help center says it works on the /mcp endpoint only, not on /sse. claude mcp add stores the entry without checking the key. If Claude Code gets a rejected Authorization header it reports the connection as failed and does not fall back to OAuth, so replace a bad key.
claude.ai connectors inside Claude Code
Add Ryze AI at claude.ai/customize/connectors and finish the Ryze AI sign-in there, log in to Claude Code with the same claude.ai subscription account, then run /mcp. Connectors added in claude.ai appear with an indicator that they come from claude.ai. On Team and Enterprise plans an Owner adds the connector under Organization settings, Connectors, and each member then clicks Connect. These connectors load only when the active login is a claude.ai subscription; ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, a third-party provider or a setup-token credential stops them from loading, and /status shows which login is active. If the same address was also added with claude mcp add, that entry wins and /mcp lists the connector as hidden.
Scripts and limits
claude -p and Agent SDK runs cannot run the OAuth flow. Sign in first with /mcp or claude mcp login ryze, or use the Ryze AI API key method. Claude Code warns when a tool result passes 10,000 tokens and caps MCP output at 25,000 tokens by default. A HogQL answer above the cap is saved to a file, and the conversation gets the file path in its place; set MAX_MCP_OUTPUT_TOKENS to raise the cap. A call to an HTTP server that sends no response and no progress for five minutes is stopped.
Claude Code and MCP: the facts in one table
| Topic | What Anthropic's Claude Code docs say |
|---|---|
| Where the server entry is stored | Local and user scope: ~/.claude.json. Project scope: .mcp.json in the project root. Claude Code does not read ~/.claude/mcp.json |
| Transports | HTTP, which Anthropic recommends for remote servers such as this one; SSE, now deprecated; stdio for local processes; WebSocket in JSON only |
| Sign-in | OAuth 2.0. A server that answers 401 or 403 is marked as needing authentication until you choose Authenticate in /mcp. Tokens refresh on their own |
| Static credentials | --header (short form -H) or a headers object. A key pasted with a hidden trailing newline gets a whitespace warning in claude mcp list |
| Tool approval | From version 2.1.283, interactive terminal and VS Code sessions begin in auto mode if the session can use it, for example on a supported model. A call that matches an allow, ask or deny rule follows that rule, and a second model reviews other actions in your place |
| Where servers are managed | claude mcp list, get and remove in the shell, /mcp in a session or in the VS Code chat panel, and Customize, then Connectors, in the desktop app |
| Plan | A paid Claude plan that includes Claude Code, a Console account, or a provider such as Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. The MCP page adds no plan for remote servers |
| Ryze AI in the Anthropic Directory | A Community listing with the connector address, added August 2026. Community means screened, without an in-depth review |
Sources: Claude Code MCP, permission modes, setup, changelog, Claude custom connectors, Ryze AI in the Anthropic Directory. Checked November 14, 2026.
Claude web, ChatGPT and Cursor
The same URL works in other MCP clients. PostHog is connected once in Ryze AI, so nothing changes on the PostHog side.
Claude on the web and Desktop
Open Customize, Connectors, click + Add, choose Add custom connector, name it Ryze AI and enter https://connector.get-ryze.ai/mcp. Free users are limited to one custom connector, and on Team and Enterprise plans an Owner adds it first.
ChatGPT
OpenAI says full custom MCP server support is for ChatGPT Business and Enterprise/Edu on the web, and Pro can connect custom MCP servers with read and fetch permissions only. In Plugins choose Add custom MCP server, enter the URL and pick OAuth.
Cursor
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor runs OAuth with PKCE and asks for approval before using MCP tools by default.
{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }API key scopes and access
Three things decide what Claude Code can reach in PostHog.
- Which key and host
- Ryze AI stores a PostHog personal API key (phx_) and the host you enter: https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud or your self-hosted URL. The key needs read access to the project, including the Query and Insight scopes. A host that does not match where the account lives, or a key without those scopes, is rejected.
- Which project
- One connection holds one PostHog project, picked after you connect. PostHog is not on the Ryze AI list of platforms that support several accounts. To switch, click View on the card, disconnect with the trash icon and connect again, or use another workspace for another project.
- Read or write
- What Claude Code can change is limited by the scopes on the key. A key with read scopes only keeps it read-only, because PostHog rejects any change. Add write scopes only for the insights, dashboards, feature flags or cohorts you want Claude Code to edit.
The PostHog scopes behind each Ryze AI tool
Ryze AI reaches PostHog with the personal API key you create, so the scopes and projects you set on that key limit what it can reach, and the key acts as the person who made it. Each scope has a read level and a write level, and write includes read.
| PostHog scope | What PostHog says it covers | On the key Ryze AI asks for |
|---|---|---|
| query:read | SQL and insight queries on the project's data, plus event, session and web vitals lookups. No write level | Yes, as the Query scope |
| insight:read, insight:write | Insights with their queries, results and explanations | Read, as the Insight scope. Write only to create or edit insights |
| dashboard:read, dashboard:write | Dashboards with their tiles, text cards and layout | Not named. Add read if a dashboard request fails with a 403 naming it |
| feature_flag:read, feature_flag:write | Flags with their release conditions, variants, payloads and rollout history | Not named. Same rule as dashboards |
| cohort:read, cohort:write | Cohorts with their filters, static member lists and calculation history | Not named. Add read if a cohort list fails with a 403; write is needed to create or delete a cohort |
| person:read, person:write | Persons and their properties | Not named. Add read if a request for persons fails with a 403 naming it |
| event_definition:read, event_definition:write | Event definitions, schemas and property groups | Not named. Add read if listing event definitions fails with a 403 |
Not included by default: any write scope on the key, a second project in the same workspace, and the MCP Server key preset, which PostHog made for its own MCP server and CLI. Ryze AI does not list session recordings, experiments, surveys or error tracking among what its tools cover, so this guide makes no claim about them.
A key can cover the whole organization, chosen projects or every project, and its scopes can be changed later. If GitHub secret scanning finds an exposed phx_ key, PostHog rolls it and emails the owner.
Sources: PostHog API scopes, PostHog personal API keys, PostHog API documentation, Ryze AI PostHog guide. Checked November 14, 2026.
Removing access
To remove access, click View on the PostHog card in Ryze AI and disconnect with the trash icon, or delete the personal API key in PostHog. In Claude Code, run claude mcp logout ryze and then claude mcp remove ryze: remove alone deletes the stored tokens without revoking them at the sign-in server. To pause the server and keep its entry, toggle it off in /mcp; that choice is kept per project.
What Claude Code can do in PostHog
The Ryze AI connector exposes 3 PostHog tools: 1 read, 1 write and 1 delete. They run against the one project you picked.
| Tool | Type | What it does |
|---|---|---|
| posthog__read | Read | Reads projects, insights, dashboards, feature flags, cohorts, persons and event definitions, and runs HogQL analytics queries. |
| posthog__write | Write | Creates or updates PostHog objects such as insights, dashboards, feature flags and cohorts. |
| posthog__delete | Delete | Deletes a PostHog object by path, for example a cohort. The deletion is irreversible. |
Claude Code has its own permission system. Rules for an MCP tool follow the pattern mcp__<server>__<tool>, with your server name in place of <server>, and each rule allows, asks or denies. Interactive sessions on version 2.1.283 or later start in auto mode when it is available, and an ask rule still makes a matching call ask first, so add ask rules for posthog__write and posthog__delete if you want to see each change before it runs. In the claude.ai connector settings (Customize, Connectors, Ryze AI, Tool permissions) you can set write and delete tools to Needs approval. In the Ryze AI chat the Tool approvals picker starts on Skip all approvals, so the agent runs PostHog tools on its own by default; switch it to Approve write & delete or Manual approve. Scheduled tasks in Ryze AI run without an approval step.
Limits in numbers
Ryze AI adds one rule of its own: a HogQL query needs a time window and a row limit of 1,000 or fewer. Every other number below is PostHog's or Claude Code's, counted the way that vendor counts it.
| Limit | What the docs say |
|---|---|
| Analytics endpoints | 240 requests per minute and 1,200 per hour for each personal API key, for example to calculate insights |
| Query endpoint | 2,400 per hour. PostHog's queries page counts it per project, with 240 per minute, 3 queries at once and 10 seconds of execution each |
| Hourly read budget | A budget of bytes read per project for queries made with a personal API key. PostHog gives no byte figure; cached results still come back once it is spent |
| Other read, create, update and delete calls | 480 per minute and 4,800 per hour for each personal API key |
| Rows in one query | 100 unless you set a LIMIT, up to 50,000 with one. Through Ryze AI, 1,000 at most |
| Paging | OFFSET answers HTTP 400 for personal API keys; PostHog points to keyset pagination on timestamp |
| Who the limits count against | Most count per personal API key, not per team, and PostHog is not offering higher ones |
| Claude Code tool output | A warning above 10,000 tokens and a cap of 25,000 by default. Text longer than 50,000 characters goes to a file |
Sources: Claude Code permissions, PostHog API rate limits, PostHog query API, PostHog personal API keys, PostHog cohorts, Claude Code MCP output limits. Checked November 14, 2026.
First 3 prompts to run
Each answer comes from your own project, so this page describes what comes back instead of showing sample numbers.
1. A bounded HogQL query
Run a HogQL query on my PostHog project: count $pageview events per day for the last 14 days, with a LIMIT of 100.
Tools used: posthog__read
What comes back: A table with one row per day and its pageview count. Ryze AI expects a time window and a row limit of 1,000 or fewer on HogQL queries, so keep both in the prompt.
2. Inventory of dashboards and flags
List my PostHog dashboards, insights and feature flags, and tell me which flags have no description.
Tools used: posthog__read
What comes back: Lists of dashboards, insights and flags for the connected project, with the flags that lack a description called out. If PostHog answers with a 403 that names dashboard:read or feature_flag:read, add that scope to the key in PostHog, which lets you change scopes after the key is made.
3. Build a cohort or insight
Create a PostHog cohort of persons who triggered the signup event in the last 30 days, then show me its definition.
Tools used: posthog__write, posthog__read
What comes back: A new cohort and its definition. This needs a key with write scopes; with a read-only key PostHog rejects the change.
Deleting is a separate tool, so ask for it by name and object, and set write and delete tools to ask first as described above. The Ryze AI help center describes deleting insights, dashboards, feature flags and cohorts when explicitly asked.
10 jobs to hand to Claude Code
Ten jobs for Claude Code, each with the Ryze AI tool and the PostHog scope behind it. None was run for this guide. The last column assumes the key Ryze AI asks for: Query and Insight scopes, no write scopes.
| Job | What to type in Claude Code | Tool | PostHog scope | Works with that key |
|---|---|---|---|---|
| Pageview trend | Count $pageview events per day for the last 7 days with HogQL, capped at 1,000 rows. | posthog__read | query:read | Yes |
| Campaign traffic | Break last month's sessions down by UTM source with a HogQL query over sessions. | posthog__read | query:read | Yes |
| Funnel readout | Open my saved signup funnel insight and tell me how many people reach each step. | posthog__read | insight:read, query:read | Yes |
| Dashboard names | List the dashboards in this project by name so I can point you at one later. | posthog__read | dashboard:read | Not confirmed. It works when the key also has dashboard:read |
| Flag check before a launch | List the feature flags with their current rollout settings. | posthog__read | feature_flag:read | Not confirmed. It works when the key also has feature_flag:read |
| Cohort review | List the cohorts and what defines each one. | posthog__read | cohort:read | Not confirmed. It works when the key also has cohort:read |
| Event check | List the event definitions so I can see which events exist before we build a report. | posthog__read | event_definition:read | Not confirmed. It works when the key also has event_definition:read |
| New campaign dashboard | Create a trends insight for landing page signups and put it on a new campaign dashboard. | posthog__write | insight:write, dashboard:write | No. Add both write scopes first |
| Campaign cohort | Build a cohort of people who arrived from one campaign. | posthog__write | cohort:write | No. It needs cohort:write |
| Remove a test cohort | Delete the old test cohort I name here. This cannot be undone. | posthog__delete | cohort:write | No. It needs cohort:write and a request that names the cohort |
6 ways to connect Claude Code to PostHog
Claude Code can reach PostHog in six ways whose makers document them for it. This guide uses the Ryze AI connector as the main way: one claude mcp add command, a browser sign-in, and a PostHog key whose scopes you set yourself. PostHog's own server, plugin and CLI, plus two hosted services, were checked on November 14, 2026, and each row says what it takes inside Claude Code.
| Way | Where it runs | How you add it in Claude Code | What it can reach in PostHog | Cost |
|---|---|---|---|---|
| Ryze AI connector (the main way) | Hosted by Ryze AI, one address for everyone | claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, then Authenticate in /mcp. An API key with --header or a claude.ai connector also works | 3 tools on one project: insights, dashboards, flags, cohorts, persons, event definitions and HogQL. Changes need write scopes on the key | Paid Ads is $89 per month with a 7-day free trial |
| PostHog MCP server | Hosted by PostHog at https://mcp.posthog.com/mcp, routed to your US or EU region at sign-in | claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user, or npx @posthog/wizard mcp add | 1,284 tools in 78 categories. Claude Code gets CLI mode, a single exec tool, by default; ?readonly=true drops every tool that changes data | Free to connect and call. Some tools may count as PostHog AI spend |
| PostHog AI plugin | Plugin files on your computer, pointing at PostHog's hosted server | claude plugin install posthog, then /mcp to log in to PostHog | The hosted server's tools, 30+ skills, and slash commands such as /posthog:flags | No price stated. MIT license |
| PostHog CLI (posthog-cli) | Shell commands on your computer or a CI runner | npx @posthog/wizard cli add, which also writes instructions into CLAUDE.md, then posthog-cli login | PostHog's API and MCP tool catalog from the shell, SQL included, within the key's scopes | No price stated. MIT on npm |
| Composio | Hosted | Add https://connect.composio.dev/mcp as an HTTP server, authenticate and allow access. PostHog is linked inside Composio with your own API key | 686 tools and 11 triggers in its Posthog toolkit | Free up to 10,000 tool calls a month. Standard is $18 per seat per month |
| Zapier MCP | Hosted | Add Zapier as a connector and sign in. Zapier lists a programmatic install for Claude Code | One action, Capture Event. No reads are listed | Two tasks from your Zapier plan per successful call |
Options that do not fit Claude Code
- PostHog's connector in Claude's directory. The listing names Claude only, shows 57 tools and uses the same hosted address. Anthropic says connectors added in claude.ai also load in Claude Code under a claude.ai subscription login, but PostHog's Claude Code page documents the claude mcp add route instead.
- PostHog's plugin in ChatGPT names ChatGPT only. Enterprise-managed authorization is documented for Claude on Team or Enterprise with PostHog's Scale or Enterprise add-on, and does not name Claude Code.
- Windsor.ai, Coupler.io, AnythingMCP, viaSocket and Improvado. Their PostHog pages do not name Claude Code. Windsor.ai lists ChatGPT, Claude, Perplexity, Cursor, Grok, Gemini Enterprise, Copilot Agent, Manus, Lovable and Antigravity; Coupler.io lists Claude, ChatGPT, Gemini, Copilot, Cursor, Perplexity and OpenClaw; AnythingMCP lists ChatGPT, Claude, Gemini, Cursor, Copilot, OpenClaw and Meta Muse; viaSocket lists ChatGPT, Claude and Cursor; Improvado names Claude and Cursor.
- Retired PostHog packages. posthog-for-claude, an earlier Claude Code plugin, and the standalone PostHog/mcp repository are archived, and @posthog/agent-toolkit is deprecated in favor of the MCP server.
Which one to pick
Ryze AI is the best way to connect Claude Code to PostHog when you want a small read, write and delete set on one project behind the same address as your other connected platforms, with caveats: it covers one project and three tools, needs a Ryze AI plan or trial, and your PostHog data passes through Ryze AI. Pick PostHog's own server for PostHog's full catalog, such as session replay, experiments or error tracking, with no Ryze AI plan, and add the plugin for its skills. PostHog's CLI page says MCP is useful when an agent has no terminal. Claude Code runs in one, so the CLI is an option inside it too, and it also fits scripts and CI. Composio suits teams that already run it. Zapier lists only Capture Event, so it sends events and lists no reads.
Sources: PostHog MCP server docs, PostHog MCP for Claude Code, PostHog MCP, tools reference, PostHog AI plugin, PostHog CLI, managed authorization, Claude directory, Claude Code MCP, Composio, Composio pricing, Zapier, Zapier quickstart, Windsor.ai, Coupler.io, AnythingMCP, viaSocket, Improvado, Ryze AI PostHog guide. Checked November 14, 2026.
PostHog, Claude Code and MCP: dates that matter
| Date | What happened |
|---|---|
| June 18, 2025 | Claude Code 1.0.27 added streamable HTTP servers and OAuth for remote servers, the transport and sign-in this guide uses. |
| January 20, 2026 | PostHog created posthog-for-claude, a Claude Code plugin, now archived. |
| February 18, 2026 | PostHog created the PostHog/ai-plugin repository. Claude Code 2.1.46, dated the same day, began to load claude.ai connectors. |
| June 22, 2026 | Claude Code 2.1.186 added claude mcp login and claude mcp logout. |
| August 27, 2026 | PostHog simplified MCP login: setup in Claude Code and Codex hands the OAuth sign-in to the editor. |
| September 28, 2026 | Claude Code 2.1.284 made interactive sessions start in auto mode on every plan and provider when no permission mode is set. |
| October 1, 2026 | PostHog MCP clients with non-rotating refresh tokens stopped having to authorize again after roughly 67 days. |
| October 22, 2026 | PostHog's changelog: the wizard detects Claude Code and Codex and installs the MCP connection. |
| November 13, 2026 | Claude Code 2.1.325, the newest on its changelog when checked, and @posthog/wizard 2.94.0 came out. |
| November 14, 2026 | On the day of checking, the PostHog AI plugin manifest showed version 1.1.98, and PostHog's MCP page counted 1,284 tools in 78 categories. |
Sources: Anthropic MCP announcement, Claude Code changelog, PostHog changelog, PostHog/mcp, PostHog/posthog-for-claude, PostHog/ai-plugin, @posthog/wizard versions on npm. Checked November 14, 2026.
How this guide was tested
Two checks were run against the live Ryze AI connector on November 13, 2026, at about 04:20 UTC. Neither one needs a PostHog project. The table gives what came back.
| What was run | What came back |
|---|---|
| A request to the connector address with no sign-in | HTTP 401, with a WWW-Authenticate header that points to the sign-in details. Claude Code's docs say a server that answers this way is marked as needing authentication until you sign in. |
| The two discovery files on the connector's host | Both loaded. They name the authorize, token and register endpoints, the authorization code and refresh token grants, PKCE with S256, and two scopes, mcp:read and mcp:write. |
Not run for this page: any call to PostHog. No PostHog test account was connected, so no PostHog tool was called and the page shows no PostHog output. The steps inside Claude Code were not run either: no server was added with claude mcp add and no sign-in was made from /mcp. The Claude Code steps follow Anthropic's documentation and the PostHog figures follow PostHog's pages, both as read on November 14, 2026. The steps in PostHog and Ryze AI follow the Ryze AI help center.
Errors and fixes
- PostHog rejects the key when you connect
- The host may not match where the account lives, or the key lacks the Query and Insight scopes. Use https://us.posthog.com or https://eu.posthog.com to match the account, or your self-hosted URL, and create the key again with those scopes.
- Claude Code says the server failed to connect with an API key
- If a configured Authorization header is rejected, Claude Code reports the connection as failed and does not fall back to OAuth. Check that the key is a current Ryze AI rk_live_ key and that the URL ends in /mcp, or remove the server and add it again without --header. A warning about leading or trailing whitespace in headers.Authorization means the pasted key carried a hidden character.
- claude -p or an Agent SDK run cannot sign in
- Those runs cannot run the OAuth flow. Sign in first with /mcp or claude mcp login ryze in an interactive shell, or use the Ryze AI API key method.
- The server does not load from .mcp.json
- Project-scoped servers wait for approval in an interactive session before they connect. Approve it when Claude Code asks.
- No PostHog tools appear
- If the connector was added before PostHog was connected, run claude mcp remove ryze, add it again, then start a new session. Tool search is on by default, so tools load on demand and may not be listed up front.
- A HogQL query is refused or returns nothing useful
- Ryze AI expects a time window and a LIMIT of 1,000 or fewer on HogQL queries. Ask for both.
- The result lands in a file or is very large
- Claude Code warns above 10,000 tokens, and past 25,000 tokens by default it saves the result to a file and hands Claude the file path. Ask for fewer columns or rows, or raise MAX_MCP_OUTPUT_TOKENS.
- Queries are rate limited
- PostHog allows 240 requests per minute and 1,200 per hour on analytics endpoints for each personal API key, and 2,400 per hour on the query endpoint, which its queries page counts per project. A 429 with api_queries_budget_exceeded means the project's hourly read budget is spent. Wait for the Retry-After time, then retry.
- Changes fail
- The key probably has read scopes only. PostHog answers a request without the needed scope with a 403 error that names the missing scope. Create a key with write scopes for the objects you want changed, and save it again in the PostHog card in Ryze AI.
- The one-time connection link is refused
- Ryze AI refuses it while PostHog is already connected in the workspace. Change the project or the key in the Ryze AI app instead.
- Claude says a subscription is required
- The PostHog tools need an active Ryze AI plan or free trial. Start the trial in Ryze AI and retry.
Terms on this page
- MCP
- The Model Context Protocol, which Anthropic open-sourced in November 2024. Claude Code uses it to reach outside tools.
- Personal API key
- A PostHog key that starts with phx_ and acts as the user who made it. Each user can hold up to 10.
- Key scope
- A PostHog permission on one part of the product, with a read level and a write level.
- Server scope
- In Claude Code, where a server entry lives: local, user or project.
- HogQL
- PostHog's SQL, a wrapper around ClickHouse SQL. PostHog uses the name HogQL for SQL access internally.
- Insight
- PostHog's building block for product analytics, such as a trend, funnel or retention chart.
- Cohort
- A saved list of people who share something. Dynamic cohorts refresh once every 24 hours.
Sources: Anthropic on MCP, PostHog personal API keys, PostHog scopes, PostHog SQL, PostHog insights, PostHog cohorts. Checked November 14, 2026.
Frequently asked questions
How do I connect Claude Code to PostHog?
Save a PostHog personal API key and host in the PostHog card in Ryze AI, then run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp. Inside Claude Code run /mcp, select ryze, sign in on the Ryze AI page, choose the workspace and click Allow connection. Check it with claude mcp get ryze.
Does PostHog have an MCP server for Claude Code?
Yes. PostHog runs a free hosted MCP server at https://mcp.posthog.com/mcp and documents three ways to add it to Claude Code: claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user, npx @posthog/wizard mcp add, or the PostHog plugin. Sign-in routes you to your US or EU region. The Ryze AI connector is a separate route with 3 PostHog tools.
Which PostHog connector should I use with Claude Code?
Ryze AI is the best PostHog connector for Claude Code when you want one hosted URL that also carries your other connected platforms, but it covers one project and 3 tools and needs a Ryze AI plan. PostHog's own server needs no Ryze AI plan and offers PostHog's wider tool set.
Can Claude Code use the Ryze AI connector and PostHog's server at the same time?
Yes. Add each under its own name, for example ryze and posthog. They have different addresses, so Claude Code keeps both, and its MCP page names no limit on the number of servers. Each tool name carries its server name, in the pattern mcp__<server>__<tool>, so you can tell which one ran.
Which Claude plan do I need for Claude Code?
Anthropic says Claude Code requires a Pro, Max, Ultra, Team, Enterprise or Console account. The free claude.ai plan does not include it. Claude Code can also run through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.
Should I use OAuth or an API key?
OAuth through /mcp is the simplest on a personal machine. A Ryze AI API key from Workspace Settings, Profile, API keys suits scripts, because claude -p and Agent SDK runs cannot run the OAuth flow. That key works on the /mcp endpoint only and is separate from your PostHog key.
Does the Ryze AI connector need PostHog's MCP Server key preset?
No. That preset is for PostHog's own MCP server and CLI. For Ryze AI, create a personal API key with read access to the project and the Query and Insight scopes, and add write scopes only for objects Claude Code should change.
Can Claude Code change my PostHog project?
Yes, within the key's scopes. The connector has a write tool for insights, dashboards, feature flags and cohorts and a delete tool. A key with read scopes only keeps Claude Code read-only, because PostHog rejects any change. Set write and delete tools to ask first if you want to approve each change.
Which PostHog host do I enter?
Enter https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud, or the URL of your self-hosted instance. A host that does not match where the account lives makes PostHog reject the key.
Can I connect more than one PostHog project?
Not in one workspace. Ryze AI holds one PostHog connection per workspace, with one project picked after connecting. To switch, disconnect and connect again, or keep another project in another workspace.
What does the claude mcp add scope change?
Local scope, the default, keeps the server to the current project. User scope loads it in all your projects. Project scope writes .mcp.json so the team shares it, and each person approves it in an interactive session. The scope is fixed once the server is added, so changing it means removing the entry and adding it again.
Why does claude mcp list show ryze as Needs authentication?
Because no sign-in has been stored for it yet, or the stored one was cleared. Open /mcp in Claude Code and pick Authenticate on ryze, or sign in from the shell with claude mcp login ryze. If a refresh token is rejected later, the same menu offers Re-authenticate, and /mcp reconnect all retries every server that failed or is signed out.
Why do the PostHog tools not show up?
Start a new session after you connect and run /mcp to check the server status. If the connector was added before PostHog was connected, remove and re-add it. If a claude.ai connector is missing, you must be logged in with a claude.ai subscription account.
How much does it cost?
Connecting the connector is free, but the PostHog tools need an active Ryze AI plan or free trial. Paid Ads is $89 per month with a 7-day free trial, SEO Starter is $129 per month with a 3-day free trial and Agency is $279 per month. Annual billing takes 30% off the first year.