create_persona
Adds one of the people the product is built for, so the stories that follow have someone to be written as.
Add a persona to a project: project_id and name are required; tagline, role_title, demographics, goals, frustrations, behaviours (each HTML), tech_proficiency (low, medium or high; medium by default), devices (short tags) and quote fill in the rest. The persona is written through the same action the People page and the intake wizard run, and persona.created goes out.
Write a persona for each kind of person the brief names before the stories that speak as them, so create_work_item can name the persona and the "as a" reads the same everywhere. A staff token with persona:create on the project is needed.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
project_id*stringUUID of the project.
name*stringWhat the persona is called, 2 to 80 characters.
taglinestringoptionalOne line that sums them up.
role_titlestringoptionalWhat they do, in their own world.
demographicsstringoptionalWho they are, as HTML.
goalsstringoptionalWhat they want from the product, as HTML.
frustrationsstringoptionalWhat gets in their way today, as HTML.
behavioursstringoptionalHow they work and what they reach for, as HTML.
tech_proficiencystringoptionalHow at ease they are with technology; medium by default.
lowmediumhighdevicesstring[]optionalThe devices they use, as short tags.
quotestringoptionalSomething they would say.
What it returns
{ "data": { "id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "name": "Busy parent", "tagline": "Drops laundry on the way to work and wants it back by Friday", "role_title": "Working parent of two", "demographics": null, "goals": "<p>Book a pickup in under a minute and know when the laundry is ready.</p>", "frustrations": "<p>Calling the shop to ask whether the order is done.</p>", "behaviours": null, "tech_proficiency": "medium", "devices": ["phone"], "quote": "Just tell me when it is ready.", "position": 1, "archived_at": null, "created_at": "2026-10-28T09:25:00+00:00", "updated_at": "2026-10-28T09:25:00+00:00" }}How it fails
VALIDATION_FAILEDname missing or outside 2 to 80 characters, a tech_proficiency outside the three, more devices than allowed, or a name another persona of the project already uses.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, or the holder's role on the project does not carry persona:create.
TOKEN_MISSING_ABILITYtoken lacks persona:create.
How is this guide?
Last updated on