Percio Agent (@percio/agent)

AI-powered usability testing agent — test any URL (including localhost) using a real browser.

This package ships:

• CLI: percio
• MCP server: percio-mcp (for Cursor/IDE integration)

Install

npm install -g @percio/agent

Requires Node.js >= 18.

Authenticate (API key)

Option A: Login (recommended)

percio login

This stores your key at ~/.config/percio/credentials.json and is used automatically by both the CLI and MCP server.

Option B: Environment variable

export PERCIO_API_KEY="pk_..."

Start the daemon

Percio uses a local daemon (HTTP on 127.0.0.1) that powers the CLI commands.

Foreground (recommended for integrated terminals)

percio start

Detached (like docker run -d)

percio start -d

Stop it later with:

percio stop

Run a usability test

Interactive (recommended) — Percio helps you build the test scenario:

percio test --url https://example.com
# → Starts a conversation to refine your test scenario, then runs the test

Direct — provide the scenario yourself:

percio test --url https://example.com --flow "Sign up for an account"

Use cloud persona IDs (UUIDs):

percio personas list
percio test --url https://example.com --flow "Buy a product" --persona-id <uuid>

Cursor MCP setup

Recommended: npx + API key (no login)

Install nothing globally. Create (or edit) .cursor/mcp.json:

{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["percio-mcp", "--api-key", "YOUR_PERCIO_API_KEY"]
    }
  }
}

Replace YOUR_PERCIO_API_KEY with your key from the Percio dashboard. Restart Cursor (or reload MCP servers).

Publish the percio-mcp package from packages/percio-mcp to npm so npx percio-mcp resolves; it depends on @percio/agent and runs the same MCP server.

Local clone (uses built dist/ — no stale global binary)

If MCP auth fails with npx (unpublished or cached old package), point Cursor at this repo’s build:

1. Run npm run build (output goes to dist/, which is gitignored).
2. Use .cursor/mcp.json in this repo: node + dist/mcp-server.js + --api-key (replace the placeholder key), or set PERCIO_API_KEY under env instead of --api-key.
3. Reload MCP servers in Cursor.

Optional check: npm run verify:mcp-auth confirms loadConfig() reads PERCIO_API_KEY after a build.

Alternative: global install + login

1) Install the package

npm install -g @percio/agent

2) Login once

percio login

3) Add MCP server to Cursor

Create (or edit) .cursor/mcp.json in your project:

{
  "mcpServers": {
    "percio": {
      "command": "percio-mcp"
    }
  }
}

Restart Cursor (or reload MCP servers). You should see Percio tools like:

• run_usability_test
• chat_scenario
• list_personas
• chat_persona
• create_persona

Configuration

Percio reads configuration in this order (highest → lowest):

1. Environment variables: PERCIO_API_KEY, PERCIO_API_ENDPOINT
2. Global credentials: ~/.config/percio/credentials.json (from percio login)
3. Built-in defaults (apiEndpoint, maxSteps, viewport)

There is no project config file; use MCP args / env for API keys or percio login for the CLI.

Binaries

• percio: CLI entrypoint
• percio-mcp: MCP server entrypoint (stdio)