OverlayQA

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, label 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:

• Install in Cursor
• Install in VS Code

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

Tools your agent can call. Each is written so the model picks the right one from natural language.

Audit

File and manage issues

AI review workflows

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

See overlayqa.com/pricing.

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](https://chromewebstore.google.com/detail/overlayqa/pbnjikbncbjaaimelhlkfihgdkocmmei) 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 labels

Use list_labels with a project UUID to see that workspace's labels and your permissions. create_label creates a reusable label; set_issue_label applies or removes it from one issue without changing its other labels or text. Workspace owners and admins can use rename_label and delete_label; deletion removes the label'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 management in 0.3.0

Requires the matching issue-parity API deployment. Existing scans and status updates remain compatible with 0.2.0.

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 files and 10 MiB total per 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