Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Integrations / MCP server(24 of 37)

MCP server

CLOUD API URL REQUIRED. There is no working hosted default or supported production self-host quick start. Use cloud-dependent source only with a deployment you operate and have independently verified.

@frontguard/mcp gives coding agents structured access to local visual regression reports, diff clusters and static CSS patch checks. Reading local reports needs no cloud account or API key.

Frontguard MCP Agentic Visual Cortex Architecture
FIG 01 · @FRONTGUARD/MCP — SIX READ TOOLS OVER STDIO JSON-RPC (LOCAL REPORT & CLOUD API MODES)

Configuration

From your project directory, start the app and prepare reviewed baselines first. JSON output goes to stdout, so create the report directory and redirect it into the file MCP will read:

terminal: create the local JSON report
mkdir -p frontguard-report
npx -p @frontguard/cli frontguard run --output json > frontguard-report/report.json

Exit 1 means the report contains regressions or unaccepted screenshots; exit 2 indicates an error to investigate. Run the MCP client from this project directory, or use an absolute FRONTGUARD_LOCAL_REPORT path.

.mcp.json: local report setup
{
  "mcpServers": {
    "frontguard": {
      "command": "npx",
      "args": ["-y", "@frontguard/mcp"],
      "env": {
        "FRONTGUARD_LOCAL_REPORT": "./frontguard-report/report.json"
      }
    }
  }
}

Cloud-dependent tools require an independently verified FRONTGUARD_API_URL deployment and FRONTGUARD_API_KEY; no working hosted default is supplied. The package ships an MCP Registry server.json manifest under io.github.ravidsrk/frontguard and negotiates both 2025-11-25 and 2026-07-28 MCP protocol versions.

Tools

MCP Tool NameRequired ArgumentsWhat It Returns to the Coding Agent
list_regressionspr_id; optional repo, limit, cursorLists regressions worst first, each with a diffId and a clusterCount, 25 per page by default (max 200). Use a PR number, a run ID returned by recent_runs, or "latest" for the newest run (the report's run in local-report mode). Pass nextCursor back as cursor for the next page.
inspect_diff_cluster_domdiff_id; optional cluster_idReturns the diff clusters with bounding boxes and recorded target selectors, plus the classification, explanation and suggested fix.
get_suggested_fixdiff_idReturns a stored suggested fix if one exists. Fixes exist only when the run had an ai provider and generateFixes: true.
verify_css_patchdiff_id, css_patch, target_selectorStatically checks CSS syntax, a deny list, and whether target_selector matches a selector recorded for the diff. It renders nothing and does not apply the patch: staticCheck pass comes with rendered: false.
promote_baselinerun_id, confirm_reviewed: true; optional routesWrite tool, registered only with FRONTGUARD_MCP_WRITES=1; agents should not call it. Cloud API mode only: records whole-run approval through the same endpoint as accept_baseline and promotes no screenshots. routes must include every changed route. Refuses local-report mode.
accept_baselinerun_id, confirm_all_regressions_reviewed: trueWrite tool, registered only with FRONTGUARD_MCP_WRITES=1. Records whole-run approval metadata in the local JSON report or Cloud API; does not replace screenshot baselines.
recent_runsoptional repo, branch, limitLists runs, including the local run ID when reading a JSON report.
list_horizontal_overflowoptional run_id, flagged_only, limit, cursorLists horizontal overflow from the JSON report, largest overflow first, 25 per page by default (max 200). A flagged row is a visible unclipped box past the right edge; only flagged rows are returned unless flagged_only is false. It does not change the pixel result.

Agentic debugging workflow

STEP 01Write the report
Use the JSON command above. Recreate report.json after each comparison so MCP reads the current evidence.
STEP 02Inspect regressions
Call list_regressions with {"pr_id": "latest"} for the newest run, or with a run ID from recent_runs. Rows come worst first; pass nextCursor back as cursor for more. Pass a returned diffId as the diff_id input to inspect_diff_cluster_dom or get_suggested_fix.
STEP 03Check and re-run
Call verify_css_patch with diff_id, css_patch and target_selector. It is a static check and renders nothing. When staticCheck is pass, apply the reviewed code edit yourself and re-run Frontguard to confirm the pixels.

Approval limit

promote_baseline and accept_baseline are registered only when FRONTGUARD_MCP_WRITES=1, and agents should not call them. MCP promotion is refused in local-report mode and does not write the frontguard-baselines branch. The local write is the CLI command frontguard update-baselines --confirm-baselines, which a human runs. An agent setting confirm_reviewed: true on itself is not a human review, and an advisory caption cannot set that flag. Cloud approveRun is not a production path; do not point the MCP client at a production host. accept_baseline can mark a JSON report approved, but it does not replace screenshot baselines. Cloud tools record approval metadata only; cloud screenshot promotion is not implemented.