# OverlayQA MCP server

> Run accessibility, contrast, and design token audits and manage QA issues directly from your AI coding editor.

- Repository: https://github.com/OverlayQA/mcp
- Page: https://hostedmcp.org/servers/overlayqa/mcp
- Transport: stdio, remote
- Stars: 0
- License: MIT
- Latest version: 0.8.0

## Install

### Claude Code

```sh
claude mcp add mcp -- npx -y @overlayqa/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@overlayqa/mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@overlayqa/mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@overlayqa/mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@overlayqa/mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mcp -- npx -y @overlayqa/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@overlayqa/mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user mcp npx -- -y @overlayqa/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@overlayqa/mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MCP_PARITY_API` | no | no |  |

## Tools (45)

- `create_review_issues`: File selected findings from your completed MCP Auto Review or visual comparison in its original project. Preserves saved images, page, captured context and fix guidance without scanning again. Repeating the same job and indexes recovers existing issues; inspect every finding outcome for partial completion. Old jobs without retained page provenance cannot be filed.
- `list_scheduled_reviews`: List readable scheduled reviews in this workspace, including cadence, pause state, next run and latest saved result summary. Does not scan or send email. (read-only)
- `create_scheduled_review`: Create a recurring public-page review with the same plan limits and cadence as the dashboard. Enables future scans and review emails. A lost response can be recovered by listing schedules; the same project, page and scan type cannot have duplicate schedules.
- `update_scheduled_review`: Pause, resume, or change a scheduled review cadence. Supply exactly one of action or cadence. Resuming enables future scans and review emails; plan and project permissions still apply. Pausing keeps previous results.
- `delete_scheduled_review`: Delete a scheduled review and stop its future scans and emails. Does not delete filed project issues.
- `run_scheduled_review`: Run an active scheduled review now using its existing settings and the dashboard run-now path. Uses scan resources; Run now does not send email. Request IDs and run results are retained for 24 hours. Reuse requestId after a lost response; poll the saved run with the same scheduleId and requestId. Does not resume paused schedules.
- `get_scheduled_review_result`: Read the latest retained scheduled-review findings and evidence without rescanning, or poll a specific run by requestId. An empty result before the first successful run is not a clean scan. No longer detected, ignored and already filed are not proof that an issue was fixed. (read-only)
- `list_export_connections`: List your connected issue trackers and reconnect requirements without exposing credentials. A connection does not prove export delivery or working two-way sync. Connect or reconnect in OverlayQA first. (read-only)
- `list_export_destinations`: Discover and read destination choices for a connected tracker. Omit collection to learn its available collections and required parameters. Read choices before exporting; use schema collections for required destination fields. Does not create tasks or connect accounts. (read-only)
- `export_issues`: Export existing issues with their captured evidence and discussion to an explicitly chosen connected tracker destination. Uses the same product export and retry handlers. Inspect every result: pending or partial attachment delivery is not success. Read the saved export status after uncertain outcomes before retrying.
- `get_issue_export_status`: Read persisted export destinations, attachment delivery and the latest recorded sync success/error for an issue. Does not contact trackers or force a sync. Missing or stale sync evidence is not proof of a current round trip; unsupported fields are reported. (read-only)
- `scan_accessibility`: Run an accessibility audit on a URL. Returns WCAG violations with severity, descriptions, and an overall score. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
- `scan_contrast`: Run a color contrast audit on a URL. Returns elements failing WCAG contrast ratios with severity and details. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
- `scan_and_create_issues`: Run an accessibility scan on a URL and automatically create issues in the given project for each violation at or above the minimum severity. Returns scan summary + issue IDs created. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
- `compare_visual`: Start AI visual comparison of a public page against a Figma frame, saved design or uploaded image. Supply reference, or both figmaFileKey and figmaNodeId. Captures at the design’s authored width. Optional measureSpacing adds supported element measurements and tolerances. Uses your scan allowance and returns a persistent job ID; results include individual differences and screenshot evidence. Does not create issues or provide a deterministic pixel-difference build gate.
- `run_auto_review`: Start Auto Review of a public page in a readable project. Uses your scan allowance and the project’s review settings, ignored findings and already-filed issues. Returns a persistent job ID; results include findings, scores, AI status and screenshot evidence. Does not create issues. Login-required pages need the browser extension.
- `get_review_result`: Read a previously started review without starting or charging for another run. Returns running progress, failed details, or the complete Auto Review or visual-comparison findings and evidence. Results are retained for 24 hours by default and require access to the original project and workspace. (read-only)
- `audit_tokens`: Audit a live URL's design-system token usage. Returns a 0-100 token-health score plus findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity and evidence. Audits the live page only; the figmaFileKey argument is accepted but Figma comparison is not yet available via MCP.
- `create_issue`: Create an issue in an OverlayQA project. Title is optional; severity, type, and description default to medium / general / empty. Assignee defaults to you; pass null for Unassigned. This does not capture a screenshot or scan a page.
- `list_issues`: List project issues with tags, description, ownership and ignored state. notDetectedAt records when a scan stopped detecting the issue; lastDetectedAt records a detection. Neither proves a fix. Use notDetected to filter the flag. Filter by status, severity, type, tags, assignee, creator, page (pageUrl), or active/finished/ignored state, and use createdAfter to ask only for issues newer than the last one seen. Each issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team): an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. Returns page, pageSize, total and hasMore; continue to the next page while hasMore is true. Use get_issue for full capture evidence and the discussion.
- `update_issue`: Update issue status, title, description, severity, type, assignee, or ignored state. Only supplied fields change. Use null to unassign and ignored=false to restore. Accepts UUID or display id. Status verified does not run a verification scan. Use verify_issue to check a deployed fix, then inspect its evidence before deciding whether to change status.
- `get_issue`: Read a complete issue by UUID or display id: description, tags, assignee, ignored state, screenshot URLs, captured element/CSS and viewport evidence, its comments (the same discussion list_comments returns), aiAnalysis (the latest saved analysis with full findings and suggestions, or null), and latestVerification (the newest saved check, or null). Reading saved analysis does not run AI. Read get_issue_verifications for history; issue status and notDetectedAt alone do not prove a fix.
- `list_project_members`: List workspace teammates for a readable project. Use their userId for assignment and comment mentions. Returns the signed-in userId too.
- `move_issue`: Move an issue into another project in the same workspace, preserving its identity, comments and evidence. Requires write access to both projects. Returns its new display id; use that id afterward.
- `verify_issue`: Check whether a resolved, verified, or closed issue is fixed on its public page. Uses the existing capture and verification engine and your verification allowance. Requires an original screenshot and a verifiable issue type. Returns the saved verdict, explanation, confidence, and after-screenshot evidence; passed_with_caveat, failed, inconclusive, and error are not an unconditional pass. Does not change issue status. Login-required and localhost pages need the browser extension. Reuse requestId only when retrying the same check after a lost response. Availability follows the verification rollout.
- `get_issue_verifications`: Read the latest 50 saved verification results for an issue, newest first. Includes verdicts, explanations, confidence, after-screenshot URLs, capture context, and timestamps. This does not run a new check. An issue status of verified or a no-longer-detected flag alone is not a verification pass.
- `list_comments`: Read an issue discussion, including comment authors, audience, mentions and attachment metadata. Returns native and linked comments; edit/delete accept native comment IDs only.
- `create_comment`: Post a comment with explicit audience (Team only or Team and clients), optional teammate mentions and PNG/JPG/PDF or MP4/WebM recording files, at most 10 MiB combined. Attaches an existing recording; does not record a browser tab. Reuse requestId when retrying the same submission after a lost response.
- `update_comment`: Edit your own native comment text and mention list. Empty text is allowed only when an attached file remains. Audience and attached files stay unchanged. Supply the complete mention list, including retained mentions.
- `delete_comment`: Delete your own native comment and its attached files. This also removes it from client-visible discussions when its audience was public.
- `get_comment_attachment`: Read a native comment attachment using the issue’s read permissions. Returns up to 2 MiB as base64. Start at offset 0; decode each part separately and concatenate the bytes, following nextOffset until null. totalBytes and sha256 describe the whole file. Attachment IDs come from list_comments.
- `list_labels`: List the workspace tag library and your write/manage permissions. Optionally include an issue UUID to see its assigned tags.
- `create_label`: Create a reusable workspace tag. Editors can create tags; retries and case-insensitive duplicate names return the existing tag. Apply it with set_issue_label.
- `rename_label`: Rename a tag throughout its workspace. Requires workspace owner or admin permission. Assignments are preserved; existing shared reports keep their original names.
- `delete_label`: Delete a tag from the workspace and all its issues. Requires workspace owner or admin permission. Issues themselves are retained.
- `set_issue_label`: Apply (applied=true) or remove (applied=false) one workspace tag on an issue. Other tags and issue text remain unchanged. Safe to retry.
- `list_projects`: List all OverlayQA projects in the authenticated user's team.
- `create_project`: Create a new OverlayQA project. Returns the project id, name, slug, displayPrefix, and url.
- `list_client_reviews`: List a project’s client review links, share URLs, titles, capture status, expiry, visits, comments, doneReviewers and clients. Each client includes invitedAt, inviteFailed, invitePending, inviteUnconfirmed, lastReminderAt, done, commented and unsubscribed. Done reviewing means that reviewer finished giving feedback, not that issues are fixed or that every client is done. invitationsEnabled reports the delivery switch; reminders follow the existing automatic schedule. (read-only)
- `create_client_review`: Create a public client review link for a website in a writable project, optionally with a title, client emails, welcome note and private guest comments. Snapshot mode starts asynchronous capture; read list_client_reviews for readiness. New client emails may receive an invitation and automatic day 3/7/10 reminders. Requires explicit intent to share and, when emails are supplied, invite those people. If invitationsEnabled is false, addresses are saved but not sent and may be invited when delivery is enabled. Inspect invites for per-address sent/skipped/pending results. Pending means the invitation is queued; do not send a duplicate while the initial saved page or delivery confirmation is pending. After a lost response, list links before creating again to avoid duplicates.
- `update_client_review`: Change a client review link’s expiry or responsive previews, or revoke/restore access. Supply only fields to change. Revoked or expired links stop scheduled reminders. This does not mark a reviewer done or change issue status.
- `set_client_review_recipients`: Replace a client review link’s COMPLETE client email list. Requires explicit intent to invite or remove these people. New addresses may receive an invitation and automatic day 3/7/10 reminders; retained addresses keep their history and are not invited again. Removed addresses stop reminders; an empty list removes all recipients but leaves the public link working. If invitationsEnabled is false, addresses are saved for later delivery. Read clients and invites for actual per-address state. Reminders stop after that address comments, marks done, unsubscribes, or the link expires/is revoked.
- `list_client_review_versions`: Read saved versions and capture attempts for a client review you can access, including exact-version links, feedback counts and completed reviewers. Does not capture a page or mark anyone done. (read-only)
- `get_client_review_version`: Read one saved client review version with its original snapshot and version identity. Version IDs must belong to this review. Reading history never fetches today’s website. (read-only)
- `create_client_review_version`: Capture and publish a new saved page beneath an existing client review link in a writable project. Supply the current baseVersionId and reuse requestId after a lost response. Returns a capture attempt; read history until ready or failed. Does not create invitations, restart reminders, copy feedback, resolve issues, or mark reviewers done. Finishing an initial saved page can fulfil invitations already requested for that link. Requires an explicit request to publish a new version.

## FAQ

### Which editors does it work with?

It works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

### Is it free?

Yes, you can start for free with 3 accessibility or contrast scans per day. A 14-day trial increases this to 30 scans per day and enables issue and project creation.

### What does it actually scan?

The server can scan any public URL for WCAG accessibility violations using axe-core and check color-contrast ratios for failing element pairs.

### Do I need an account?

Yes, a free OverlayQA account is required. You connect it via a browser tab on the first run, and the connection lasts for 30 days.
