MCP guides

Testing authenticated localhost apps

When your app runs on http://localhost:* (or private dev hosts) and requires a logged-in session.

Prerequisites

1. Global Cursor MCP config
2. One-time sitelens_setup (bundled Chromium)
3. Your dev server running

Example: login then dashboard QA

1. Capture session — sitelens_auth_start on http://localhost:3000/login with profile my-app, then sitelens_auth_save.

2. Run QA — sitelens_qa_run on http://localhost:3000/app/dashboard with authProfile my-app.

{
  "url": "http://localhost:3000/app/dashboard",
  "authProfile": "my-app",
  "readySelector": "[data-testid='dashboard-root']",
  "scenario": [{ "type": "waitForText", "text": "Welcome" }]
}

scenario is an alias for actions (same safe step vocabulary, max 8 steps for ad-hoc QA).

Workspace-default profile

Omit authProfile to use the workspace folder name as the profile. Or set in project .sitelens/config.json:

{
  "auth": {
    "mode": "storage-state",
    "profileName": "my-app"
  }
}

Session expired

If QA lands on /login, interpretationNotes will warn — re-run sitelens_auth_start → sitelens_auth_save.

No cloud API required unless you also use cloud tools (SITELENS_MODE=all).