Skip to main content
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. You don’t need to install anything globally. Create or edit .cursor/mcp.json in your project: 
{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["percio-mcp", "--api-key", "YOUR_PERCIO_API_KEY"]
    }
  }
}
Replace YOUR_PERCIO_API_KEY with the key from your Percio dashboard (Integrations → Agent integrations). 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 drop the --api-key: 
{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["percio-mcp"]
    }
  }
}
The MCP server will read ~/.config/percio/credentials.json automatically.

​
Project-scoped vs. user-scoped config

Cursor supports both:
  • Project-scoped — .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. Applies across all projects. Good 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:
  • list_personas
  • chat_scenario
  • chat_persona
  • create_persona
  • run_usability_test
If they don’t appear, see 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:
  1. Call list_personas to see what’s available.
  2. Ask you to pick one or offer to create a new persona via chat_persona + create_persona.
  3. Walk through chat_scenario with you to build a scenario — it will relay each question verbatim and wait for your answer.
  4. Confirm the scenario with you.
  5. Call run_usability_test with the chosen persona and scenario.

​
Using with other MCP clients

The percio-mcp command works with any MCP-capable client. Claude Desktop and other clients use the same configuration pattern — point the client at the npx percio-mcp command and pass your API key via --api-key or environment.

​
What’s next