Agents & MCP

VisualQ as the Quality MCP for Cursor, Claude Code, and coding agents — VRT, FRT, rolling health, and PR gates from your IDE.

VisualQ is built for agentification: your coding agent can run visual regression tests, functional journeys, accessibility audits, and PR quality gates — without leaving Cursor or Claude Code.

This chapter is the entry point for IDE agents. Human dashboard workflows stay in Getting started; CI pipelines stay in CI/CD.

Why a Quality MCP?

Most agents can browse locally with Playwright MCP. That is great for exploration, but it does not give you:

Approved baselines and diff history across viewports
Rolling site health (never confuse one run with a project score)
FRT contracts — Gherkin features compiled to deterministic Playwright
gate_pr_quality — a structured merge verdict for PRs

VisualQ MCP fills that gap. Install it alongside Playwright MCP:

Layer	MCP	Role
Explore	Playwright MCP	Click, fill, inspect DOM locally
Standards	VisualQ MCP (`@visualq/mcp`)	VRT, FRT, health, tracking, PR gate

What you install

Component	Package / source	Purpose
MCP server	`@visualq/mcp`	100+ tools — runs, health, FRT, governance
Setup CLI	`@visualq/setup-agent`	One-command MCP + skills + rules
Cursor plugin	visualq-cursor-plugin	Skills, rule, MCP template
Org agent key	Dashboard → Agent API Keys	`vq_org_live_…` — all projects in your org

Use org agent keys for IDE agents. Project CI keys (vq_live_…) are for GitHub Actions and REST CI routes only.

Architecture

flowchart LR
  subgraph IDE["Cursor / Claude Code"]
    Agent["Coding agent"]
  end
  subgraph MCP["MCP layer"]
    PW["Playwright MCP\n(local browser)"]
    VQ["@visualq/mcp\n(quality standards)"]
  end
  subgraph Cloud["visualq.ai"]
    API["MCP gateway + invoke API"]
    Worker["Playwright worker"]
    FS["Firestore\nbaselines · health · FRT"]
  end
  Agent --> PW
  Agent --> VQ
  VQ --> API
  API --> Worker
  API --> FS

Start here

Quick start for agents — key, install, verify in 5 minutes
MCP reference — prompts, tool profiles, transport modes
Agent workflows — PR gate, VRT, FRT, onboarding, Jira

Deep dives

Agent API keys — scopes, org vs project keys
MCP tools catalog — full tool list
MCP response contract — ok, summary, viewerUrl
Agent setup (all install paths) — plugin, deeplink, manual JSON
Cursor marketplace — publish and install the plugin
Maestro MCP — native mobile complement (POC)

Rolling health rule for agents

Agents must use get_site_health or gate_pr_quality for project KPIs. Never treat latestA11yRun or a single VRT run as the site score. See Rolling page health.