Quick start for agents

Connect VisualQ MCP to Cursor or Claude Code in 5 minutes — org key, install, verify, first PR gate.

Get VisualQ working in your IDE agent in under 5 minutes. No dashboard clicking required after setup.

1. Create an org agent key

Sign in at visualq.ai
Open Settings → Agent API Keys (org admin)
Click New agent key
- Scope: mcp_full (read + write)
- Optional: set a default project slug if you mainly work on one site
Copy the key (vq_org_live_…) — shown once

Full wizard: Agent API Keys → Install guide

2. Install MCP (pick one path)

Fastest — setup CLI

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

Target	Command
Cursor (user)	`… cursor --key …`
Claude Code	`… claude --key …`
Project repo	`… manual --key …`

Optional: --profile vrt-qa|frt-qa|tracking-qa|full

Dashboard deeplink

Create a key (step 1)
Click Open in Cursor in the key dialog
Paste your agent key when prompted
Restart Cursor

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" }
    }
  }
}

Restart your IDE after any install path.

3. Verify the connection

In Agent mode (not Ask-only), send:

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

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

You say…	Expected
`check_setup_health` for `my-site`	Setup blockers list
`get_site_health` for `my-site`	Rolling score + coverage
`list_scenarios`	VRT scenario labels

4. Run your first PR gate

Use the MCP prompt pr-quality-gate, or say:

Run prompt pr-quality-gate for project my-site on staging.

The agent calls gate_pr_quality and returns blockMerge: true/false with rolling health context. Open viewerUrl in the response to inspect diffs in the dashboard.

5. Next steps

Agent workflows — VRT, FRT, onboarding, Jira
MCP reference — prompts, profiles, transport
Cursor plugin + skills — bundled QA skills
MCP tools catalog — full tool list

Troubleshooting

Symptom	Fix
MCP server red / missing	Node 18+? Restart IDE. Key prefix must be `vq_org_live_`.
`project_resolution_error`	Pass `"project": "slug"` or set default project on the key.
`confirm_required`	Mutating tools need `confirm: true` — say “yes, confirm”.
`403 plan_gate`	Upgrade to Hobby+ for write tools.
Too many tools	Set `VISUALQ_TOOL_PROFILE=vrt-qa`.

On this page