@percio/mcp

Use Percio from your AI assistant.

Percio helps you run AI-guided usability tests on real sites: you describe what to check and which user mindset matters, and Percio walks through the flow and reports findings.

This package is an MCP server (Model Context Protocol): assistants that support MCP can call Percio on your behalf — planning the test, driving a browser on your machine, and saving results to your Percio account.

What you need

• Node.js (a current LTS version is fine).
• A Percio account and API key from percio.app (account settings / Integrations).
• Chromium for the automated browser (install once):

npx playwright install chromium

You do not need to npm install this package globally; your assistant runs it via npx (see below).

Configure your assistant

Every MCP client needs three things: run the server with npx, pass -y and @percio/mcp, and set your API key in the server environment.

Cursor

1. Open Settings → MCP (or your project’s MCP config file, e.g. .mcp.json).
2. Add a server (any name you like, e.g. percio).
3. Command: npx
4. Arguments: -y, @percio/mcp
5. Environment: PERCIO_API_KEY = your key from Percio.

Example:

{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["-y", "@percio/mcp"],
      "env": {
        "PERCIO_API_KEY": "$API_KEY"
      }
    }
  }
}

Save, reload MCP if the app asks you to, and confirm Percio appears in the MCP server list.

Claude Desktop

1. Open Developer settings and edit the MCP JSON config.
2. Under mcpServers, add an entry with the same shape as above (npx, args -y + @percio/mcp, PERCIO_API_KEY in env).
3. Restart Claude Desktop.

Other MCP clients

If the client supports stdio servers with command, args, and env, use the same pattern: npx + -y + @percio/mcp + PERCIO_API_KEY.

How to use

1. In chat, say which site (URL) you want tested and type the scenario yourself in plain language (≥ 20 chars). The assistant won't author the scenario from URL/persona alone — Percio's contract is that the user owns the scope.
2. The assistant will ask whether the flow needs runtime credentials (login email/password, API tokens, …). Paste them in chat if so; they're forwarded only to this run and discarded after.
3. Confirm when you're ready — the assistant calls percio_confirm_scenario(confirmed:true, scenario, credentials_asked:true) and then percio_start_test. Chromium opens only on percio_navigate.
4. Follow the run in chat; when it finishes, open percio.app to review full results in your workspace if you want.

If something fails, check: API key is correct, Chromium is installed, and your Percio plan allows the action you requested.

Tool order (canonical Path A)

The host model must follow this order; the server returns structured errors for skipped steps.

1. list_personas (and optionally create_persona for a custom one).
2. The user types the scenario in chat (≥ 20 characters); the assistant asks about runtime credentials.
3. percio_confirm_scenario({ confirmed: true, scenario, credentials_asked: true }).
4. percio_start_test({ url, persona_id, scenario, credentials? }) → returns session_id.
5. percio_navigate({ session_id, url, persona_id, scenario }) (only step that opens Chromium).
6. Atomic loop: percio_get_state → percio_click / percio_type / percio_scroll / … with percio_step_result after each material action.
7. percio_complete({ session_id, status }).

create_persona (session-based)

BREAKING (v2.1.0): create_persona no longer accepts { name } only. It runs the same multi-turn guided conversation as the web app (POST /api/agent/persona-chat), then saves via POST /api/agent/personas when the chat signals completion.

1. First call: omit persona_session_id. Optionally pass user_message if the user already gave a short description.
2. Response: JSON includes persona_session_id, assistant_message, and phase: "conversation" until done.
3. Follow-ups: pass persona_session_id and user_message (the user’s exact reply — never fabricated).
4. Done: when phase is "complete", the persona row is created; the payload includes the persisted persona.

Sessions expire after 1 hour; the server keeps at most 200 active sessions (oldest evicted when over capacity).

Runtime credentials

percio_start_test accepts an optional credentials array of { name, value } objects (≤ 20 entries, name 1–120 chars, value 1–4000 chars — same limits as the Test Lab modal in the web app). Forward only the values the user just gave you in chat; never source credentials from .env, host secrets, or staging defaults.

Lifecycle is in-flight only. The values are NOT stored on agent_sessions or any other Percio-side table. On the MCP execution path the host LLM (your assistant) is the navigation motor — it keeps the credentials in its own conversation context and applies them via percio_type when the page asks. The MCP controller only records that the session was started with credentials so percio_navigate can append a reminder to its execution instruction; the values themselves never cross the wire to the Percio API. Credentials are never echoed in any MCP tool response — do not paste them into percio_step_result.value either.

PERCIO_MCP_SKIP_CREDENTIALS_GATE (CI only)

Mirrors PERCIO_MCP_SKIP_PERSONA_TOKEN. Set to 1 / true / yes to make credentials_asked:true implicit on percio_confirm_scenario. Use this in scripted automation where there is no human to ask; never enable it in a host that talks to a real user.

Help

Product site and account: percio.app