HomeFeaturesDocumentationContactDownload
Browse the docs

AI editor setup overview

How SiteCMD's MCP server lets your AI editor read scan results, request fixes, and verify them.

If your AI editor speaks MCP (Model Context Protocol), it can talk to SiteCMD directly. Your AI sees your scan results, can pull fix prompts written specifically for the failing checks, and can request independent verification from SiteCMD after making changes.

This page covers what MCP is, what SiteCMD exposes through it, and the pieces that work the same across every supported editor. For per-editor setup commands, see the page for your editor:

What MCP is

Model Context Protocol is an open standard for letting AI tools talk to other tools. An MCP server exposes a set of named functions (called "tools"), each with a description and a parameter schema. The AI editor decides when to call which one based on what you're asking it to do.

Three things make this useful:

  1. The AI doesn't have to guess. When you say "fix the failing accessibility issues on this page," it can call get_issues to see the real list, not invent plausible-looking ones.
  2. You choose which editors can access SiteCMD. SiteCMD's MCP server runs locally under your account. Configuring it grants that editor access to the projects in your local SiteCMD database; the editor's own tool approvals control when it calls tools.
  3. The protocol is the same across tools. Configure your editor once, and the same MCP server works whether you switch editors next month.

SiteCMD ships an MCP server (sitecmd-mcp) as part of the desktop app. When configured, your editor spawns it as a subprocess and talks to it over stdio.

What you need first

Install SiteCMD and Node 22.22.1 or newer. For Claude Code, Codex, Cursor, and Windsurf, open SiteCMD, go to Integrations, and connect the editor. The app finds Node, checks that its built-in node:sqlite module works, copies the bundled server into persistent application data, and writes the config itself. If Node is missing or too old, the app explains what to install. A stale path or changed argument later shows as Repair.

For every other editor, or to wire one up by hand, you need two things:

  • Node 22.22.1 or newer on your PATH. The server reads SiteCMD's local database through Node's built-in node:sqlite module, and 22.22.1 is the first release whose node:sqlite passes the server's own test suite. Check with node --version.
  • The persistent server script. The desktop app copies sitecmd-mcp.mjs into its application-data folder each time it starts, so point your editor at that copy, never at the app bundle or installation directory (an AppImage mount disappears when the app closes):
OS Persistent MCP script
macOS ~/Library/Application Support/com.sitecmd.app/sitecmd-mcp/sitecmd-mcp.mjs
Linux $XDG_DATA_HOME/com.sitecmd.app/sitecmd-mcp/sitecmd-mcp.mjs when set; otherwise ~/.local/share/com.sitecmd.app/sitecmd-mcp/sitecmd-mcp.mjs
Windows %LOCALAPPDATA%\com.sitecmd.app\sitecmd-mcp\sitecmd-mcp.mjs; %APPDATA% is used when %LOCALAPPDATA% is unavailable

Replace the placeholders below with absolute paths before pasting into JSON or TOML, unless you are deliberately using variable syntax supported by your editor. Shell forms such as ~ are not portable across editor configurations.

Every setup example passes one argument before the script path: --disable-warning=ExperimentalWarning. Node prints an ExperimentalWarning for node:sqlite on every start, and some editors surface anything on stderr as an error. No other sqlite feature flag is needed on Node 22.22.1 or newer, and the app's own launcher does not pass one.

What SiteCMD exposes

The MCP server provides these tools to your AI editor:

Tool What it does
get_projects List every project tracked in SiteCMD, with URLs and detected frameworks.
get_scan_score Get the current SiteCMD Score, with source-specific scan data for diagnosis.
get_issues Page through compact summaries of active grouped findings. Filter by severity, category, and confidence. See the context guidance below.
get_issue Read one issue in full by check ID: the evidence and the fix prompt.
get_fix_prompts Return fix prompts for selected failing checks. These are written with enough context that the AI can act on them directly.
get_scan_history Return scan score history over time for a URL, useful for trend analysis.
get_dismissed_issues Return ignored or blocked issues and configuration suppressions so the AI can respect those decisions.
compare_scans Compare two Web Scans for a URL, defaulting to the most recent pair. It does not compare Code Scan reports.
run_scan Queue a desktop scan with scope: "web" (the default), "code", or "full". Use get_scan_status to follow the request.
get_scan_status Read the outcome of a run_scan request.
how_to_rescan Explain how to get a fresh scan when the AI should hand that back to you. request_scan is a deprecated alias of this tool.
start_fix Queue a fix attempt for an open issue. The running desktop app creates the attempt; use get_fix_status to follow the request.
get_fix_brief Read the full fix brief for a fix attempt: the issue, where to fix it in the repository, and the acceptance criteria.
get_fix_status Read the status of a fix attempt, or of a start_fix request that has not resolved to an attempt id yet.
request_verification Tell SiteCMD a fix attempt is complete so it can re-run the check and verify it. This does not mark the issue fixed; SiteCMD verifies independently.
list_fix_attempts List fix attempts that are currently open (briefed, verify-requested, or verifying).

That covers the core fix-loop tools. To target a particular source occurrence, pass its relative_path and line to start_fix (including a null line when applicable). A path without a line must select exactly one open occurrence. Missing, ambiguous, or inactive location selections are rejected; omitting both selectors lets SiteCMD choose an occurrence for the check.

The server also exposes six correlation tools (Correlation Engine v3) that accept a project_id or site URL:

Tool What it does
get_active_correlations Return all active issue groups for a project with v3 enrichments: transitive causes, downstream effects, recent events, and more.
get_recent_events Return site events (deploys, traffic signals) tied to check IDs within the last N days.
get_likely_causes Return the direct and transitive likely causes for a specific check ID in a project.
get_causal_graph Return the active causal graph for a project as a node-link payload, suitable for visualization.
preview_deploy_risk Given a list of files about to change in a deploy, predict which active issues are likely to regress.
whatif_resolve Given a hypothetical set of resolved check IDs, return the downstream effects likely to also resolve.

The naming and behavior of these tools is identical across every editor. If the editor's documentation says "this is what we'll send to the MCP server," that's what SiteCMD will receive.

Keep agent context focused

Start triage with get_issues and a small limit, such as 5. Once you select a fix attempt, read its get_fix_brief and work from that brief. Fetch get_issue for the selected check_id only if evidence is missing, or get_fix_prompts filtered by check_id if you need additional prompt guidance. Avoid fetching bulk prompts after a complete brief.

Reuse the attempt ID returned by start_fix. If it returns a pending request_id, follow it with get_fix_status until an attempt ID is available, then fetch the brief. Use list_fix_attempts only when an existing attempt's ID is unknown.

For bundled MCP servers whose tool schema includes offset, the paging contract is:

Tool Default / maximum limit Page content budget
get_issues 25 / 100 16,000 characters; descriptions shortened to 300 characters
get_fix_prompts 5 / 20 24,000 characters; identical prompts appear once

These budgets cover the content body; response instructions and pagination metadata add a small overhead. Distinct occurrence guidance is preserved. A page can contain fewer entries than limit; use the returned next offset with the same URL and filters only when you need more findings. Do not calculate the next offset from the requested limit. Start at offset: 0 again after a scan or issue-state change. If a single oversized entry is shortened, another page does not continue that entry; request the selected check's details as needed. On older servers without offset, use small limits and focused checks, and update SiteCMD for pagination support.

Leave a delay between status reads and increase it when the result is unchanged. Stop polling when work finishes, fails, or needs the app opened or a deployment; resume after that prerequisite changes.

The typical workflow

A normal MCP-driven session looks like this:

  1. You pick an issue in SiteCMD and click Fix with your agent, or the AI opens the attempt itself with start_fix. Either way SiteCMD opens a fix attempt and writes its fix brief: the issue, where to fix it, and the acceptance criteria.
  2. The AI calls get_fix_brief with the known attempt ID. Use list_fix_attempts only when an existing attempt's ID is unknown. The brief supplies the working context; fetch additional evidence only if something needed for the fix is missing, following the focused context guidance.
  3. The AI makes edits. It modifies your source files with the changes the brief calls for.
  4. The AI calls request_verification, then polls get_fix_status. SiteCMD runs the required check or source audit and records the verdict. Completion time depends on that work. The AI never marks an issue fixed.
  5. Run a broader scan when needed. You click Run Scan in SiteCMD, or the AI calls run_scan with the intended scope and follows it with get_scan_status. Requests wait for the desktop app; pending scan and start-fix requests expire after 24 hours.
  6. For Web Scan changes, the AI can call compare_scans. It sees what changed between two Web Scans. For Code Scan fixes, use the attempt's verification result and current issues.
  7. Iterate. If verification fails or a new scan finds a regression, the AI uses that evidence to address it.

This loop is the entire point of the integration. Without MCP, your AI is guessing at what's wrong with your site. With MCP, it's working from the actual scan output and SiteCMD checks the result.

What MCP does not do

  • Run its own scanner. run_scan and request_verification ask the desktop app to do the work. For headless scanning, use the separate CLI.
  • Let the AI declare an issue fixed or change its lifecycle state directly. The AI can request scans and fix attempts, fetch a brief (recording that it was fetched), and request verification. SiteCMD determines verification outcomes. Ignore, Block, Snooze, and Reopen remain desktop controls.
  • Isolate access by project. A URL or project selector filters a query; it is not an authorization boundary. get_projects lists the database's projects, and a configured editor can query any of them.

Auth model

The MCP server runs on your machine, as your user, against the same local database the desktop app uses. There is no separate API key for MCP. If the desktop app can see a project, the MCP server can read it. If you don't want a specific editor to have access, don't configure the MCP server in that editor.

The transport between the editor and SiteCMD is local. Findings, evidence, and source excerpts returned to an editor can then be sent to that editor's model provider under its own settings. Review the editor's data controls before connecting it to sensitive projects. See Privacy & data.

Multiple editors

If you use more than one AI editor (Cursor in the morning, Claude Code in the afternoon), they can all point at the same SiteCMD MCP server. You configure each one separately, but the underlying server and data are shared.

You don't need to "switch" SiteCMD between editors. Each editor spawns its own subprocess copy of sitecmd-mcp and talks to it independently. Reads work with the desktop app closed, but verification needs it running: request_verification asks the app to re-run the check. With the app closed, results are only as fresh as the last time it was open.

When MCP isn't enough

If your editor does not support MCP, open the finding in SiteCMD and copy its fix prompt into the tool you use. Reports and exports cover workflows where a person or another system needs a portable result.

The standalone CLI is available for scripts, pre-push hooks, and CI pipelines. It runs Web Scan and the full Code Scan audit without Tauri or a GUI. On a connected site, sitecmd gate and sitecmd connected --submit add shared baseline or deployment context. Default CLI binaries omit the browser engine; supported desktop platforms and hosted scans provide browser analysis, and source builds of the CLI can opt into its browser feature. See CLI reference.