How I let Claude Code handle my accessibility compliance

When I started building WebAbility.io, I leaned heavily on Claude Code to move things fast. It could whip up a form, a modal, or even an entire checkout flow in a fraction of the time it would take me. But speed came with a catch: the pages looked fine, but users with screen readers or low vision still hit roadblocks. I noticed missing form labels and low-contrast buttons slipping through.

That’s where the WebAbility MCP comes in. I built it to give my coding agent an extra set of eyes: it scans the rendered page against WCAG 2.2 AA, generates accessibility fixes, and then verifies that those fixes actually work. In this post, I’ll walk through how to set up the MCP server with your coding agent and show you the scan-fix-verify loop in action.

Why an MCP for accessibility

Most accessibility tools stop at a report. You get a score and a list. Someone still has to read each finding, find the file, and write the change in the right framework.

An agent with direct tool access closes that gap. Three things make it work well:

• The agent sees real output. The scan runs against the rendered page, not against a guess about what your JSX produces.
• The output is structured. Each issue has a machine-readable fix, so the agent does not have to parse prose.
• The agent can verify. After a change, a re-scan says if the issue is gone. You do not rely on the agent's claim that it worked.

The server runs three engines and deduplicates the results into one list: WebAbility detectors (60+ rules), axe-core (104 rules), and HTML_CodeSniffer (200+ rules). If two engines report the same problem on the same element, you see it once.

60-second setup

The hosted server is at https://mcp.webability.io/mcp (Streamable HTTP). You need no API key and no account to start.

Cursor

Use the one-click link:

Add to Cursor

Or paste this into your MCP config:

{
  "mcpServers": {
    "webability": {
      "url": "https://mcp.webability.io/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http webability https://mcp.webability.io/mcp

In claude.ai, add the same URL as a custom connector.

VS Code

Add the server to your MCP configuration (.vscode/mcp.json):

{
  "servers": {
    "webability": {
      "type": "http",
      "url": "https://mcp.webability.io/mcp"
    }
  }
}

The same URL works in Windsurf, Zed, ChatGPT (as a connector), Gemini CLI, and any other MCP client. If you prefer to run it locally over stdio:

npx -y @webability/mcp

Then ask your agent: "Scan https://webability.io/pricing for accessibility issues."

The scan, fix, verify loop

Three tools carry the main loop: scan_page, generate_ai_fix, and verify_fix.

1. Scan

scan_page returns output in three tiers:

• issues: high-confidence violations. Safe to act on.
• incomplete: findings that need a person to judge, such as contrast over a photo or the alt text of a marketing image. The agent should treat these as questions, not bugs.
• summary: counts by severity, plus the number of incomplete items.

Example output (shortened):

# example
summary: 4 issues (2 serious, 2 moderate), 1 incomplete

1. image-alt (serious)  img.hero__photo
   fix.op: add-attribute  fix.attribute: alt
   fixability: contextual
   source: src/components/Hero.tsx:42:7  <Hero>

2. label (serious)  input#email
   fix.op: add-attribute  fix.attribute: aria-label  fix.value: "Email address"
   fixability: mechanical
   source: src/components/SignupForm.tsx:18:9  <SignupForm>

3. color-contrast (moderate)  button.cta
   fix.op: suggest
   fixability: visual
   source: src/components/Cta.tsx:11:5  <Cta>

Every issue carries a fix.op from a closed set: add-attribute, set-attribute, remove-attribute, add-element, remove-element, add-text-content, or suggest. It also carries a fixability tag:

• mechanical: the value is known. Apply it as given.
• contextual: the operation is known, but the value needs judgment, such as alt text or a label. The agent reads the HTML and writes it.
• visual: needs rendered output, such as contrast, focus rings, or target size. The agent proposes a change and you review it.

That tag matters. It tells the agent which fixes it may apply on its own and which ones need your eyes.

2. Fix

For the mechanical items, the agent edits the file directly. For items that need framework-aware code, generate_ai_fix produces a suggestion that matches your stack. Findings from scan_page and generate_ai_fix are the tools to use together here; detect_framework tells the fix generator whether you use Tailwind, MUI, Bootstrap, Next.js, WordPress, or plain CSS.

3. Verify

verify_fix re-scans the element you changed and returns true or false.

# example
verify_fix  img.hero__photo  -> verified: true
verify_fix  input#email      -> verified: true
verify_fix  button.cta       -> verified: false  (contrast 3.1:1, needs 4.5:1)

The third result is the useful one. The agent thought it was done, and the verifier said no. The agent tries again with a darker color token.

More tools around the loop

• diff_scan compares two scans and reports fixed, new, and remaining issues. Use it to check that a change did not add regressions.
• flow_scan walks a multi-step flow, such as login, dashboard, and checkout, and reports the unique issues across it.
• visual_audit is a vision pass. It looks at the rendered screenshot for things DOM engines miss, such as weak focus visibility or an element that looks like a button but is not one.
• start_audit and get_audit run a full audit and return a report, an Excel workbook, and a PDF.

If your agent has a small context window, pass format: "compact". It prints one line per issue.

Localhost via tunnel

The hosted server runs on our infrastructure, so it cannot reach localhost:3000 on your laptop. The tunnel closes that gap:

webability-tunnel --port 3000

Run it next to your dev server. The hosted tools can then scan the app you are building, before you push anything. This is the loop that matters most for day-to-day work: change code, scan the dev server, verify, commit.

Source pointers

A selector tells you what is wrong. It does not tell you which file to open.

On React 18 and earlier, and on Vue development builds, each issue carries file:line:column and the component name. Those values come from the live component tree. In the example above, you can see src/components/SignupForm.tsx:18:9 next to the label issue. The agent opens that file directly.

Production builds do not carry this data. For those, the local find_source tool maps a selector back to files in your source tree.

Free model and fair-use limits

The MCP is free. There are no credits, no trial period, and no paid tier on the MCP.

Access	What you get
Anonymous	Scan and check tools, with fair-use limits: 30 browser scans per hour and 10 AI fixes per hour, per IP address
Free WebAbility account	The limits lifted, plus visual_audit, start_audit, and get_audit

To sign in, use the one-click OAuth prompt in your client. For the local server, run webability login.

What automation does not cover

Automated testing finds a share of WCAG problems, not all of them. (The ADA rule cites WCAG 2.1 AA; the MCP checks 2.2 AA, which includes every 2.1 AA criterion.) No scanner can tell you whether your alt text is meaningful, whether the heading order matches the page logic, or whether a screen reader announces a custom widget in a useful way. Use the MCP to clear the automated layer at source, then test with assistive technology for the rest. The incomplete tier exists so the agent does not guess where a person should decide.

FAQ

Do I need an API key?
No. Point your client at https://mcp.webability.io/mcp and start. Sign in with a free account only if you want the limits lifted or the vision and audit tools.

Which clients work?
Claude (Claude Code and the claude.ai connector), Cursor, VS Code, Windsurf, Zed, ChatGPT (as a connector), Gemini CLI, and any MCP client.

Will the agent change things it should not?
It should not. Findings in the incomplete tier are for human review, and visual fixes are proposals. You review every change before you commit, as with any agent-written code.

Can it scan my local dev server?
Yes. Run webability-tunnel --port 3000 and the hosted tools can scan it. The local npx -y @webability/mcp server is the other option.

How do I know a fix worked?
Run verify_fix on the element, or diff_scan on the page. Both re-scan and report a result. You do not need to trust the agent's own summary.

Try it

Add https://mcp.webability.io/mcp to your client, then ask your agent to scan the page you are working on today. Start with the issues marked mechanical. They are the fastest to fix and the easiest to verify.