Send a test fromthe editor.

Three steps

Copy-paste setup

The stdio package reads PERSQO_API_KEY. HTTP clients send Authorization: Bearer pq_live_.... OAuth for the remote server comes later.

claude mcp add persqo --env PERSQO_API_KEY=$PERSQO_API_KEY -- npx -y persqo-mcp

claude mcp add --transport http persqo https://persqo.com/mcp --header "Authorization: Bearer $PERSQO_API_KEY"

REST API v1

Base URL https://persqo.com/api/v1. One test spends one session from the plan quota and can include up to three personas. Send Idempotency-Key on POST so a retry returns the same test.

POST /tests
{ "url": "https://your-app.vercel.app",
  "personas": [{ "name": "Maya", "role": "First-time visitor", "device": "iPhone", "goal": "Sign up" }],
  "auth": { "email": "tester@example.com", "password": "..." } }

GET /tests/:id
GET /tests/:id/findings
GET /tests/:id/fix-prompt
POST /personas/generate   { "url": "https://your-app.vercel.app" }

GET /projects   POST /projects { "url" }
GET /sites
GET /personas   POST /personas
GET /findings?project_id=&severity=&status=&page=&persona=&run_id=
GET /findings/:id
POST /findings/:id { "status": "fixed" }
POST /findings/:id/retest
POST /runs { "confirm": true, "url": "...", "personas": "auto" }
GET /runs/:id/replay
GET /runs/:id/report
GET /runs/:id/pdf
GET /pages?project_id=
GET /trends?left=&right=
GET /schedules   POST /schedules
GET /shares   POST /shares { "run_id" }
GET /notifications   PUT /notifications

A pq_live_ key belongs to the workspace, not one project. It can read and change every site on that account. Pass project_id or a site URL when the workspace has more than one project. One project is selected for you. Several projects come back as project_choice so the caller can ask which one.

OpenAPI spec

MCP tools

Remote Streamable HTTP is at https://persqo.com/mcp. The same tools ship in persqo-mcp.

• run_test starts a test. wait: true polls until it finishes or the timeout, then returns a short summary and the fix prompt.
• get_test_status reads status, personas, findings, cost, and the report URL.
• get_findings returns severity, screenshots, and each fix prompt for one test.
• get_fix_prompt returns one prompt you can paste. On the stdio bridge this takes test_id. On /api/mcp it also accepts findingId.
• generate_personas suggests personas for a URL.
• list_tests lists recent tests.
• list_projects and list_sites are how an agent picks a site. create_project adds one from a URL.
• start_run is a dry run until confirm is true. Pass url or project_id, and personas as auto or persona ids. A new URL creates the project.
• list_personas and create_persona manage saved personas. project_id or a site URL is required when the account has more than one project.
• list_findings filters by project, run, severity, status, page, and persona. project_id or a site URL is required when the account has more than one project. get_finding includes Claude Code, Cursor, and Lovable prompts. update_finding and retest_finding change status and queue a retest.
• get_run_replay returns the step timeline, thoughts, actions, and the stuck marker.
• get_report and get_report_pdf return the score and the PDF URL.
• list_pages and get_trends return per-page scores and score over time, including opened versus closed and a two-run comparison. get_trends needs project_id or a site URL when the account has more than one project.
• list_schedules, save_schedule, and delete_schedule manage daily and weekly tests.
• list_shares, create_share, and revoke_share manage public report links.
• get_notifications and update_notifications read and set score-drop and schedule email.
• list_webhooks, create_webhook, and revoke_webhook match the webhook REST endpoints.

Workspace members each keep their own key. Every key sees every site in that workspace. Team invites are on the Team page in the dashboard. Operator accounts can call /api/mcp without the Pro plan, and the session limit does not stop them. Their own domains, including persqo.com, count as verified.

Webhooks

Register an https endpoint in Settings or with POST /api/v1/webhooks. The signing secret starts with whsec_ and is shown once. When every persona in a test finishes, Persqo POSTs test.completed.

Persqo-Event: test.completed
Persqo-Signature: t=1710000000,v1=<hmac sha256 of "t.body" with the whsec_ secret>

{ "id": "evt_...", "type": "test.completed", "data": { "id": "test_...", "status": "completed" } }

Testing a local app

# Vercel or Netlify: use the preview URL from the deploy.

# Or tunnel the machine:
ngrok http 3000
cloudflared tunnel --url http://localhost:3000

# Then:
run_test({ url: "https://your-preview.ngrok.io", wait: true })