Persqo

Persqo MCP Server

AI personas test your web app like real users, then hand your coding agent ready-to-paste fix prompts.

Persqo runs AI personas (first-time visitor, impatient mobile user, accessibility-dependent user, and more) through your live or preview site in a real browser. Every run gives you step-by-step recordings, screenshots, and prioritized findings. This MCP server lets Claude, Claude Code, Cursor, Codex, and any MCP client start a test, wait for it, read findings, and pull a fix prompt straight into the session.

The live remote server is https://persqo.com/api/mcp. This package is the stdio bridge for clients that launch a local command. It calls the Persqo API with Authorization: Bearer and the key from PERSQO_API_KEY. persqo-mcp is not published to npm.

Get an API key

Sign up at https://persqo.com and create an API key (pq_live_...) in Settings, then API keys. The secret is shown once. Put it in PERSQO_API_KEY. Do not put the key in the URL.

A 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 matches come back as project_choice.

Remote server

HTTP clients send Authorization: Bearer plus the key. The examples below read that key from PERSQO_API_KEY so the secret stays in the environment.

Claude Code

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

{  "mcpServers": {    "persqo": {      "type": "http",      "url": "https://persqo.com/api/mcp",      "headers": {        "Authorization": "Bearer ${PERSQO_API_KEY}"      }    }  }}

Cursor

{  "mcpServers": {    "persqo": {      "url": "https://persqo.com/api/mcp",      "headers": {        "Authorization": "Bearer ${env:PERSQO_API_KEY}"      }    }  }}

Or open the Cursor install link. Put the key in Cursor's secret store as PERSQO_API_KEY.

Codex and other MCP clients

Use the same URL and header. Clients that speak stdio can use the local command in the next section instead.

{  "mcpServers": {    "persqo": {      "type": "http",      "url": "https://persqo.com/api/mcp",      "headers": {        "Authorization": "Bearer ${PERSQO_API_KEY}"      }    }  }}

Claude and ChatGPT can also connect with OAuth at the same URL. That flow does not use an API key. API-key clients always send the Bearer header above.

Local stdio server

package.json maps the persqo-mcp command to bin.js, which is what npx executes. The process reads PERSQO_API_KEY and sends Authorization: Bearer <key>.

npx -y github:YaakovTzedek/persqo-mcp

{  "mcpServers": {    "persqo": {      "command": "npx",      "args": ["-y", "github:YaakovTzedek/persqo-mcp"],      "env": { "PERSQO_API_KEY": "pq_live_YOUR_KEY" }    }  }}

Claude Code:

claude mcp add persqo --env PERSQO_API_KEY=$PERSQO_API_KEY -- npx -y github:YaakovTzedek/persqo-mcp

Optional PERSQO_API_BASE (default https://persqo.com).

Visitor place

Personas, runs, schedules, retests, and finding filters take four place fields. A project stores the same four as defaults. Omit a field to keep the project default.

create_project accepts these as project defaults. list_projects returns them. create_persona, list_personas, start_run, save_schedule, list_schedules, retest_finding, and list_findings accept them as overrides or filters. Persona and schedule results include the place stored on each record.

Tools

start_run and reproduce_ticket are dry runs until confirm is true. run_test with wait: true polls until the test finishes or timeout_ms (default 120000, max 600000) and then returns a summary plus the fix prompt.

The Persqo browser cannot open localhost. Use a Vercel or Netlify preview, or an ngrok or cloudflared tunnel.

Projects, runs, and tests

Personas and findings

Schedules, sharing, and notifications

Tickets

Localhost

The Persqo browser cannot open localhost. Deploy a preview (Vercel or Netlify) or tunnel the machine:

ngrok http 3000cloudflared tunnel --url http://localhost:3000

Then pass that https URL to start_run or run_test.

License

MIT