Skip to main content

MCP Server

← Back to Documentation

The A11y Pulse MCP server gives your AI coding agent direct access to your scan data. Instead of manually reviewing the dashboard, copying issue details, and context-switching to your editor, your agent can fetch your accessibility violations and suggest targeted code fixes without you leaving your IDE.

It works with Claude Code, Cursor, and GitHub Copilot.

Contents:

When to use this

The MCP server is useful when you want to work through accessibility violations as part of a normal development session. Your agent can pull the latest scan for any of your sites, prioritise issues by severity, trace each failing element back to its source component, and suggest concrete code changes — all in one flow.

It’s most effective when you have a backlog of accessibility issues and want to make systematic progress on them, or when you want to address violations immediately after a new scan.

Setting up

Step 1: Get your API key

The MCP server authenticates using your A11y Pulse API key. Go to Settings and scroll to the API Keys section to create one if you don’t have one yet.

Settings page showing the API Keys section

Keep your API key somewhere safe — you’ll need it in the next step.

Step 2: Add to your AI coding tool

Go to Settings → Integrations → MCP Server in A11y Pulse. Select your tool and copy the config snippet, then add it to your MCP settings file.

MCP Server setup page showing the two-step card layout with Get your API key and Add to your AI coding tool steps

The setup page tells you exactly which file to paste into for your tool. For Claude Code and Cursor, you’ll also need to add your API key as an environment variable — the snippet includes a placeholder showing the variable name to use. Copilot will prompt you for the key when it first connects.

Available tools

The MCP server exposes five tools your agent can call. You don’t need to invoke these manually — your agent discovers and calls them automatically based on what you ask it to do.

get_sites

Returns a list of all sites in your A11y Pulse account, including issue counts by severity (critical, serious, moderate, minor) from the latest scan. Your agent uses this to present an overview and help you decide which site to work on.

get_latest_scan

Fetches the complete latest scan for a site. Returns a per-page breakdown with all violations for each page, including the full detail for each failing HTML element: the rendered HTML snippet, CSS selectors, XPath, and fix instructions (failureSummary). Use this when you want to work across an entire site.

get_page_scan

Fetches the latest scan for a single page. Returns the same detail as get_latest_scan but scoped to one URL. Useful when you want to focus on a specific page, or when a full site scan is too large to work through in one session.

fix_site_accessibility

A compound tool that orchestrates the full fix workflow for a site. It fetches the latest scan, prioritises issues by impact (critical → serious → moderate → minor), and structures the output with an impact summary and per-page issue details. It references the MCP resources (see below) to guide your agent through mapping DOM nodes to source files and generating fixes. Optionally accepts codebase context to help your agent find the right files.

fix_page_accessibility

The same compound workflow as fix_site_accessibility, but scoped to a single page. Use this when you want to focus on one URL, or when your agent suggests narrowing down from a large site scan.

Using your agent effectively

Start with the compound tools

For most sessions, ask your agent to fix accessibility issues for a site or page directly. It will call fix_site_accessibility or fix_page_accessibility and handle the entire workflow — fetching data, prioritising issues, mapping them to source code, and proposing fixes.

A good starting prompt:

Fix the accessibility issues on my marketing site.

If you have multiple sites, your agent will call get_sites first and ask you to confirm which site to work on.

Give your agent codebase context

The MCP server returns DOM-level data — HTML snippets, CSS selectors, and XPaths. For your agent to map these back to source files accurately, it needs to know where your code lives. If you don’t provide this upfront, your agent will ask before proceeding.

Be ready to answer:

  • Which app or package in your repo contains the code for the scanned site? (e.g. apps/web in a monorepo)
  • Where do component and page source files live? (e.g. apps/web/src/components)
  • Where are your styles and design tokens defined? (e.g. a Tailwind config or CSS variables file)

This is especially important in monorepos where a single repo may contain code for multiple sites (marketing, app, docs) — the scanned URL only maps to one of them.

Work through large sites page by page

For sites with many pages, your agent may suggest switching from fix_site_accessibility to fix_page_accessibility to keep the session focused. This is normal — accessibility work on large sites is most manageable one page at a time.

Ask your agent to list the pages with the most critical issues first, then tackle them in order.

Review fixes before applying

Your agent will present proposed fixes organised by source file, with a before/after code change and a confidence level (high, medium, or low) for each. Review these before approving — the agent will not apply changes automatically.

For Fix any violations (where multiple fixes are valid), your agent will choose the most appropriate one for the component’s context. If you disagree with the choice, you can tell it to use a different approach before it applies the change.

After applying fixes, your agent will summarise what changed. It will not commit — that’s left to you.

Good to know

  • Read-only access: The MCP server can only read your scan data. It cannot trigger new scans, create sites, or modify anything in A11y Pulse.
  • No live scanning: The server only accesses data from completed scans stored in A11y Pulse. It does not run axe-core against live URLs.
  • Status shown as “API key available”: The integrations page shows whether you have an API key set up, not whether an agent is currently connected. There’s no way to detect active MCP client connections server-side.
  • No scan notifications: There’s no way for the MCP server to notify your agent when a new scan completes. Check the dashboard and start a new session when you want to work on fresh results.
  • Very large sites: For sites with 100+ pages, get_latest_scan returns all data. If the response is too large for your agent’s context, it will suggest switching to get_page_scan for focused work on individual pages.
  • Rate limiting: The server applies a rate limit of 100 requests per minute per API key. Normal agent sessions won’t hit this.
  • API key security: Never paste your API key directly into a config file that gets committed to source control. Always use an environment variable (A11Y_PULSE_API_KEY) or your tool’s secrets prompt (Copilot).