OverlayQA MCP
Запускайте аудиты доступности WCAG и цветового контраста на любом URL-адресе и создавайте готовые к разработке задачи QA прямо из Claude Code, Cursor или Windsurf. Бесплатный тариф: 3 сканирования в день.
Документация
OverlayQA MCP
OverlayQA MCP is a Model Context Protocol server that gives your AI coding agent accessibility and design-QA superpowers. Ask Claude Code, Cursor, or Windsurf to audit any URL for WCAG and color-contrast issues, then read, assign, discuss, tag and resolve issues in your OverlayQA projects without leaving your editor.
You: Scan staging.acme.com for accessibility issues, then open issues for the criticals.
Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100.
scan_and_create_issues → created 2 issues in "Acme Web":
- Buttons missing accessible names (WCAG 4.1.2): critical
- Insufficient text contrast on .cta (WCAG 1.4.3): high
You: List the open criticals.
Agent: list_issues(status=open, severity=critical) → 2 issues.
Install
One click:
Or add it to your editor's MCP config manually:
Claude Code (.mcp.json in your project root) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
}
}
Any MCP-compatible client works the same way. On first run a browser tab opens to connect your OverlayQA account (free, no card): pick the workspace, allow access, and the connection lasts 30 days. Credentials cache at ~/.overlayqa/auth.json; the access token is short-lived and refreshes in the background. Disconnect an editor at any time from Connected AI apps in the dashboard (app.overlayqa.com/mcp/connect).
Tools
The 0.8.0 client exposes 45 tools, listed below. Server rollout settings and your permissions determine which operations are available.
Audit
| Tool | What it does |
|---|---|
scan_accessibility | Run a WCAG audit (axe-core) on any URL. Returns violations with severity, WCAG success criteria, and an overall score. |
scan_contrast | Check color-contrast ratios across a page. Returns the failing foreground/background element pairs. |
audit_tokens | Audit a live URL's design-system tokens. Returns a 0-100 token-health score and findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity. Audits the live page only. |
File and manage issues
| Tool | What it does |
|---|---|
scan_and_create_issues | Scan a URL and auto-create an issue for every violation above a severity threshold. |
create_issue | File a QA issue with optional title, severity, type, description and assignee. An omitted title uses the issue context. |
list_issues | Page through issues filtered by status, severity, type, tags, assignee, creator, page, creation time, or active/finished/ignored state. Each issue says who filed it and whether it still needs a reply. |
update_issue | Edit supplied issue fields, assignment, ignored state or status. Takes a UUID or display id such as OQ-12. |
create_project | Create a project for a site URL. |
list_projects | List all projects on your team. |
list_labels | Read the workspace tag library, assigned tags, and your permissions. |
create_label | Create a reusable workspace tag. |
set_issue_label | Apply or remove one tag without changing issue text or other tags. |
rename_label | Rename a workspace tag (owner/admin). |
delete_label | Delete a workspace tag and its assignments; keep the issues (owner/admin). |
AI review workflows
| Tool | What it does |
|---|---|
run_auto_review | Start Auto Review using project settings, ignored findings and already-filed issues. |
compare_visual | Start visual comparison against a Figma frame, saved design or uploaded image, with optional measured spacing. |
get_review_result | Retrieve progress, findings and screenshot evidence from a saved review. |
Both start tools require projectId, a public url, and a new UUID requestId. They return a jobId immediately. Read it with get_review_result until complete or failed. Reuse the same request ID and inputs after a lost response; do not start another review just to read its result. Reviews use your scan allowance and do not automatically file issues. Visual comparison captures at the design’s authored width and returns AI findings, not a deterministic pixel-difference CI verdict.
What the server records
Every tool also accepts an optional context argument: one sentence on why the agent is calling it. OverlayQA records that sentence, the tool name, your account, project and issue ids, counts and scores, the URL a scan runs on, and your editor's name and version (from the MCP handshake) as product analytics. The sentence is capped and stripped of email addresses and credential-like strings before it is stored. Nothing else travels: not your conversation, not your code, not the tool's replies. Full detail: overlayqa.com/privacy.
Example prompts
- "Scan example.com for accessibility issues."
- "Check the contrast on our pricing page and tell me what's failing."
- "Scan staging.acme.com and create issues for anything critical or high."
- "Create a high-severity accessibility issue: the login button has no focus ring."
- "List the open critical issues in the Acme Web project."
- "Create a project for shop.acme.com, then scan it."
Pricing
| Scans | Create issues & projects | |
|---|---|---|
| Free | 3 / day, forever | no |
| 14-day trial | 30 / day | yes |
| Paid | 10-30 / day by plan, unlimited on Pro | yes, with export to Linear / Jira / Asana / Notion |
FAQ
Which editors does it work with? Claude Code, Cursor, Windsurf, and any MCP-compatible client (it speaks standard stdio MCP).
Is it free? Yes to start: 3 accessibility/contrast scans per day with no card. A 14-day trial raises that to 30 scans per day and unlocks issue and project creation. After that, creating issues and projects needs a paid plan (Pro has unlimited scans).
What does it actually scan? Any public URL. Accessibility uses axe-core mapped to WCAG success criteria; contrast checks foreground/background ratios and returns the failing element pairs.
Do I need an account? Yes, a free OverlayQA account. On first run a browser tab opens to connect it; the connection lasts 30 days and can be disconnected from the dashboard at any time.
Does it work with the OverlayQA Chrome extension? Yes. The MCP server and the extension share the same projects and issues, so anything you file from your editor shows up in the extension and the dashboard, and vice versa.
Prefer clicking to typing? Meet the extension
The MCP server is one way into OverlayQA. The Chrome extension is the other: click any element on a live page and it captures a screenshot plus the CSS, DOM, and metadata into a dev-ready issue in seconds, and runs AI accessibility and design-system audits right on the page. Same projects, same issues, shared with this server.
Links
- Website: overlayqa.com
- Chrome extension: Chrome Web Store
- Free accessibility checker (no account): overlayqa.com/accessibility-checker
- Free color-contrast checker (no account): overlayqa.com/color-contrast-checker
- Pricing: overlayqa.com/pricing
- Model Context Protocol: modelcontextprotocol.io
License
MIT
Custom issue tags
The product calls these tags. Tool names and fields containing label keep their existing identifiers for compatibility.
Use list_labels with a project UUID to see that workspace's tags and your permissions. create_label creates a reusable tag; set_issue_label applies or removes it from one issue without changing its other tags or text. Workspace owners and admins can use rename_label and delete_label; deletion removes the tag's assignments, not its issues. list_issues accepts labelIds (match any), including unlabeled. Shared reports preserve the names present when shared.
Local verification can set OVERLAYQA_API_BASE and an isolated OVERLAYQA_AUTH_FILE; neither changes the default production endpoint or normal saved login.
Issue details and discussion
| Tool | What it does |
|---|---|
get_issue | Read description, ownership, tags, ignored state, screenshots, captured element/CSS, viewport evidence, comments, saved AI analysis and the latest verification. Reading saved analysis does not run AI. |
list_issues | Filter by one or more statuses, severities or types; tags; assignee (me, unassigned, or user ID); creator; and active/finished/ignored state. Follow hasMore with the next page. |
list_project_members | Find teammate user IDs for assignment and mentions in a readable project's workspace. |
create_issue | Choose an assignee, use null for Unassigned, or omit to assign to yourself. Default type is General. |
update_issue | Change any supplied title, description, severity, type, status, assignee or ignored flag. Omitted fields remain unchanged. Ignoring never resolves an issue. Setting verified records a status; it does not run a scan. |
move_issue | Move by stable issue UUID into another writable project in the same workspace; retain comments and evidence. Read the returned display ID afterward. |
list_comments | Read the discussion, audience, mentions and attachment metadata. |
create_comment | Post with explicit internal (Team only) or public (Team and clients) audience, mentions, and optional PNG/JPG/PDF/MP4/WebM files. |
update_comment / delete_comment | Edit or delete your own native comments. Edits preserve audience and files; clear the text only while an attached file remains. |
get_comment_attachment | Read a native comment file in parts of up to 2 MiB under the issue's access rules. |
For mentions, use @[userId] in the text and include the same ID in mentionedUserIds. Comment creation requires a UUID requestId: reuse it when retrying that same submission after a lost response, so a retry does not post twice. Attachments are base64 bytes with filename and MIME type, up to ten PNG/JPG/PDF/MP4/WebM files and 10 MiB total per comment. Recording attachments upload existing files; MCP does not start a browser recording. The product validates the actual bytes and file type before saving.
For downloads, start get_comment_attachment at offset: 0. Decode each returned base64 part separately, concatenate the bytes in order, and follow nextOffset until it is null. Check the assembled file against totalBytes and sha256. Small files fit in one response. Part reads require the matching server update; older clients receive an explicit update message for large files instead of truncated data. Reusing a comment request ID returns its original content and files; use update_comment to change text or a new request ID for another comment.
list_issues defaults to all states for compatibility. Use state: "active" for open/in-progress issues that are not ignored. finished includes resolved/verified/closed issues that are not ignored; ignored selects the independent ignore flag. All supplied filters intersect. Pages start at 1 and contain up to 100 issues; an empty filtered page is not a complete-project result unless hasMore is false.
To poll for new feedback, pass createdAfter with the createdAt of the newest issue you have already seen (an ISO-8601 time with a zone, such as 2026-10-05T22:00:00Z); only issues created after it come back. pageUrl narrows the list to one page and ignores the query string. Each listed issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team), so an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. If the server has not been updated for a filter yet, the tool answers FILTER_NOT_SUPPORTED instead of an unfiltered list.
The tag tools listed above were included in 0.3.0. The later review workflows, client review tools and scheduled reviews are described below and require their matching server updates. Saved-design discovery is not included.
Verify before release
Run npm test and npm run build. The live journey drives the built client over the real stdio protocol against a local API or production using designated fixture accounts; it creates and removes its own projects and produces JSON and HTML evidence.
MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-live
MCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live
Release order: deploy and verify the matching server endpoints, then publish npm 0.8.0 and update the MCP registry. A local build or version bump is not a publication.
Verify a deployed fix
verify_issue({ issueId, requestId }) runs the same fix-verification engine as the dashboard on the issue’s saved public URL. The issue must be resolved, verified, or closed, have original screenshot evidence, and have a verifiable type (General and Improvement cannot be checked). Use a new UUID for each check; reuse that UUID only when retrying the same request after a lost response. Verification uses the workspace’s existing permissions and verification allowance and follows the server rollout setting.
The result contains a saved check ID, verdict, explanation, confidence, after-screenshot URL, capture context, and timestamps. A check can pass, pass with a caveat, fail, be inconclusive, or report an error. It never updates issue status. Inspect the evidence before deciding whether to change status with update_issue. Private or localhost pages require the browser extension’s signed-in capture.
get_issue_verifications({ issueId }) reads the latest 50 saved checks, newest first, without running another check. get_issue also includes latestVerification, or null when none exists. On an older server, an absent field means this capability has not been deployed; it does not mean the issue has never been checked.
list_issues accepts notDetected: true for issues flagged “No longer detected”, or false for issues without that flag (including issues never checked). It combines with status, state, page and other filters before pagination. The returned notDetectedAt and lastDetectedAt timestamps describe scan detection, not proof of a fix. A server that ignores this filter is refused as FILTER_NOT_SUPPORTED.
These additions need the matching server deployment before the client release. Both local and hosted MCP offer verification and saved history; hosted verification needs scan and write permission. This change does not enable verification in production.
Client review links, versions and progress
These tools require the matching server deployment before publishing this client. The guest-options database migration must be applied before deploying that server. They are available on local and hosted MCP connections and use the app's project permissions.
| Tool | What it does |
|---|---|
list_client_reviews | Read a project's client links, titles, share URLs, capture status, visits, comments, completed reviewers, and each client's invitation/reminder state. |
create_client_review | Create a live or snapshot review link, optionally with a title, client email addresses, a welcome note and private guest comments. Snapshot capture finishes asynchronously; read the list for readiness. |
update_client_review | Revoke or restore a link, change its expiry, or change responsive previews. |
set_client_review_recipients | Replace the complete client email list. Retained addresses keep their history; removed addresses stop reminders. An empty list removes all recipients while preserving the link. |
list_client_review_versions | Read saved versions of a client review and their capture state. |
get_client_review_version | Read one saved version and its page evidence by version UUID. |
create_client_review_version | Capture the next version after an explicit request, preserving the link and previous feedback. |
Version capture requires a new UUID requestId and the current baseVersionId from the version list (null only when no saved version exists). Reuse both values and the same optional name after a lost response. The server refuses a stale base rather than replacing a newer version. Read the version until capture finishes; creating a version does not mean it is ready. These tools require the server's client-review versions rollout setting.
Creating a public link requires the user's intent to share. Adding email addresses requires their intent to invite those people. A new address may receive an invitation and automatic day 3/7/10 reminders. Read invitationsEnabled and the returned per-address invites: when delivery is off, addresses are saved with sent: false, skipped: true and may be invited after it is enabled. One failed invitation does not undo the link or successful invitations.
The list returns doneReviewers and clients with email, invitedAt, inviteFailed, lastReminderAt, done, commented, and unsubscribed. Done reviewing means a client finished giving feedback; it does not certify fixes or mean everyone is done. Only the client can perform that gesture. Reminder timing and stop conditions remain owned by the existing scheduler; there is no MCP send-now tool.
After an uncertain recipient-update response, retry the same complete list and reopen it; retained addresses are not invited twice. Creating a review does not have a retry key: after a lost response, use list_client_reviews to check for the saved link before creating another. Project viewers and read-only hosted connections can read progress but cannot change links or invite people.
Retained findings, scheduled reviews, and tracker exports
These tools require the matching server update. create_review_issues shares the Auto Review/visual-comparison rollout gate.
| Tools | What they do |
|---|---|
create_review_issues | File selected zero-based indexes from a completed review, preserving saved screenshots, page context and fix guidance. Repeating the same job and indexes recovers existing issues. |
list_scheduled_reviews, create_scheduled_review, update_scheduled_review, delete_scheduled_review | Manage recurring public-page reviews under the dashboard's existing project permissions, plan limits and cadence rules. |
run_scheduled_review, get_scheduled_review_result | Start a run with a request UUID, then poll that same UUID. Run now sends no email. IDs/results are retained for 24 hours; without a request ID, read the latest saved baseline and available full evidence. |
list_export_connections, list_export_destinations | Discover connected trackers and explicit destinations. Omit collection to see the provider's available collections and required inputs. |
export_issues, get_issue_export_status | Export existing issues with their evidence and read saved delivery/sync state. Inspect every result; partial attachments and pending work are not success. |
Exports support Jira, Linear, Asana, Trello, Notion, ClickUp, GitHub, Basecamp and Monday.com through the product's existing adapters. Destination fields are required; the client never chooses the first project or list. Notion lists the database retained at connection, without arbitrary database search. An already-exported issue keeps its original destination. Images, discussion, and supported field synchronization follow the same provider limits as the app; a stored sync timestamp is not proof of a fresh round trip.
Example: call list_export_destinations with { "provider": "trello" }, then list boards and lists for the chosen board. Pass both boardId and listId in export_issues.destination. Scheduling future scans and sharing issues require the user's request. After uncertain results, read saved state before starting new work.