MCP Tools

Reference for all tools in @visualq/mcp and the hosted gateway. Install and configure the server in MCP integration.

Health / discovery

GET /api/mcp/v1/health
GET /api/mcp
GET /api/mcp/v1/openapi.json

No authentication required for health and OpenAPI. The hosted gateway (GET /api/mcp) returns the full tool catalog for remote agents.

{
  "ok": true,
  "service": "visualq-mcp",
  "version": "v2",
  "invokeTools": ["list_scenarios", "get_run_failures", "..."]
}

Invoke endpoint

POST /api/mcp/v1/invoke
X-API-Key: vq_org_live_…   # org agent key (IDE)
X-API-Key: vq_live_…       # project key (CI or single-project MCP)
Content-Type: application/json

{ "tool": "get_run_failures", "args": { "project": "my-client", "environment": "staging" } }

With an org agent key, pass "project": "slug" on most tools unless the key has a defaultProject or you set VISUALQ_DEFAULT_PROJECT in the MCP env. See Agent API keys.

Remote-first clients may also call POST https://visualq.ai/api/mcp with the same body and X-API-Key header.

Responses follow the MCP response contract.

Error codes

HTTP	`error.code`	Meaning
400	`validation_error`	Invalid arguments
400	`confirm_required`	Write tool called without `confirm: true`
403	`scope_denied`	API key scope too narrow
403	`plan_gate`	Tool not allowed on current plan
404	`not_found`	Unknown tool name
422	`tool_error`	Tool ran but business logic failed
429	`rate_limit`	Rate limit exceeded; see `retryAfterMs`

Rate limits

60 invoke calls per minute per API key
HTTP 429 with retryAfterMs and Retry-After header when exceeded
CI endpoints (/api/ci/*) use separate limits — see CI endpoints

Phase 1 — Core VRT & health

Tool	Via	Description
`list_projects`	CI API	Projects accessible with the API key
`list_scenarios`	invoke	Scenario labels, URLs, and viewports
`run_vrt`	CI API	Start VRT comparison against baselines
`run_baseline`	CI API	Capture new baselines
`run_perf` / `run_seo` / `run_a11y` / `run_security` / `run_tracking`	CI API	Pillar audits
`get_run_status`	CI API	Run status and summary (`runId` required)
`wait_for_run`	MCP client	Poll `get_run_status` until complete
`get_run_failures`	invoke	Batch failures with mismatch %
`get_diff_stats`	invoke	Drill-down for one scenario + viewport
`get_quality_score`	invoke	Composite score from rolling page health
`get_site_health`	invoke	Site rollup with coverage and pillar scores
`get_page_health`	invoke	Rolling health for one page/scenario
`get_job_status`	invoke	Poll async jobs
`list_my_tools`	invoke	MCP catalog for this key and plan

Org agent tools

Available with org agent keys (vq_org_live_…) — require project unless a default is configured:

Tool	Mutating	Description
`create_project`	yes	Create a project + default Production environment
`get_project`	no	Project metadata, modules, scenario count
`list_environments`	no	Environments for the project

create_project requires scope mcp_full and confirm: true.

Common parameters

Parameter	Used by	Description
`project`	most	Project slug or ID (required with org agent keys unless default is set)
`environment`	run/failure tools	Environment slug or ID
`runId`	status, failures, approve	Defaults to latest completed run when omitted
`scenarioLabel`	diff, explain, rules	Human-readable scenario label
`viewport`	diff, explain	`phone`, `tablet`, or `desktop`
`scenarios`	run_vrt, approve	Filter to specific scenario labels
`browsers`	run_vrt, run_baseline	Browser filter
`maxWaitMs`	wait_for_run	Client poll timeout
`confirm`	write tools	Must be `true` for mutating invoke tools

Phase 2 — Analysis & platform (invoke)

Tool	Description
`get_run_history`	Recent VRT and audit runs
`get_scenario_details`	Full configuration for one scenario
`compare_runs`	Delta between two runs
`check_setup_health`	Setup blockers before audits
`explain_vrt_failure`	Structured failure analysis
`inspect_page_dom`	DOM map from baseline or Firecrawl
`find_element_on_page`	Resolve selector from description
`get_run_report`	Slim run report for agents
`perf_get_latest_report` / `perf_list_history`	Performance reports and history
`seo_get_report` / `seo_list_history`	SEO reports and history
`a11y_get_report` / `a11y_list_history`	Accessibility reports and history
`security_get_report` / `security_list_history`	Security reports and history
`tracking_get_plan`	Full analytics tracking plan + FRT linking hints
`tracking_get_page`	One plan page with datalayer attributes + VRT scenarios
`tracking_get_event`	One plan event with event attributes + FRT links
`tracking_list_pages`	Page list with scenario/attribute counts
`tracking_list_events`	Event list with FRT coverage flags
`tracking_list_page_attributes`	Datalayer variable matrix (`pageId` optional filter)
`tracking_list_event_attributes`	Event-variable matrix (`eventId` optional filter)
`tracking_get_audit_report`	Latest tracking audit bilan
`tracking_get_audit_event_proof`	Per-event proof: report link, FRT scenario, variable table (plan / Piano / expected / received)
`tracking_prove_jira_ticket`	JIRA ticket → semantic intent, async tracking audit, `proofVerdict` + `jiraMarkdown` (poll `get_job_status`)
`tracking_export_audit_report`	Export audit report (xlsx/html/pdf)
`recommend_next_action`	Highest-value next action
`prioritize_issues`	Rank open issues by impact
`generate_action_plan`	Structured remediation plan
`identify_blockers_for_release`	Release blockers from health and runs
`analyze_user_intent`	Classify user intent for routing
`suggest_quick_scenarios`	Quick scenario suggestions
`suggest_scenario`	Suggest VRT scenario from URL
`get_page_groups`	Page group organization
`frt_get_feature_groups`	FRT feature folder organization (includes step summaries)
`frt_find_scenarios`	Search existing FRT features by ticket, name, or step text — call before `create_frt_scenario`
`crawl_site`	Crawl URLs via Firecrawl (async → `get_job_status`)
`generate_scenarios`	Generate scenarios from URLs (async)
`analyze_results`	AI analysis of VRT diff results
`frt_search_step_library` … `frt_explore_site`	FRT authoring (28 tools)
`agent_start_recording` / `agent_recording_turn` / `agent_finish_recording`	Headless NL recorder

Rolling health: use get_site_health / get_quality_score for project KPIs. Never treat a single latest run as the site score.

Phase 3 — Write (invoke)

All phase 3 tools are mutating. They require:

API key scope mcp_full
Organization plan Hobby or above
confirm: true in arguments

Tool	Required args	Description
`approve_vrt_results`	`scenarios`, `confirm`	Promote failed results to baselines
`create_scenario`	`label`, `url`, `confirm`	Persist a VRT scenario (counts toward plan `create_scenario` quota)
`create_comparison_rule`	`scenarioLabel`, `selector`, `mode`, `confirm`	Ignore/dynamic/layout rule
`create_content_rule`	`scenarioLabel`, `selector`, `normalize`, `confirm`	Content normalization rule
`run_frt_feature`	`featureId`, `confirm`	Run an FRT feature suite
`create_frt_scenario`	`goal`, `confirm`	Create FRT scenario from NL goal (resolve-first; Gherkin always EN)
`frt_organize_feature_groups`	`groups`, `confirm`	Organize FRT features into folders
`frt_save_feature_draft`	`featureId`, `confirm`	Persist FRT feature draft
`frt_create_step_def` … `frt_set_gherkin_bulk`	varies + `confirm`	FRT step/scenario authoring
`post_pr_comment`	`prNumber`, `confirm`	Post VisualQ summary on a GitHub PR
`tracking_set_page_attribute`	`pageId`, `name`, `expected`, `confirm`	Set datalayer attribute on a page
`tracking_delete_page_attribute`	`pageId`, `name`, `confirm`	Remove datalayer attribute from a page
`tracking_set_event_attribute`	`eventId`, `name`, `expected`, `confirm`	Set event-variable on an event
`tracking_delete_event_attribute`	`eventId`, `name`, `confirm`	Remove event-variable from an event
`tracking_upsert_page`	`id`, `label`, `pageType`, `confirm`	Create or update a plan page
`tracking_delete_page`	`pageId`, `confirm`	Delete a plan page
`tracking_upsert_event`	`id`, `label`, `eventType`, `confirm`	Create or update a plan event
`tracking_delete_event`	`eventId`, `confirm`	Delete a plan event
`tracking_link_page_scenario`	`pageId`, `scenarioId`, `confirm`	Link page to VRT scenario id
`tracking_unlink_page_scenario`	`pageId`, `scenarioId`, `confirm`	Unlink VRT scenario from page
`tracking_link_event_frt`	`eventId`, `featureId`, `stepIndex`, `stepText`, `confirm`	Link event to FRT step
`tracking_unlink_event_frt`	`eventId`, `featureId`, `confirm`	Remove FRT link from event
`tracking_update_plan`	`fields`, `reason`, `confirm`	Bulk replace plan sections
`agent_start_recording` / `agent_finish_recording`	`confirm`	Headless recorder session

`create_comparison_rule` modes

`mode`	Effect
`full`	Standard pixel comparison
`layout_only`	Layout only
`ignore`	Exclude region
`dynamic`	Tolerate changes in region

Example — create VRT scenario (after `suggest_scenario`)

{
  "tool": "create_scenario",
  "args": {
    "label": "Homepage",
    "url": "https://example.com/",
    "selectors": ["document"],
    "delay": 6000,
    "misMatchThreshold": 2,
    "captureBaseline": true,
    "confirm": true
  }
}

Typical agent flow: suggest_scenario → create_scenario → wait_for_run (if baselineRunId returned) or run_baseline.

Example — approve failures

{
  "tool": "approve_vrt_results",
  "args": {
    "environment": "staging",
    "runId": "abc123",
    "scenarios": ["Homepage", "Checkout"],
    "viewports": ["desktop"],
    "confirm": true
  }
}

Async jobs

Long-running tools return { jobId, status: "queued" }. Poll with:

{ "tool": "get_job_status", "args": { "jobId": "…" } }

Async tools include crawl_site, generate_scenarios, frt_propose_journey, and frt_explore_site.

MCP resources

Registered on @visualq/mcp (stdio/HTTP) and readable without explicit invoke:

URI	Backing tool
`visualq://latest-failures`	`get_run_failures`
`visualq://quality-score`	`get_quality_score`
`visualq://site-health`	`get_site_health`
`visualq://scenarios`	`list_scenarios`

MCP prompts

Name	Purpose
`diagnose-vrt-failure`	Guided failure diagnosis
`pre-merge-check`	VRT pre-merge and blockers
`setup-health-review`	Setup + rolling health review

Tool manifest

Authoritative schema: tools-manifest.json in visualq-mcp (98 tools as of @visualq/mcp@0.6.1). Regenerate from the backend:

cd visualq && npm run mcp:export-manifest

Install

See MCP integration.

On this page