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. 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): 
{
  "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: 
{
  "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.

​
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