Agent setup & tutorials

This guide walks you through installing the VisualQ agent and using it in daily QA workflows. For a structured entry point, start with Quick start for agents and the Agents chapter. For the full MCP reference, see MCP integration.

What you get

Step 1 — Create an org agent key

1. Sign in at visualq.ai
2. Go to Settings → Agent API Keys (org admin)
3. Click New agent key
   • Scope: mcp_full (read + write)
   • Optional: default project slug if you mainly work on one site
4. Copy the key (vq_org_live_…) — shown once

Full install wizard: Agent API Keys → Install guide

Step 2 — Choose an install path

Path A — One-command CLI (fastest)

npx @visualq/setup-agent cursor --key vq_org_live_YOUR_KEY --project my-site

Optional flags: --profile vrt-qa|frt-qa|tracking-qa|full, --base-url https://visualq.ai

Restart your IDE.

Path B — Cursor plugin (skills bundled)

Public repo: github.com/abecms/visualq-cursor-plugin

Local test before marketplace:

git clone https://github.com/abecms/visualq-cursor-plugin.git
cp -R visualq-cursor-plugin ~/.cursor/plugins/local/visualq
# Edit ~/.cursor/plugins/local/visualq/mcp.json — paste your key
# Cursor → Developer: Reload Window

Claude Code:

/plugin install github:abecms/visualq-cursor-plugin

Configure userConfig.apiKey when prompted.

Path C — Dashboard deeplink

1. Create a key (Step 1)
2. Click Open in Cursor in the key dialog
3. Paste your agent key when Cursor asks
4. Restart Cursor

Path D — Manual MCP JSON

Add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "visualq": {
      "command": "npx",
      "args": ["-y", "@visualq/mcp"],
      "env": {
        "VISUALQ_API_KEY": "vq_org_live_YOUR_KEY",
        "VISUALQ_BASE_URL": "https://visualq.ai",
        "VISUALQ_TOOL_PROFILE": "vrt-qa"
      }
    }
  }
}

No Node.js? Use hosted mode:

{
  "mcpServers": {
    "visualq": {
      "url": "https://visualq.ai/api/mcp",
      "headers": { "X-API-Key": "vq_org_live_YOUR_KEY" }
    }
  }
}

Step 3 — Verify the connection

In Cursor Agent chat (not Ask-only mode):

List VisualQ scenarios for project my-site and run check_setup_health.

You should see MCP tool calls and structured JSON responses — not “I don't have access”.

Quick checks:

Tutorial 1 — Pre-merge PR gate

Goal: Decide if a PR can merge based on VRT + FRT + rolling health.

1. Use MCP prompt pr-quality-gate, or say:

   Run prompt pr-quality-gate for project acme-shop on staging.

2. The agent calls gate_pr_quality and returns blockMerge: true/false.

3. If blocked:

   • VRT: get_run_failures → explain_vrt_failure
   • FRT: frt_explain_failure
   • Re-run after fixes: run_vrt with confirm: true

4. Open viewerUrl in the response to see diffs in the dashboard.

Tutorial 2 — Run VRT from the IDE

Run VRT on staging for project acme-shop, wait for completion, and list failures with mismatch %.

Agent workflow:

1. run_vrt (confirm: true, environment: staging, project: acme-shop)
2. wait_for_run
3. get_run_failures
4. Optional: explain_vrt_failure on the worst scenario

Tutorial 3 — Create an FRT journey from plain language

Use prompt frt-journey-from-goal or:

Create an FRT test: user logs in, adds a product to cart, and reaches checkout.
Start URL: https://staging.example.com/
Project: acme-shop

Agent workflow:

1. frt_search_step_library
2. frt_propose_journey → poll get_job_status
3. frt_save_feature_draft (confirm: true)
4. frt_compile_feature
5. run_frt_feature (confirm: true)

Set VISUALQ_TOOL_PROFILE=frt-qa for a focused toolset.

Tutorial 4 — Onboard a new client site

Use prompt onboard-new-site:

Onboard https://new-client.com/ in VisualQ — crawl, baselines, and one critical FRT flow.

Steps the agent follows: create_project → crawl_site → generate_scenarios → run_baseline → frt_propose_journey → check_setup_health.

Tutorial 5 — Jira ticket coverage

Use prompt jira-qa:

Cover JIRA ticket PROJ-456 for project acme-shop: acceptance criteria are login + order history visible.

Agent creates/updates VRT or FRT coverage, runs tests, and summarizes with gate_pr_quality.

Tool profiles

Reduce MCP noise with VISUALQ_TOOL_PROFILE:

Skills included in the plugin

Invoke explicitly: /visualq-agent or mention “use VisualQ skill” in chat.

Troubleshooting

Related

• MCP reference — architecture, scopes, rate limits
• MCP tools — full catalog
• Maestro MCP — native mobile complement
• Plugin repo — skills, rules, marketplace