MCP (Model Context Protocol) is the open standard AI assistants use to work with outside services. Personyze runs an MCP server, so an assistant — Claude, ChatGPT, an agent you build yourself — can work with a Personyze account in conversation: read reports, inspect and build campaigns, manage audiences and visitor profiles, answer product questions.
It is the External API in the shape assistants speak, under the same permissions and the same keys.
This page is the protocol reference. For what an assistant can actually be asked to do, with examples, see the MCP server guide in the knowledge base.
Server URL: https://personyze.com/mcp/
Transport: Streamable HTTP, JSON-RPC 2.0.
Connecting a ready-made assistant
Most assistants ask only for the URL and then run the OAuth flow themselves:
- In the Personyze panel, open Integrations → AI Assistants (MCP) and copy the server URL.
- In the assistant, add a custom connector and paste it — Claude: Settings → Connectors → Add custom connector. ChatGPT: Settings → Connectors.
- Approve the connection on the Personyze screen that opens. Nothing is copied by hand; the assistant receives its own credential.
Authorization
OAuth 2.1, authorization code with PKCE. Public clients — there is no client secret.
- Discovery per RFC 9728 (protected resource) and RFC 8414 (authorization server), both served at the host root:
https://personyze.com/.well-known/oauth-protected-resourcehttps://personyze.com/.well-known/oauth-authorization-server
- Dynamic client registration per RFC 7591, at the advertised
registration_endpoint. A client can register itself; no manual application step. - PKCE: S256 required.
- Scope:
personyze:full. - Grant types:
authorization_code,refresh_token.
An unauthenticated request to /mcp/ answers 401 with a WWW-Authenticate header carrying resource_metadata, which is the discovery entry point:
WWW-Authenticate: Bearer realm="Personyze MCP",
resource_metadata="https://personyze.com/.well-known/oauth-protected-resource"API key instead of OAuth
Clients that cannot open a browser — a script, a CI job, an IDE plugin — can authenticate with a Personyze API key as a bearer token:
Authorization: Bearer YOUR_API_KEYKeys are generated under Integrations → AI Assistants (MCP), or the Full-featured API card; the two share one set of keys. See API keys.
Tools
Every tool acts under the permissions of the account that authorized the connection. Tools are annotated with readOnlyHint and destructiveHint so a client can decide what to confirm.
Campaigns and content
| Tool | |
|---|---|
list_campaigns |
The account's campaigns |
get_campaign_targeting |
Targeting rules as readable text, plus active dates |
create_campaign_draft |
Create a campaign in staging mode; targeting given in plain words is compiled into rules |
update_campaign_draft |
Rename, re-target or switch a staging-mode campaign |
duplicate_campaign |
Copy any campaign, live or staging, into a new staging-mode campaign |
list_actions |
Personalization actions — banners, popups, recommendations, email widgets |
get_action_content |
One action with its editable HTML and presenting rules |
set_action_active |
Pause or resume one live action |
list_placeholders / create_placeholder |
Named page regions actions render into |
Reporting
| Tool | |
|---|---|
get_campaign_performance |
Per-action daily counters over a date range: impressions, deliveries, clicks, dismissals, configured goals, revenue totals |
get_traffic_analytics |
Site-wide traffic by page, landing page, referrer, search term, device, city or country — with bounce, goal, click-through, new-user and mobile rates |
get_product_stats |
Per-product views, recommendation deliveries, favourites and purchases over rolling windows |
Audiences and visitors
| Tool | |
|---|---|
list_audiences / create_audience / delete_audience |
Visitor segments |
list_audience_members / add_audience_member / remove_audience_member |
Membership, by profile id, your own CRM id, or email |
get_visitors / save_visitor |
Search, create and update visitor profiles |
Help
| Tool | |
|---|---|
search_docs |
Search the Personyze knowledge base and answer from it |
open_support_ticket |
Open a ticket with the support team; replies arrive in the panel |
Everything else
personyze_api reaches any object of the External API directly, for requests the dedicated tools do not cover.
Writes are deliberately conservative
Two behaviours are worth knowing before you build on this:
New campaigns are created in staging mode. They are shown only to visitors arriving from a staging IP. Live traffic keeps seeing whatever is published now, and a person publishes the campaign in the panel themselves. The tool returns a direct panel URL for the new campaign, and reads the compiled targeting back — a rule that says something slightly different from what was asked for is otherwise indistinguishable from a correct one.
Pausing or resuming an action is live. It takes effect for real visitors as soon as the account's JavaScript rebuilds. It is one action per call, fully reversible, and the tool description requires the assistant to confirm in concrete terms first — naming the action, its campaign, and what visitors stop or start seeing.
Revoking access
Every connection rides on an API key belonging to the account. Delete the key under Integrations → AI Assistants (MCP) and access stops immediately.
The other direction
Personyze can also act as an MCP client, calling your own MCP servers — CRM, ticketing, a data warehouse — so an agent turn reaches your tools and Personyze's together. That is the Connected Tools (MCP) card on the same Integrations screen.