Docs

Step 1: Copy the hosted MCP URL:

https://www.runnerqa.dev/api/mcp/mcp

Step 2: Add it to Claude Code (or any MCP client that supports remote servers with OAuth):

claude mcp add --transport http runnerqa https://www.runnerqa.dev/api/mcp/mcp

Step 3: Sign in with RunnerQA OAuth when prompted and approve the scopes on the consent screen.

Step 4: Have the agent call runnerqa_connection_status first — the first-call truth check. Confirm the authenticated account (email) and the granted scopes before reading or creating anything, then ask it to inspect your projects or create tests.

The hosted MCP manages projects, test cases, run evidence, analysis, and approved fixes. It never drives your simulator — tests execute locally through the CLI (section 2), and applying a fix always requires your explicit approval.

Maestro CLI (test runner):

curl -Ls "https://get.maestro.mobile.dev" | bash

Maestro is an open-source mobile UI testing framework. It requires an iOS simulator or Android emulator. RunnerQA is powered by Maestro for execution — it adds the catalog, evidence, history, and approvals around it.

RunnerQA CLI (result reporter):

npm install -g runnerqa@0.1.8

This installs the mqa command (current beta: runnerqa@0.1.8). The CLI pulls tests from your catalog and reports the run evidence back.

Connect and set up — run these from the root of your mobile app's repository (not the RunnerQA repo, your home folder, or an arbitrary directory). Create a runner token in Settings first, then:

mqa connect https://www.runnerqa.dev <runner-token>
mqa setup --agent claude --yes    # installs the Verify skill for Claude Code
mqa doctor --json                 # checks local execution readiness (JSON)

mqa setup is the recommended Claude Code setup — no hand-written JSON config needed. mqa doctor is read-only: it checks Node, config, the runner token, Maestro, and simulator/device readiness, and exits non-zero only on a blockingfailure. A missing tool for a platform you're not targeting (e.g. no adb on an iOS-only run) is a warning, not a blocker.

Diagnose and manage the setup:

mqa doctor                  # human-readable readiness report
mqa doctor --json           # same checks, machine-readable
mqa agent install claude    # install/update the Verify skill on its own
mqa agent status            # show the Verify skill install state
mqa status                  # show CLI connection status

Pull and run:

mqa pull                    # Download your tests
mqa run <test_case_id>      # Run a single test
mqa run-all                 # Run all tests

Every run reports status and logs automatically, with per-step timings and the UI hierarchy attached when the local run produces them.

A real session, condensed:

You:    "Create a smoke test for the premium paywall."
Agent:  runnerqa_list_projects        → picks your app
Agent:  runnerqa_create_test_case     → "Premium Paywall Flow"
Agent:  runnerqa_generate_yaml        → validated Maestro-compatible test
You:    mqa pull && mqa run <id>      → run fails (49.2s)
Agent:  runnerqa_analyze_failure      → real ids from the UI snapshot
Agent:  "Here's the proposed fix — apply it?"
You:    "Yes."
Agent:  runnerqa_apply_fix            → new version saved, old kept in history
You:    mqa pull && mqa run <id>      → passes (29.3s)
Agent:  runnerqa_get_report_summary   → failing_tests: 0

Timings are from a local Petipedia dogfood run — a real example, not a benchmark.

Create an agent token on the AI Integrations page (Advanced section), then add to your MCP client config:

{
  "mcpServers": {
    "runnerqa": {
      "command": "npx",
      "args": ["-y", "runnerqa-mcp"],
      "env": {
        "RUNNERQA_AGENT_TOKEN": "rqa_agent_xxx",
        "RUNNERQA_BASE_URL": "https://www.runnerqa.dev"
      }
    }
  }
}

Same tools, same safety model as hosted MCP — the difference is transport (stdio) and authentication (token instead of OAuth).

Create an agent token on the AI Integrations page and pass it as a bearer header:

Authorization: Bearer rqa_agent_...

These endpoints cover the loop:

GET  /api/agent/projects          # list projects
GET  /api/agent/test-cases        # list test cases (?project_id= optional)
POST /api/agent/test-cases        # create a test case (project_id, name, description)
GET  /api/agent/test-cases/:id    # test case detail with YAML + run commands
POST /api/agent/generate-yaml     # generate the Maestro-compatible test (test_case_id)
GET  /api/agent/runs              # recent runs (?test_case_id= optional)
GET  /api/agent/runs/:id          # run detail with logs + failure analysis
POST /api/agent/runs/:id/analyze  # failure analysis (stores result on the run)
POST /api/agent/test-cases/:id/apply-fix  # apply a validated fix (requires your approval flow)
GET  /api/agent/report-summary    # QA report: totals, failing tests, next steps

Rate limit: 30 requests/minute per token. Full curl examples are on the AI Integrations page.

Broad regex selectors like ".*Get Premium.*" work, but Maestro can spend a long time matching them. An accessibility identifier is both faster and immune to copy changes.

1. Add an identifier in your app (SwiftUI):

.accessibilityIdentifier("premium_banner")

2. Target it in Maestro:

- tapOn:
    id: "premium_banner"

No identifier? Prefer the exact visible text. If the text is embedded in a longer label, use a narrow regex anchored to the stable part — ".*Get Premium" matches faster than ".*Get Premium.*".