Skip to main content
The main event. Launches a real browser, navigates the target URL as the chosen persona, and returns a markdown report plus structured JSON findings.

​
Inputs

FieldTypeDescriptionDefault
urlstringURL to test. Supports localhost and any valid URL.required
taskstringWhat the persona should try to do. Minimum 10 characters for clarity.required
persona_idstringCloud persona UUID. Get it via list_personas.required
max_stepsnumberMaximum steps before stopping (1–200).50
headlessbooleanRun the browser in headless mode.false (visible so you can watch)
timeoutnumberOverall test timeout in seconds.no limit
viewportobject{ width, height } for the browser viewport.{ 1280, 800 }

​
Output

Three pieces of content:
  1. A full markdown report — the same report you’d see in the web app, ready to paste into a document.
  2. The structured JSON — issues, flow analysis, score, metadata. Useful if Cursor wants to do something programmatic with it.
  3. A path to a saved markdown file — percio-report-<timestamp>.md written to the working directory for future reference.

​
Required flow before calling this tool

The tool itself enforces an ordered flow via its description — a well-behaved MCP client (like Cursor) will:
  1. Call list_personas and present the personas to you.
  2. Let you pick one or offer to create a new one via chat_persona + create_persona.
  3. Call chat_scenario to build the scenario with you.
  4. Show the generated scenario to you for approval.
  5. Only then call run_usability_test with your chosen persona_id and the approved scenario as task.
If you see Cursor trying to run a test without confirming the persona and scenario with you first, stop it and ask it to follow the standard flow.

​
Example prompts in Cursor

“Run a usability test on http://localhost:3000/checkout using Rachel the power user.”
“Test the sign-up flow on the staging site with the first-time visitor persona. Then rerun it with the power user persona so I can compare.”

​
Visibility vs. headless

The default is visible — the browser window appears on your desktop so you can watch the agent work. Pass headless: true if you’re running in the background and don’t want a window popping up, or if you’re on a headless system.

​
Timeouts and step limits

  • max_steps defaults to 50. For simple flows, 25 is usually plenty. Raise it (up to 200) for long flows with many navigation steps.
  • timeout is optional. If you want a hard wall-clock cap, set it — otherwise the test runs until it completes or hits max_steps.

​
Where the report is saved

A timestamped markdown file is written to the current working directory of the MCP server process: 
percio-report-2026-04-21T17-42-32.md
The same report appears in your test history in the web app.

​
What’s next