testorax-mcp

Coding agents START new browser tests from here, not just read reports. MCP server for Testorax — gives Claude / Cursor / Codex / any MCP-compatible agent end-to-end control over the Testorax test loop: kick off a Fast Bug Scan, poll status, read the Compact Proof, run Fix Check, and verify the patch landed.

What this MCP can do (read this first)

testorax-mcp is not a read-only reporter. The agent can drive the full test loop:

| What | Tool | |------|------| | Start a new Fast Bug Scan (real browser, clicks every safe control) | start_fast_bug_scan | | Start a Fast Bug Hunt (cheaper; stops on first high-confidence bug) | start_fast_bug_hunt | | Use the free trial credit on first scan | start_free_fast_bug_scan | | Walk a multi-step user journey (signup, login, checkout) | prepare_workflow_test | | Validate a Deep CRUD E2E config before paying | prepare_crud_e2e_config | | Re-run prior failures after a patch (Fix Check loop) | start_regression_check | | Watch a run live (status, current step, recent events) | get_live_run_status | | Read agent-readable proof — small (~3 KB), decision-ready | get_compact_proof | | Read full Proof Packet (~12 KB) with AI Fix Prompt | fetch_proof_packet | | List saved logins (Login Memory metadata only — no session material) | list_auth_sessions | | Revoke a saved login | revoke_auth_session | | Run an authenticated scan | pass authSessionId to start_fast_bug_scan |

The 5-step agent loop:

1. start_fast_bug_scan({ url, pagesLimit?: 10, scopedPaths?: ["/signup"] }) → returns runId
2. get_live_run_status({ runId }) — poll until isFinished:true
3. get_compact_proof({ runId }) — read verdict, failureType, runtimeEvidence, nextSafeAction
4. Apply minimal patch from the proof. Don't auto-patch from inconclusive or blocked verdicts.
5. After patching: trigger Fix Check via POST /api/runs/<runId>/fix-check — only verdict='fixed_verified' counts as a real fix.

Cold-start walkthrough for agents: https://testorax.com/docs/agent-quickstart.

Install

npm install -g testorax-mcp

Configure

The server reads two environment variables:

• TESTORAX_EMAIL (required) — the customer's account email
• TESTORAX_API (optional) — defaults to https://testorax.com

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "testorax": {
      "command": "npx",
      "args": ["-y", "testorax-mcp"],
      "env": {
        "TESTORAX_EMAIL": "[email protected]"
      }
    }
  }
}

Use with Cursor

Add to .cursor/mcp.json in your repo or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "testorax": {
      "command": "npx",
      "args": ["-y", "testorax-mcp"],
      "env": {
        "TESTORAX_EMAIL": "[email protected]"
      }
    }
  }
}

Full tool surface

Run lifecycle (these CREATE new runs):

| Tool | What it does | |------|--------------| | start_fast_bug_scan | Start a Fast Bug Scan. Args: url, pagesLimit?, scopedPaths?, viewport?, authSessionId?. | | start_fast_bug_hunt | Continuous Bug Hunt — cheaper, stops on first high-confidence bug. | | start_free_fast_bug_scan | Use the one-time free trial credit. | | prepare_workflow_test | Walk a full user journey end-to-end (multi-step). | | prepare_crud_e2e_config | Validate a Deep CRUD E2E config before paying. | | start_regression_check | Re-run failing scenarios from a prior runId — Fix Check loop. | | register_app | Register a deployed app to your account. |

Reading run state and proof:

| Tool | What it does | |------|--------------| | get_live_run_status | Status, current step, recent events (poll until isFinished:true). | | get_compact_proof | Small (~3 KB) agent-readable proof — read this FIRST after a run completes. | | fetch_proof_packet | Full Proof Packet (~12 KB) with aiFixPrompt. | | list_runs | List recent runs (filter by status). | | run_status | Legacy status endpoint. | | get_report | Full report JSON for a completed run. |

Login Memory (authenticated runs):

| Tool | What it does | |------|--------------| | list_auth_sessions | Metadata only — never returns cookies, headers, or tokens. | | get_auth_session | Single entry metadata. | | revoke_auth_session | Revoke a saved login (deletes the encrypted blob). |

There is no decrypt tool, no export tool. Saved-session contents never leave the test-run engine. Customers create saved logins themselves at /account/login-memory; agents reference them by id via authSessionId on start_fast_bug_scan.

Templates and helpers:

| Tool | What it does | |------|--------------| | list_test_templates | 24 ready-made workflow / CRUD templates. | | get_test_template | Inputs + safety notes for one template. | | validate_template_inputs | Pure shape check before paying. | | generate_template_prompt | Agent prompt prebuilt from the template. | | list_scenario_templates | 45 scenario templates (auth, CRUD, search, mobile, etc.). | | get_scenario_template | One template's required inputs + assertions. | | generate_scenario_from_template | Deterministic generator — refuses unsafe shapes. | | get_screenshot_recommendation | When to fetch a screenshot, marked vs latest. | | list_screenshots / get_screenshot / get_latest_screenshot / get_marked_screenshot | Auth-proxied screenshot fetch. | | chrome_capture_for_job | Local Chrome bridge for real-Chrome parity (operator-driven). |

Account / suites / variables:

| Tool | What it does | |------|--------------| | get_usage | Plan, monthly usage, wallet balance — call before start_* to know if it's free or charges. | | list_suites / run_suite | Saved suites (charges the saved tier price). | | list_variables / set_variable | Saved KV variables. | | list_repos | Registered GitHub repos. | | search_testorax_issues | Issue inbox (filter by source, status, severity). | | send_message / list_messages | Agent ↔ human messaging on a run. |

Safety notes

• start_fast_bug_scan and friends create real runs and may charge the wallet. Call get_usage first to see the cost.
• Authenticated runs use authSessionId (Login Memory). Never paste cookies, passwords, or session JSON into chat.
• aiFixPrompt: null on the Proof Packet means the deterministic generator declined to write a one-shot patch prompt — it does NOT mean no bug was observed. Always read runtimeEvidence directly.
• Only verdict='fixed_verified' from Fix Check counts as a real fix.
• Read-only tools never expose internal architecture, model names, prompts, or our cost structure.