> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent overview

> The Percio CLI and MCP server — test localhost, drive Percio from Cursor

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

<Columns cols={2}>
  <Card title="Install" icon="download" href="/agent/install">
    Install the npm package and verify the CLI is reachable.
  </Card>

  <Card title="Authenticate" icon="key" href="/agent/authentication">
    `percio login` vs. `PERCIO_API_KEY`.
  </Card>

  <Card title="The daemon" icon="server" href="/agent/daemon">
    What the local HTTP daemon does and why it exists.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/agent/cli/login">
    Every command, every flag.
  </Card>

  <Card title="Cursor setup" icon="code" href="/agent/cursor-setup">
    Wire Percio into Cursor via MCP in two minutes.
  </Card>

  <Card title="MCP tools" icon="plug" href="/agent/mcp-tools/list-personas">
    The five tools exposed to MCP clients.
  </Card>
</Columns>