axe MCP Server

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

Overview

The axe MCP Server is a Model Context Protocol (MCP) server that integrates enterprise-grade accessibility testing directly into your development workflow. Built on the trusted axe platform, it enables developers to perform comprehensive accessibility scans and receive expert remediation guidance without leaving their IDE.

The server provides three capabilities - analyze, remediate, and igt.

These tools integrate seamlessly with MCP-compatible clients (like Claude Desktop, VS Code with Copilot, or Cursor) and respect your organization's axe Configuration settings.

Getting Access

Axe MCP Server is included in the Axe DevTools for Web bundle. A subscription that enables axe MCP Server access is set up by talking to a Deque sales representative.

Tools & Capabilities

The analyze Tool

The analyze tool performs comprehensive accessibility analysis on web pages by running a scan through the axe DevTools Browser Extension in a real browser environment. It works seamlessly with both local development URLs (e.g., localhost:3000) and remote production URLs.

What It Does

  1. Authentication - Validates the user's credentials (either an API key or an OAuth 2.0 access token) to ensure authorized access
  2. Configuration Retrieval - Fetches the user's organization-specific axe Configuration settings, including:
    • Accessibility Testing Standard (e.g., WCAG 2.2 AA)
    • axe-core version
    • Needs review / best practices
  3. Browser-Based Analysis - Spins up a browser instance in the background with the axe DevTools Extension mounted
  4. Page Navigation - Navigates to the URL provided by the user in their prompt to the AI agent
  5. Accessibility Scan - Runs a full accessibility analysis on the rendered page using the axe DevTools Browser Extension, ensuring that the actual user experience is tested (not just static HTML)
  6. Results Delivery - Returns comprehensive analysis results back to the agent in a structured format

Responsive Testing

The analyze tool supports optional viewportWidth and viewportHeight parameters, allowing you to test pages at specific viewport dimensions. This is useful for catching accessibility issues that only appear at certain screen sizes, such as mobile or tablet breakpoints.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

When these parameters are omitted, the browser uses its default viewport size.

Partial Page Scans

By default, the analyze tool scans the entire page. To scope the scan to a specific region, pass the optional selector parameter — useful for focusing on a single component or excluding noisy, unrelated parts of the page from the results.

  • A single CSS selector string targets an element in the top frame:

    {
  "url": "http://localhost:3000",
  "selector": "#main"
}

  • An array of CSS selectors steps through iframe or shadow-DOM boundaries — each segment selects the host for the next. Use an array only when the target lives inside an iframe or shadow root:

    {
  "url": "http://localhost:3000",
  "selector": ["iframe#checkout", "#payment-form"]
}

An array supports up to 10 segments. If the selector matches no element on the page, the scan returns an error. When selector is omitted, the whole page is scanned.

Prompt your AI agent in natural language — the agent translates your intent into the tool call:

Scan only the #main region of http://localhost:3000 for accessibility issues

Browser Interactions Before Scanning

The analyze tool supports an optional before array of interaction steps that run after the page loads but before the accessibility scan. This unlocks several real-world testing scenarios:

  • Login-gated pages — fill in credentials and submit before scanning the post-login page
  • Cookie/consent banners — dismiss banners that would otherwise overlay or obscure page content
  • Dynamic content — wait for client-rendered content (route changes, late-injected DOM) to appear before scanning

Steps execute in array order, in the same browser context as the scan, so cookies, localStorage, and any route changes triggered by click or fill persist into the scan.

The before array supports up to 20 steps. Each step gets its own timeout of BROWSER_TIMEOUT_MS (default 30000 ms); there is no per-step override.

Supported Actions
Action Required fields Optional fields Purpose
click selector Click the element matching the CSS selector (e.g., a submit button, a "Dismiss" button on a banner).
fill selector, value Fill an input matching selector with value. Use for credentials, search queries, or form fields. An empty string clears the input.
waitFor selector state — one of "visible" (default), "attached", "hidden", "detached" Wait for the element matching selector to reach state. Use to gate the next step or the scan itself. Pick a selector that exists only in the post-interaction state (e.g., a logout button or dashboard heading) — generic selectors like body or #app already exist before the interaction and resolve instantly, so they won't gate anything.
Example: Logging in before scanning

Prompt your AI agent in natural language — the agent translates your intent into the tool call:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

The agent resolves the prompt and calls the analyze tool with a payload similar to:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}
important

fill.value is treated as sensitive. The axe MCP Server never logs fill.value, never echoes it in error messages, and never sends it to telemetry. Use fill for any user-supplied or secret input (passwords, API tokens, etc.) so secrets stay redacted across the entire pipeline — and never embed sensitive values in a selector, which does appear in logs and error messages.

note

The agent resolves value, not the server. The axe MCP Server treats value as a literal string — it does not read files, expand environment variables, or interpret placeholder syntax like ${VAR}, $VAR, or {{VAR}}. Your AI agent (Claude, Copilot, Cursor, etc.) is responsible for resolving the user's intent into a concrete string before calling the tool.

In practice, this means:

  • Phrase prompts naturally — "use USERNAME/PASSWORD from .env.local" works. The agent reads the file with its own filesystem tools and substitutes the values.
  • Don't paste placeholder syntax — writing value: "${USERNAME}" in a prompt will cause the literal string ${USERNAME} to be typed into the input.
  • Be explicit about ambiguous sources — if you say "use my saved credentials" without pointing the agent at a file or env var, a well-behaved agent will ask rather than guess. Tell it where to look.
caution

Some authentication flows are not supported. before actions drive the page through Playwright-style interactions in a Dockerized Chromium instance. The following are intentionally out of scope:

  • Captcha challenges (reCAPTCHA, hCaptcha, etc.)
  • 2FA / TOTP / SMS verification codes
  • Third-party SSO redirect chains (e.g., "Sign in with Google", Okta-hosted login pages)

When your real login flow requires any of the above, scan an alternative entry point:

  • A pre-authenticated session cookie injected with Cookie Injection — authenticate once in a real browser, then pass the resulting session cookie so the scan starts already logged in
  • A session token or bypass URL your team uses for automated testing
  • A staging URL with auth disabled for accessibility testing

The analyze tool supports an optional cookies array that sets cookies on the browser context before navigation — so they ride the very first request to the page. This is distinct from before actions, which run after navigation and therefore cannot influence how the initial request is routed. Two common uses:

  • Environment routing — set a staging or feature-branch selector cookie that an edge or CDN layer reads to decide which version of the site to serve.
  • Pre-authenticated sessions — inject a valid session cookie so the scan starts already logged in, without driving a login form through before.

The cookies array supports up to 20 cookies.

Field Required Description
name Yes Cookie name. Appears in logs and error messages — never put secret values here.
value Yes Cookie value. Treated as sensitive: never logged, echoed in errors, or sent to telemetry. Up to 10,000 characters (long enough for JWTs and session tokens).
domain Yes Cookie domain. Required so scope is explicit. Use a leading dot (.example.com) to share the cookie across subdomains.
path No Cookie path. Defaults to /.
sameSite No One of "Strict", "Lax", or "None". "None" requires secure: true.
secure No Boolean.
httpOnly No Boolean.
expires No Expiry as a Unix timestamp in seconds. Omit for a session cookie.
Example: Landing on a pre-authenticated page

Prompt your AI agent in natural language — the agent translates your intent into the tool call:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

The agent resolves the cookie value and calls the analyze tool with a payload similar to:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}
important

cookies[*].value is treated as sensitive. As with fill.value, the axe MCP Server never logs a cookie's value, never echoes it in error messages, and never sends it to telemetry. A cookie's name, however, does appear in logs and error messages — keep secrets in value, never in name.

note

The agent resolves value, not the server. Cookie values follow the same rule as fill.value in before actions: the server treats value as a literal string and does not read files, expand environment variables, or interpret placeholder syntax like ${VAR}. Your AI agent resolves the user's intent into a concrete string before calling the tool.

Key Benefits

  • Real Browser Testing - Tests the actual rendered page, not just source code, ensuring accurate results
  • Organization Standards - Respects your team's axe Configuration settings for consistent testing across all users
  • Comprehensive Coverage - Leverages the industry-leading axe Platform
  • Responsive Testing - Test at specific viewport dimensions to catch breakpoint-specific accessibility issues
  • Targeted Scans - Scope a scan to a specific region, iframe, or shadow root with the selector parameter
  • Authenticated & Interactive Pages - Scan pages behind a login, dismiss cookie banners, or wait for dynamic content using before actions
  • Session & Environment Cookies - Land already authenticated, or route to a specific environment, by injecting cookies before navigation with the cookies parameter

Output

The tool returns a structured JSON response containing:

  • All accessibility violations found
  • Violation severity levels (critical, serious, moderate, minor)
  • Specific element selectors and source code
  • Rule IDs and descriptions

The remediate Tool

The remediate tool takes one or more accessibility issues identified by the analyze or igt tool and generates context-aware, AI-powered remediation guidance that coding agents can translate into actual code fixes. Issues are submitted as a batch, so a single call can return fixes for every violation found on a page.

What It Does

  1. Authentication - Validates the user's credentials—either an API key or an OAuth 2.0 access token—to ensure authorized access
  2. AI Credit Usage - Each issue in the batch consumes AI credits from your organization's allocation, enabling the use of advanced AI models trained on Deque's extensive accessibility expertise
  3. AI-Generated Remediation - Crafts high-quality, actionable accessibility fixes that coding agents can interpret and implement in the source code
note

If AI credits are depleted, the remediate tool will no longer work until your credits are restored (either by purchasing more or your monthly cycle resets). However, the analyze tool will continue to function.

Batch Remediation

The tool accepts an issues array. Submit all the issues from a single analyze or igt run together in one call rather than calling the tool once per issue — a batch supports between 1 and 25 issues.

Each issue has the following fields:

Field Required Description
id Yes A caller-chosen identifier, unique within the batch (e.g., the rule ID plus a counter: color-contrast-0). Used only to correlate each result to its input.
rule Yes The axe rule ID from the analyze/igt output (e.g., color-contrast, image-alt).
elementHtml Yes The HTML snippet of the violating element.
remediation Yes A description of what's wrong and what needs fixing, taken from the issue's summary (optionally enriched with its description, help text, or AI reasoning).
pageUrl No The URL of the page being remediated, from the analyze response.

Prompt your AI agent in natural language — it assembles the batch from the analysis results:

Analyze http://localhost:3000 and remediate every issue found

The agent resolves the prompt and calls the remediate tool with a payload similar to:

{
  "issues": [
    {
      "id": "color-contrast-0",
      "rule": "color-contrast",
      "elementHtml": "<span style=\"color: #aaa\">Sign up</span>",
      "remediation": "Increase the contrast ratio to at least 4.5:1",
      "pageUrl": "http://localhost:3000"
    },
    {
      "id": "image-alt-1",
      "rule": "image-alt",
      "elementHtml": "<img src=\"logo.png\">",
      "remediation": "Add alt text describing the image"
    }
  ]
}

Output

The tool returns an array of per-issue results, each keyed back to its input by id. A result is one of two shapes:

  • Success — status: "ok", with a remediation object containing a general description, the remediation steps, and a concrete code fix
  • Error — status: "error", with an error object (code and message) for an issue that could not be remediated
{
  "data": [
    {
      "id": "color-contrast-0",
      "status": "ok",
      "remediation": {
        "general_description": "...",
        "remediation": "...",
        "code_fix": "<span style=\"color: #595959\">Sign up</span>"
      }
    },
    {
      "id": "image-alt-1",
      "status": "error",
      "error": { "code": "LLM_ERROR", "message": "..." }
    }
  ]
}

Results are independent: a failure on one issue does not block guidance for the others.

Credit Usage

The remediate tool is part of the AI Credit Management System. Each issue in a batch consumes credits from your organization's monthly allocation. Administrators can monitor credit usage through the axe Account Portal.

The igt Tool

The igt tool runs Deque's Automated Intelligent Guided Tests (IGTs) against a web page from your IDE. Where the axe DevTools Browser Extension normally walks a developer through an IGT with manual prompts, the igt tool drives the test automatically and returns structured results a coding agent can act on.

Today the tool supports the Keyboard IGT, which evaluates whether the interactive elements on a page can be reached and operated using the keyboard alone.

What It Does

  1. Authentication - Validates the user's credentials—either an API key or an OAuth 2.0 access token—to ensure authorized access
  2. Browser-Based Run - Tests in the same Chromium instance with the axe DevTools Extension mounted that the analyze tool uses
  3. Page Navigation - Navigates to the URL provided by the user in their prompt to the AI agent
  4. Automated Keyboard IGT - Tabs through the page while AI analyzes each tab stop, evaluating focus order and keyboard operability—no manual input required
  5. Results Delivery - Returns structured findings back to the agent

Usage

The tool accepts a url and an igtTools array naming which IGTs to run. The Keyboard IGT is currently the only supported value:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

Prompt your AI agent in natural language—the agent translates your intent into the tool call:

Run the keyboard IGT on http://localhost:3000

Browser Interactions Before Testing

Like the analyze tool, igt accepts an optional before array of interaction steps that run after the page loads but before the guided test triggers. This lets you run a guided test against login-gated pages, dismiss cookie banners, or wait for dynamic content to appear first.

The steps run in the same browser context as the test (so cookies, localStorage, and route changes persist), use the same click, fill, and waitFor actions, and are capped at the same 20 steps. See Supported Actions under the analyze tool for the full reference, including the sensitive-value handling of fill.value and the selector rules.

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"],
  "before": [
    { "action": "fill", "selector": "#username", "value": "<resolved-from-.env.local>" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Output

The tool returns a structured JSON response:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "keyboard": {
      "issues": [],
      "unanalyzedElements": [],
      "terminatedReason": "keyboard-trap"
    }
  }
}
  • issues - Keyboard accessibility violations found during the run
  • unanalyzedElements - Tab stops the AI could not analyze. These are reported separately from issues so they can be reviewed manually, rather than being misreported as either passing or failing.
  • terminatedReason - Present only when the run was cut short before every tab stop was analyzed. The current value is "keyboard-trap", meaning the test encountered a keyboard trap it could not escape; the remaining steps are halted and the tab stops analyzed up to that point are returned in issues.

Credit Usage

The igt tool is an AI-powered feature and is part of the AI Credit Management System. Each run consumes AI credits from your organization's monthly allocation. Administrators can monitor credit usage through the axe Account Portal.

note

If AI credits are depleted, the igt tool will no longer work until your credits are restored (either by purchasing more or your monthly cycle resets). However, the analyze tool will continue to function.

Getting Started

Setting up the axe MCP Server involves three independent choices:

  1. Choose a distribution — Docker or npm
  2. Set up authentication — an API key or OAuth 2.0
  3. Configure your client — VS Code with Copilot, Cursor, or Claude Code

For environment variables and recommended AI-agent instructions, see the Configuration Reference. If something goes wrong, see Troubleshooting.

Example Prompts

Ensuring expected tools get called

In many IDEs, using the following syntax ("#" prefix) will ensure the axe MCP Server tools are called as expected:

#analyze the http://localhost:3033/ web page for accessibility issues and #remediate any violations found

Analyze a localhost URL for accessibility issues:

Analyze http://localhost:3000 for accessibility issues

Analysis with remediation:

Analyze https://example.com for accessibility issues and fix any issues found

Analyze a page behind a login:

Analyze http://localhost:3000 for accessibility issues. Before running the
analysis, fill in the #username and #password fields with USERNAME and
PASSWORD from ./.env.local, click the button[type=submit] button, and
wait for #main-content to appear.
Analyze https://example.com for accessibility issues, but first click the
#cookie-dismiss button to dismiss the cookie consent banner.

Scan a page with an injected session cookie:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

Support

For questions, issues, or feedback regarding the axe MCP Server:

Security & Privacy FAQ

Does axe MCP Server capture or store our source code?

No. The axe MCP Server does not capture or store your source code in any database or persistent storage.

When the analyze tool runs, the response includes the HTML source code of accessibility issue elements for context and debugging purposes. However, this data:

  • Is only returned in the immediate API response to your AI agent
  • Is never persisted to Deque-managed databases
  • Remains within your local development environment
  • Is discarded after the analysis completes

How long do MCP test results live on Deque-managed infrastructure?

They don't. MCP test results are not persisted in any Deque-managed database or storage system.

The analyze tool:

  • Runs entirely on your machine — in a Docker container, or as a local Node.js process with the npm distribution
  • Returns results directly to your AI agent
  • Does not send analysis results to Deque servers

The only exception is when you call the remediate tool, which can include minimal violation metadata (see below) to generate AI-powered fix guidance.

What data is sent to Deque servers?

Only when using the remediate tool:

The following data is sent to Deque's AI remediation endpoint to generate fix guidance:

  • Rule ID - The specific accessibility rule that was violated
  • Element HTML - The HTML markup of the affected element(s)
  • Issue metadata - Violation description and remediation guidance from axe-core

This data is used exclusively to generate remediation guidance and is not stored long-term in Deque databases.

The analyze tool does not send any data to Deque servers beyond authentication requests (validating your API key or OAuth 2.0 access token).

What level of access does the AI agent need to function?

The AI agent (Claude, Copilot, Cursor, etc.) needs access to:

  1. MCP Server Communication - The agent must be able to call the MCP server's tools through the Model Context Protocol

  2. Tool Response Data - The agent receives:

    • Accessibility violation data from analyze calls
    • Remediation guidance from remediate calls
    • This data is necessary for the agent to understand issues and generate code fixes

  3. Your Codebase (Optional) - If you want the agent to automatically apply code fixes, it needs access to your source code files

  • This is standard for AI coding assistants in IDEs (VS Code, Cursor, etc.)
  • Not required if you're only using the tools for analysis and guidance (e.g., via Claude Desktop app)

The MCP server itself needs access to:

  • URLs you specify for testing (supports both local and remote)
  • Your axe credentials: either an API key (generated in the axe Account Portal) or an OAuth 2.0 access token (obtained via @deque/axe-auth); provided via environment variable

Important: The MCP server runs locally on your machine — in a Docker container, or as a Node.js process with the npm distribution. It does not require broad file system access or elevated privileges.

Best Practices

  • Credential Security - Store your AXE_API_KEY or AXE_ACCESS_TOKEN as an environment variable, not in code. With OAuth 2.0, @deque/axe-auth keeps tokens in your OS keychain and injects a fresh access token at startup, so no long-lived secret needs to live in your configuration
  • Local Testing - Test local development URLs (localhost) or staging to keep sensitive pre-production code isolated
  • Network Isolation - The MCP server only communicates with:
    • URLs you explicitly request to analyze
    • Deque servers for authentication (API key or OAuth 2.0 token validation) and remediation (when called)
    • Your local AI agent through MCP protocol
  • Review Before Applying - Always review AI-generated code changes before committing them to your codebase

Is this page helpful?

Help us improve this page

Still need help?