Skip to main content
The Percio agent is a local tool that runs real-browser usability tests against any URL — including localhost. It ships as a single npm package, @percio/agent, which gives you two surfaces:
  • The percio CLI — run tests from your terminal. Great for dev loops, CI, and anywhere you can reach a URL that the Percio web app can’t.
  • The percio-mcp MCP server — expose Percio as a set of tools to MCP-capable clients like Cursor, so you can kick off tests without leaving your editor.
Both surfaces use the same account, the same personas, and the same Percio API. A test run from the CLI shows up in your test history in the web app just like any other.

​
When to use the agent vs. the web app

Use the agent when:
  • You’re testing localhost, staging on a private network, or any URL the Percio web app can’t reach.
  • You want to run tests from your terminal or CI instead of clicking through a UI.
  • You want Percio tools available in Cursor while you’re coding.
Use the web app when:
  • You’re testing a publicly reachable URL and want the polished UI.
  • You want to watch the browser run live and inspect results in one place.
  • You’re sharing reports with non-technical teammates.
You can freely mix — a test started from the CLI lives alongside tests from the web app.

​
What gets installed

npm install -g @percio/agent installs both:
  • The percio CLI (entry point: percio)
  • The percio-mcp MCP server (entry point: percio-mcp)
The MCP server is bundled — you don’t install it separately.

​
Requirements

  • Node.js ≥ 18
  • An API key (create one on the dashboard → Integrations)

​
In depth

Install

Install the npm package and verify the CLI is reachable.

Authenticate

percio login vs. PERCIO_API_KEY.

The daemon

What the local HTTP daemon does and why it exists.

CLI reference

Every command, every flag.

Cursor setup

Wire Percio into Cursor via MCP in two minutes.

MCP tools

The five tools exposed to MCP clients.