Persona MCP

Persona MCP lets supported AI clients work with your Persona projects, interviews, reports, and organisation credits. It uses your Persona Creator account and permissions, so you do not need an API key.

The environment selector in this documentation applies to REST API examples. Persona MCP uses the production server URL shown below.

MCP access must be enabled for your organisation. If authentication succeeds but access is denied, contact your Persona account manager.

Before you connect

You need:

A Persona Creator account in an MCP-enabled organisation
A supported client: Codex CLI, Claude Code, or Claude.ai
A browser to complete the Persona sign-in and authorization flow

Setting	Value
Name	`persona`
Server URL	`https://external-api.prod.insightscompany.io/mcp`
Transport	Streamable HTTP over HTTPS
Authentication	OAuth through Persona Creator

Never paste your Persona password or an API key into Claude or Codex. Enter credentials only on the Persona Creator sign-in page opened by the OAuth flow.

Connect your client

Add the Persona server:

codex mcp add persona \
  --url https://external-api.prod.insightscompany.io/mcp

Codex normally detects OAuth and opens your browser automatically. If it does not, start authentication explicitly:

codex mcp login persona

Confirm the connection:

codex mcp list

Inside Codex, you can also enter /mcp to inspect the connected server and its tools.

To switch Persona accounts, first sign out of Persona Creator in your browser, then run:

codex mcp logout persona
codex mcp login persona

To remove the connection:

codex mcp remove persona

Add Persona for your user account so it is available across projects:

claude mcp add --transport http --scope user persona \
  https://external-api.prod.insightscompany.io/mcp

Here, http is the MCP transport name. The server connection itself uses encrypted HTTPS.

Claude Code does not automatically sign in after adding the server, so start OAuth separately:

claude mcp login persona

Confirm the connection:

claude mcp list

To switch Persona accounts, first sign out of Persona Creator in your browser, then run:

claude mcp logout persona
claude mcp login persona

To remove the connection:

claude mcp remove --scope user persona

Individual accounts

Open Customize → Connectors.
Select +, then Add custom connector.
Enter Persona as the name and https://external-api.prod.insightscompany.io/mcp as the remote MCP server URL.
Leave the optional OAuth Client ID and Client Secret fields empty.
Select Add, then Connect and complete Persona authorization.

Team and Enterprise accounts

An Owner or Primary Owner must first open Organization settings → Connectors, select Add → Custom → Web, and add the Persona server URL. Each member can then open Customize → Connectors and select Connect to authorize their own Persona account.

Enable Persona for a conversation from + → Connectors in the chat composer.

To change accounts or revoke access, disconnect Persona under Customize → Connectors, sign out of Persona Creator, and connect again. Team and Enterprise owners can remove the shared connector from the organisation's connector settings.

See Anthropic's custom connector guide for current Claude plan and administration details.

Your browser opens Persona Creator

Sign in with the Persona account you want the client to use. If you are already signed in, Persona may take you directly to the authorization screen.

Review the access request

Confirm that the application is the client you intended to connect and that the server is Persona. Codex and Claude Code use a temporary callback on 127.0.0.1; this is a local listener in the CLI and is expected. Claude.ai uses its own HTTPS callback.

Approve and return to the client

Persona returns authorization to the client. The client refreshes its OAuth credentials when needed; if authorization is revoked or expires, run the login flow again.

Available capabilities

The client discovers the current tool schemas directly from Persona. At a high level, Persona MCP supports:

Area	Capabilities
Projects	List, filter, sort, inspect, review, create, and update projects; delete eligible drafts; preview and launch studies; inspect project statistics; generate grounded interview-question context
Stimuli	Upload images and videos to a STIMULI project; list uploaded assets; assign each asset to interview questions; replace or delete assets
Embed	Get ready-to-paste embed code snippets for a project; read and update the domain allowlist that controls which domains are permitted to host the embed
Interviews	List completed interviews and retrieve individual interview records and transcripts
Reports	List and retrieve reports, generate a new report, explicitly regenerate an existing report, and check generation status
Credits	Check paid and trial balances, review credit transactions, and create a Stripe-hosted top-up checkout link

Report generation and regeneration run asynchronously and may take a while. Processing time depends on the number and length of completed interviews being analysed. You can ask the client to check the existing generation job's status; avoid starting another job while one is already running.

generate_questions does not call an LLM itself — it returns the project's grounding (research objective, company context, churn context where relevant) as context for your connected AI client to draft questions with directly in its own response, then apply them via update_project or create_project.

Some clients can show interactive project-review and launch-confirmation cards. The same workflows remain available as text when the client does not render those interfaces.

Permissions and safety

Persona applies the same organisation and role boundaries on every tool call:

Boundary	Behaviour
Organisation access	The client can access only the organisation associated with the authenticated Creator user
View role	Can use read-only project, interview, report, statistics, balance, and transaction tools
Edit role	Can also create, update, delete, launch, generate reports, and create top-up checkout links
Delete project	Works only for an eligible unlaunched draft and requires explicit approval plus its exact current title
Launch project	Returns an exact, short-lived cost preview first and requires a new approval message before launch
Top up	Creates a Stripe checkout link; no payment occurs until you complete checkout on Stripe
Regenerate report	Replaces an existing report only after you explicitly request regeneration

Example prompts

Refer to projects by their human-readable title. Persona will look up the internal project ID for the client; if more than one project matches, the client should ask you which one you mean.

Read-only account check

Get my Persona credit balance and list my five newest projects. Do not create, update, delete, or launch anything.

Create a draft

Create a Persona research project about customer onboarding. Ask me about every important project preference before creating it, show me the complete draft for approval, and do not launch it.

Draft questions with AI

Draft interview questions for my project titled "Customer Onboarding Research" grounded in its research objective and our company context. Show me the questions for review before applying them.

Launch safely

Find my project titled "Customer Onboarding Research" and preview launching it for 10 completed interviews. Show me the exact cost and remaining balance, then stop and wait for my approval.

Analyse interviews

Summarise the completed interviews for the project titled "Customer Onboarding Research". Separate evidence from inference and cite the interview record IDs. Do not generate or regenerate a report unless I ask.

Read an existing report

Get the latest report for the project titled "Customer Onboarding Research" and explain its key themes, quantitative findings, and supporting evidence. Do not generate or regenerate anything.

Generate a report

For the project titled "Customer Onboarding Research", check whether a report already exists. If none exists, generate one focused on onboarding friction and monitor its status. If a report already exists, show me when it was created and ask whether I want to replace it; do not regenerate it automatically.

Regenerate a report

Regenerate the existing report for the project titled "Customer Onboarding Research", focusing on differences between first-time and experienced users. I understand this replaces the current report. Tell me when generation starts and how I can check its status.

Create a stimuli project

Create a Persona stimuli project where participants react to product mockup images. Ask me for the project details and my images. Once I've uploaded them, assign each image to the most relevant questions and show me the full setup before I approve launching.

Get embed code and set up the allowlist

Get the embed snippets for the project titled "Customer Onboarding Research". Then check the current domain allowlist and add my production domain https://app.example.com to it if it's not already there.

Top up credits

Check my current Persona balance and create a Stripe checkout link to add $50. Do not say I have been charged or update the balance until I complete checkout.

Troubleshooting

Problem	What to do
Access is denied after login	Confirm that MCP is enabled for your organisation and that your Creator user belongs to it. Contact your Persona account manager if needed.
The wrong Persona account opens	Disconnect or log out of Persona in the client, sign out of Persona Creator in the browser, then authenticate again.
Claude Code shows no Persona tools	Run `claude mcp login persona`, confirm with `claude mcp list`, and start a new Claude Code session if the current one was already open.
Codex shows no Persona tools	Run `codex mcp login persona`, confirm with `codex mcp list`, and use `/mcp` inside Codex to inspect the connection.
The browser shows a `127.0.0.1` callback	This is the expected local OAuth callback for Codex CLI and Claude Code. Keep the CLI running until authorization finishes.
A launch reports insufficient balance	Create and complete a top-up checkout, then request a new launch preview because previous previews can expire or become stale.
Authentication expired or was revoked	Run the client's logout and login commands again, or disconnect and reconnect Persona in Claude.ai.

For Codex-specific MCP configuration details, see the Codex MCP guide.

Persona MCP

On this page