MCP Server

Last updated: November 7, 2026

The OverlayQA MCP server (@overlayqa/mcp on npm) connects your AI coding agent to your OverlayQA workspace over the Model Context Protocol. From Claude Code, Cursor, Windsurf, or any MCP-compatible client, the agent can scan a URL for accessibility and design-system issues, then create, read, tag, comment on, assign, and update issues in the same projects your team uses in the dashboard and the Chrome extension. This guide installs the server, connects your account, and walks through the tools it exposes.

Prerequisites

Install the Server

Add the server to your editor's MCP config. The same block works everywhere; only the file location differs.

ClientConfig file
Claude Code.mcp.json in the project root
Cursor~/.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json

Paste this into the file (merge it with any servers you already have): { "mcpServers": { "overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] } } }. Cursor and VS Code also accept a one-click install link from the MCP server page.

Connect Your Account

The first time the agent calls an OverlayQA tool, a browser tab opens so you can sign in and connect the server to your account. There is no card step. The token caches locally for 30 days, so you connect once and keep working. Every issue the agent creates lands in your projects with your account as the creator and default assignee.

Connect from Claude.ai

To use OverlayQA in Claude.ai without installing anything, open OverlayQA in Claude's connector directory, click Connect, sign in to OverlayQA, choose the workspace Claude may use, and click Allow access. To add it by hand, open Settings, then Connectors, then Add custom connector, and enter https://api.overlayqa.com/mcp as the server URL.

Tools Your Agent Can Call

Thirty-one tools are listed here, grouped by what the agent is doing. Each is described so the model picks the right one from a plain-language request such as "scan staging.example.com for accessibility issues and file the criticals".

GroupTools
Auditscan_accessibility runs a WCAG audit (axe-core) on a URL and returns violations with severity and an overall score. scan_contrast returns the element pairs failing WCAG contrast ratios.
Design systemaudit_tokens returns a 0-100 token-health score with findings on font sizes, colors, spacing, font families, and border radii.
Reviewsrun_auto_review starts Auto Review of a public page. compare_visual compares a public page against a Figma frame, saved design or uploaded image. Each uses your scan allowance, returns a job ID and creates no issues. get_review_result reads the findings and screenshot evidence without starting or charging for another run; results are kept for 24 hours by default.
Issuesscan_and_create_issues, create_issue, get_issue, list_issues, update_issue, move_issue, verify_issue, get_issue_verifications. List and filter by status, severity, type, tags, assignee, creator, or active, finished, and ignored state; update status, title, description, severity, type, assignee, or ignored state; accept a UUID or a display id such as OQ-12. verify_issue checks whether a resolved issue is fixed on its public page and returns the saved verdict; it never changes the issue's status.
Tagslist_labels, create_label, set_issue_label, rename_label, delete_label. Rename and delete follow the same owner-or-admin rule as the dashboard.
Commentslist_comments, create_comment, update_comment, delete_comment, get_comment_attachment. Comments carry an audience (Team only or Team and clients), teammate mentions, and PNG, JPG, or PDF files.
Projectscreate_project, list_projects, list_project_members.
Client reviewscreate_client_review, list_client_reviews, update_client_review, set_client_review_recipients. Create a public client link for a page, read each link's visits, comments and clients, change its expiry or revoke it, and set the client emails it is sent to.

A Typical Session

  1. Ask the agent to scan a URL: "Run an accessibility and contrast scan on https://staging.example.com/pricing." It calls scan_accessibility and scan_contrast and summarises the violations.
  2. File the ones worth fixing: "Create issues for the critical and high violations in the Pricing project." It calls scan_and_create_issues with a severity threshold, or create_issue for a hand-picked set.
  3. Work the backlog: "List active issues assigned to me with the release tag." It calls list_issues with filters, then get_issue for the selector, CSS, and screenshot evidence on each one.
  4. Close the loop: after the fix, "Mark OQ-12 resolved and leave a comment for the team." It calls update_issue and create_comment, and the change shows up in the dashboard and the extension immediately.

Limits by Plan

Scanning is available without a paid plan: 3 scans per day. Starter allows 10 scans per day, Team 30, and Pro has no daily cap. Creating issues and projects needs an active trial or paid plan; when the cap is reached the server replies with the limit and a link to overlayqa.com/pricing. Every scan covers one page per call.

Frequently Asked Questions

Which editors work with the OverlayQA MCP server?

Claude Code, Cursor, Windsurf, and any MCP-compatible client. The server speaks standard stdio MCP, so the install block is the same everywhere; only the config file location changes.

Do issues created by my agent show up for my team?

Yes. The MCP server, the dashboard, and the Chrome extension share the same projects and issues. Anything the agent files appears in the dashboard and the extension, and anything your team changes is visible to the agent on its next call.

Can the agent use OverlayQA as the bug tracker?

Yes. With the issue, tag, and comment tools the agent can create, read, tag, assign, comment on, and update issues, and your team can sync the same issues both ways with Jira, Linear, Notion, Asana, Trello, ClickUp, GitHub Issues, Basecamp, or monday.com. See Tags, Assignees, and Filters for how the fields behave.

Does the MCP server run Visual Comparison?

Yes, for public pages. Ask the agent to compare a page against a Figma frame: compare_visual starts the run and get_review_result reads each difference and its screenshot evidence. It uses your scan allowance and creates no issues. For a page behind a login, run Visual Comparison in the extension.