> ## 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.

# Cursor setup

> Wire Percio into Cursor via MCP in two minutes

The Percio MCP server lets you use Percio tools directly from Cursor's AI. You can ask Cursor things like "run a usability test on the checkout flow" and it'll orchestrate the whole thing — picking personas, building a scenario with you, and running the test — through Percio's tools.

## Recommended setup — `npx` + API key

You don't need to install anything globally. Open **Cursor Settings → MCP**, or create **`mcp.json`** in your project root (some setups use **`.cursor/mcp.json`**).

Use this shape — replace the API key with the one from your Percio dashboard (**Integrations** → **Agent integrations**):

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

Paste your real key where `$API_KEY` is shown (or set `PERCIO_API_KEY` to that value in the `env` block).

Restart Cursor or reload MCP servers. The Percio tools should now be visible.

## Alternative — use `percio login` credentials

If you've already run `percio login` on your machine, you can omit the API key from config and rely on `~/.config/percio/credentials.json`:

```json theme={null}
{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["-y", "@percio/mcp"]
    }
  }
}
```

The MCP server reads stored credentials automatically when `PERCIO_API_KEY` is not set.

## Project-scoped vs. user-scoped config

Cursor supports both:

* **Project-scoped** — `mcp.json` or `.cursor/mcp.json` in the root of a project. Only applies when Cursor opens that project. Good for per-project keys.
* **User-scoped** — `~/.cursor/mcp.json` (or the global MCP config path Cursor shows in Settings). Applies across all projects when the same key is used everywhere.

Use whichever fits your workflow. Project-scoped wins if both exist.

## Reloading after a config change

Changes to `mcp.json` only take effect after Cursor reloads its MCP servers. Either:

* Restart Cursor, **or**
* Open the MCP settings panel in Cursor and reload servers.

## Verifying it's wired up

In Cursor, the MCP tools panel should list Percio tools (names depend on your server version), such as persona and scenario helpers and test-run tools.

If they don't appear, see [Troubleshooting](/agent/troubleshooting).

## First prompt to try

Once the tools show up, try asking Cursor:

> "Can you run a usability test on my sign-up flow at `http://localhost:3000/signup`? I want to test it as a first-time visitor."

Cursor will use the listed tools to pick or create a persona, shape the scenario with you, and run the test.

## Using with other MCP clients

The same pattern works for Claude Desktop and other **stdio** MCP clients: **`command`** `npx`, **`args`** `-y` and `@percio/mcp`, and **`env.PERCIO_API_KEY`** for your key (or rely on `percio login` credentials when omitting `env`).

## What's next

* [MCP tools](/agent/mcp-tools/list-personas)
* [Troubleshooting](/agent/troubleshooting)