MCP (Cursor & IDE)

VisualQ Quality MCP — 100+ tools for Cursor and Claude Code agents. Gate PRs, run VRT/FRT, rolling health.

VisualQ is the Quality MCP for coding agents. Install @visualq/mcp alongside Playwright MCP:

Playwright MCP — local browser exploration
VisualQ MCP — persistent baselines, FRT contracts, rolling health, gate_pr_quality

Start here: Quick start for agents — then Agent workflows and the full Agents chapter.

Use the VisualQ MCP server (@visualq/mcp) to trigger runs, wait for results, inspect structured failure reports, and — with the right API key — approve baselines or post PR comments without opening the dashboard.

MCP prompts (agent workflows)

Prompt	Purpose
`pr-quality-gate`	Merge verdict: VRT + FRT + rolling health
`setup-health-review`	Project setup blockers
`frt-journey-from-goal`	Plain-language → FRT feature
`onboard-new-site`	New project bootstrap
`jira-qa`	Ticket-driven coverage

Key tools

gate_pr_quality — structured PR gate for agents
run_frt_feature — FRT execution from IDE
get_site_health — rolling quality (never use a single run as site score)
get_org_audit_logs — governance trail (Business+)

Prerequisites

An org agent API key (vq_org_live_…) — recommended for Cursor and IDE agents. Create under Settings → Agent API Keys (org admin). See Agent API keys.
Or a project API key (vq_live_…) for single-project setups — Project → Settings → API keys (CI pipelines; not the primary IDE path)
Node.js 18+ (for npx stdio mode) — not required for hosted URL mode
Hobby plan or above for MCP write tools

Org agent keys (recommended)

One org key powers all projects from a single MCP entry. The dashboard generates copy-paste config, deeplink, and setup CLI command.

Key type	Prefix	MCP `project` arg	CI routes (`/api/ci/*`)
Org agent	`vq_org_live_…`	Required unless default project set	Not supported
Project	`vq_live_…`	Optional (inferred from key)	Supported with `ci` or `mcp_full` scope

Choose your install path

Path	Best for
Agent setup guide	Tutorials + all install options
Cursor plugin	Skills + MCP (GitHub)
`npx @visualq/setup-agent`	CLI install (MCP + skills + rules)
Dashboard deeplink	Open in Cursor from Agent API Keys
Manual `mcp.json`	Copy-paste from settings

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

Flags: --profile vrt-qa|frt-qa|tracking-qa|full, --base-url.

Cursor plugin + Claude Code

Cursor: visualq-cursor-plugin — marketplace or ~/.cursor/plugins/local/visualq
Claude Code: /plugin install github:abecms/visualq-cursor-plugin

Includes 4 skills, 1 rule, MCP template. Marketplace guide.

Cursor setup (stdio — org agent key)

{
  "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",
        "VISUALQ_DEFAULT_PROJECT": "your-project-slug"
      }
    }
  }
}

Restart Cursor. Server name: visualq.

Claude Code / Claude Desktop

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

Or use the same JSON as Cursor in your Claude MCP config.

Hosted gateway (no Node)

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

For org keys, stdio + VISUALQ_DEFAULT_PROJECT is the path documented in Settings.

Architecture

Route	Tools	Backend
Hosted gateway	Discovery + invoke	`GET/POST /api/mcp`
CI API	`run_vrt`, `get_run_status`, …	`POST /api/ci/*`
Invoke API	Read, write, FRT, health	`POST /api/mcp/v1/invoke`
Client	`wait_for_run`	Poll in MCP process

Tool profiles

Set VISUALQ_TOOL_PROFILE in MCP env:

Profile	~Tools	Use case
`vrt-qa`	22	Pre-merge VRT (default)
`frt-qa`	18	FRT journeys
`tracking-qa`	16	Analytics audits
`full`	100+	Power users

MCP resources

URI	Description
`visualq://latest-failures`	Latest VRT failures
`visualq://site-health`	Rolling health + coverage
`visualq://scenarios`	Scenario list

API key scopes

Org agent keys (`vq_org_live_…`)

Settings → Agent API Keys — scopes: mcp_read or mcp_full.

Project keys (`vq_live_…`)

Scope	MCP read	MCP write	CI runs
`ci`	no	no	yes
`mcp_read`	yes	no	no
`mcp_full`	yes	yes	yes

See Agent API keys and Project API keys.

Write tools require confirm: true and scope mcp_full.

Response format

Structured tool response: ok, summary, data, nextActions, optional viewerUrl (dashboard link).

Troubleshooting

Symptom	Fix
`project_resolution_error`	Pass `"project": "slug"` or set default on key / `VISUALQ_DEFAULT_PROJECT`
`confirm_required`	Add `"confirm": true` to mutating tools
`403` on `/api/ci/*` with org key	Expected — use project CI key in pipelines
MCP missing after install	Restart IDE; verify `vq_org_live_` key
Too many tools	Set `VISUALQ_TOOL_PROFILE=vrt-qa`

Packages & repos

NPM: @visualq/mcp, @visualq/setup-agent, @visualq/agent-skills
Plugin: github.com/abecms/visualq-cursor-plugin
MCP: github.com/abecms/visualq-mcp
Tools reference: MCP Tools
Coach Agent v2: Coach Agent API

On this page