MCP reference
VisualQ Quality MCP — prompts, tool profiles, transport modes, scopes, and key tools for coding agents.
VisualQ exposes 100+ MCP tools through @visualq/mcp and the hosted gateway at https://visualq.ai/api/mcp.
New to agents? Start with Quick start for agents.
Pair with Playwright MCP
| MCP | Use for |
|---|---|
| Playwright MCP | Local browser exploration — click, fill, snapshot |
| VisualQ MCP | Persistent baselines, FRT contracts, rolling health, gate_pr_quality |
Your agent uses Playwright to explore and VisualQ to enforce standards.
MCP prompts (one-click workflows)
Built-in prompts orchestrate multi-tool flows:
| 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 |
Invoke in chat: Run prompt pr-quality-gate for project acme-shop on staging.
Key tools
| Tool | Purpose |
|---|---|
gate_pr_quality | Structured PR gate — returns blockMerge (uses opt-in project gates from Settings → Quality gates) |
run_vrt / wait_for_run | Trigger VRT and poll completion |
get_run_failures / explain_vrt_failure | Failure analysis |
run_frt_feature | Execute FRT from IDE |
get_site_health | Rolling quality + coverage (not latest run) |
frt_propose_journey | AI-proposed Gherkin from a goal |
check_setup_health | Missing baselines, env config, blockers |
get_org_audit_logs | Governance trail (Business+) |
Full catalog: MCP tools
Tool profiles
Reduce noise with VISUALQ_TOOL_PROFILE in MCP env:
| Profile | Use when… |
|---|---|
vrt-qa | Pre-merge visual checks (default) |
frt-qa | Gherkin / functional journeys |
tracking-qa | Analytics plan audits |
full | All tools (power users) |
Quality gates (opt-in)
gate_pr_quality reads qualityGates from the project document when present. Projects without saved gates return blockMerge: false unless you pass explicit MCP inputs (includeVrt, includeA11y, etc.).
Configure thresholds per pillar under Project settings → Quality gates. See Project quality gates.
Authentication & scopes
Create keys under Settings → Agent API Keys.
| 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 | Read MCP | Write MCP | CI runs |
|---|---|---|---|
mcp_read | yes | no | no |
mcp_full | yes | yes | yes |
Write tools require confirm: true and scope mcp_full. Hobby plan or above for writes.
Transport modes
| Mode | How | Best for |
|---|---|---|
| stdio | npx @visualq/mcp in mcp.json | Cursor, Claude Desktop (local) |
| Hosted URL | https://visualq.ai/api/mcp + X-API-Key header | No Node.js, remote agents |
| Invoke API | POST /api/mcp/v1/invoke | Custom agents, CI scripts |
Hosted gateway exposes tool discovery via GET /api/mcp. See MCP response contract for the ok / summary / data / viewerUrl shape.
MCP resources
Resources expose read-only context (project list, scenario catalog, health snapshot) without a tool call. Your agent can attach them when planning QA work.
Skills (Cursor plugin)
The Cursor plugin ships skills that teach agents how to use VisualQ:
| Skill | Triggers on… |
|---|---|
visualq-agent | General VisualQ / QA / PR gate |
vrt-qa | VRT, baselines, screenshot diffs |
frt-qa | FRT, Gherkin, user journeys |
tracking-qa | Tracking, GTM, event coverage |
Invoke: /visualq-agent or mention “use VisualQ skill”.
NPM packages
| Package | Role |
|---|---|
@visualq/mcp | MCP server |
@visualq/setup-agent | CLI installer |
@visualq/agent-skills | Skill sources |
Source: github.com/abecms/visualq-mcp
Related
- Agent workflows — step-by-step tutorials
- Agent setup (all paths) — plugin, marketplace, deeplink
- Agent API keys — org keys in depth
- Coach Agent API — invoke Coach from automation