--- title: MCP Server slug: mcp-server docTags: createdAt: 2026-05-04T13:09:58.348Z --- Personizely exposes its public API to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io). Connect ChatGPT, Claude, Cursor, or any MCP-compatible client to your Personizely account and ask questions in natural language: "How is my homepage popup performing this month?", "Stop campaign #12", "Compare the goal conversion rate of variation A and B over the last 14 days". ## Endpoint ```yaml https://mcp.personizely.net ``` OAuth 2.1 with PKCE. Each user signs in to their own Personizely account; tokens are scoped to the account they pick during consent. The server supports the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) and Dynamic Client Registration (RFC 7591) — most MCP clients can connect just by pointing at the URL above. ## Permissions Only Personizely **admins and owners** can authorize an MCP client. The OAuth consent screen will reject the request if your role is `member`. Ask your account admin to either authorize the client themselves or grant you admin access first. ## Connecting ### Claude Desktop / Claude Code In your MCP settings, add: ```json { "mcpServers": { "personizely": { "url": "https://mcp.personizely.net" } } } ``` Restart the client. The first call will pop up a browser window asking you to sign in to Personizely and pick which account to grant access to. ### ChatGPT Settings → **Connectors** → **Add connector** → enter: - **Name:** Personizely - **URL:** `https://mcp.personizely.net` ChatGPT will discover OAuth automatically and walk you through the sign-in flow. ### Cursor Settings → **MCP** → **Add new MCP server** → paste `https://mcp.personizely.net`. ### Other clients Any MCP client that supports OAuth 2.1 with Dynamic Client Registration. Point it at the URL above; the rest is auto-discovered. ## What you can do The server exposes 16 tools across 5 areas. The assistant chooses which tool to call based on what you ask — you don't need to know the names. The list below is a reference if you want to know what's possible. ### Websites If your account has more than one website, every other tool needs a `websiteId`. The assistant will list your websites and ask which one you mean. | Tool | What it does | | --------------- | --------------------------------------- | | `list_websites` | Lists every website under your account. | ### Campaigns Campaigns are personalization or A/B-test rules that run alongside your site's normal content (theme overrides, shipping rules, full-page experiments, etc.). | Tool | What it does | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_campaigns` | List campaigns. Filter by `active` and `type` (`personalization`, `themeExperiment`, `productPersonalization`, …). | | `get_campaign` | Full details for a single campaign, including its variations. | | `start_campaign` | Activate a campaign. | | `stop_campaign` | Deactivate a campaign. | | `get_campaign_results` | Per-variation analytics: views, reach, goal conversions, revenue per visitor, statistical significance, sample-size progress. Optional `dimension` (`device` / `country` / `channel` / `referrer`) for breakdowns. Optional `compareMetric` (`goalConversionRate` / `valuePerVisitor` / `profitPerVisitor`) controls which metric drives significance + improvement. | ### Widgets Widgets are popups, callouts, bars, and embedded blocks that render on your site. | Tool | What it does | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_widgets` | List widgets. Filter by `active` and `type` (`popup`, `callout`, `bar`, `embedded`). | | `get_widget` | Full details for a single widget, including its variations and any running experiments. | | `start_widget` | Activate a widget. | | `stop_widget` | Deactivate a widget. | | `get_widget_results` | Aggregate analytics for a widget — views, conversions, completions, goal conversions, revenue. | | `get_widget_experiment_results` | Per-variation analytics for a specific widget experiment. Same shape as `get_campaign_results`. Available `compareMetric` values: `conversionRate`, `completionRate`, `goalConversionRate`, `valuePerVisitor`, `profitPerVisitor`, `extraValuePerVisitor`. | The control variation in widget experiments represents visitors who weren't shown the widget — comparisons measure the lift the widget produces over no widget. `goalConversionRate` measures conversion into goals defined on the widget (Purchase, etc.); `conversionRate` measures interaction inside the widget itself (form submit, CTA click). ### Goals Goals are the conversion events you track on your site (purchases, signups, custom events). | Tool | What it does | | ------------ | ---------------------------------------- | | `list_goals` | List the goals configured for a website. | | `get_goal` | Details for a single goal. | ### Targets Targets are audience segments (e.g. "returning visitors from US on mobile") used by campaigns and widgets. | Tool | What it does | | -------------- | --------------------------------------------------- | | `list_targets` | List the audience targets configured for a website. | | `get_target` | Details for a single target. | ## Filters available on results endpoints Both `get_campaign_results` and `get_widget_results` (and the experiment variant) accept a `filters` object scoping the analytics to a slice of traffic: - `dateFrom` / `dateTo` — ISO 8601 timestamps - `device` / `browser` / `os` — arrays of values - `country` / `region` / `city` — arrays of values - `utmSource` / `utmMedium` / `utmCampaign` / `utmContent` / `utmTerm` - `referrer` - `visitorType` — `new` or `returning` Example: "How did campaign 5 perform last week on mobile in the US?" — the assistant translates this into `get_campaign_results` with the appropriate filters. ## Scopes The server requests two OAuth scopes: - `read` — read campaigns, widgets, goals, targets, and analytics. - `write` — start/stop campaigns and widgets. You'll see both on the consent screen. If you only want a read-only assistant, the MCP client can request only `read`; write tools then 403 if the assistant tries to call them. ## Troubleshooting - **"This MCP server doesn't implement OAuth"** — almost always a CORS or discovery issue on the client side. The server exposes `/.well-known/oauth-protected-resource` and a `WWW-Authenticate` challenge on unauthenticated requests; if your client fetches them but rejects the response, it's likely a transport issue specific to that client. Try a different MCP client to confirm. - **"compareMetric not available for experiments with a control group"** — `conversionRate` and `completionRate` measure interaction inside the widget, which a control visitor never sees. They're rejected when the experiment has a control share. Use `goalConversionRate` or one of the per-visitor revenue metrics instead. - **Tokens stop working after a long idle** — refresh tokens are long-lived, but if the connected app has been disconnected from your account (Settings → Connected apps), you'll need to re-authorize. ## Disconnecting Settings → **Connected apps** in your Personizely dashboard lists every MCP client (and any OAuth integration) that has access to your account. Click **Disconnect** to immediately revoke all tokens for that client.