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 two primary capabilities - analyze and remediate.

Both 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.

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.

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 baked into a staging environment
  • A session token or bypass URL your team uses for automated testing
  • A staging URL with auth disabled for accessibility testing

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
  • Authenticated & Interactive Pages - Scan pages behind a login, dismiss cookie banners, or wait for dynamic content using before actions

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 any accessibility issue identified by axe and generates context-aware, AI-powered remediation guidance that coding agents can translate into actual code fixes.

What It Does

  1. Authentication - Validates the user's credentials—either an API key or an OAuth 2.0 access token (see Set Up Authentication)—to ensure authorized access
  2. AI Credit Usage - Each remediate call 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 fix 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.

Output

The tool returns structured remediation guidance that includes:

  • High-level summary of the required fix
  • Specific code changes needed (in HTML format)
  • Accessibility reasoning and WCAG criteria
  • Additional context to ensure proper implementation

Credit Usage

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

Installation and Setup

Prerequisites

  • Docker installed and running on your system
  • AI agent configured for axe MCP Server (see Configuration below for IDE-specific setup instructions)
  • A subscription that enables axe MCP Server access by talking to a Deque sales representative

Step 1: Set Up Authentication

The axe MCP Server supports two authentication methods.

Option A: API Key

  1. Log into the axe Account Portal
  2. Navigate to the API Keys page
  3. Click ADD NEW API KEY
  4. Select axe MCP Server as the product
  5. Enter a descriptive name for your API key
  6. Click Save
  7. Copy the generated API key for use in the next step

Option B: OAuth 2.0

Option B is OAuth 2.0 authentication via the @deque/axe-auth CLI. See OAuth 2.0 Authentication for setup instructions.

note

When running npx @deque/axe-auth login for the first time, your operating system may prompt you to grant keychain access so that tokens can be stored securely.

note

Set either AXE_API_KEY or AXE_ACCESS_TOKEN — not both. The server will fail at startup if both variables are set.

Step 2: Pull the Docker Image

Initially and any time an updated version is released that you would like to use, you will have to docker pull the axe MCP Server image:

docker pull dequesystems/axe-mcp-server:latest

Step 3: Configuration

Choose your IDE for specific setup instructions:

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.

To ensure your AI coding agent uses the axe MCP Server tools correctly and follows accessibility best practices, you can provide it with custom instructions. These instructions help the agent understand the proper workflow for analyzing and remediating accessibility issues.

Where to Add Instructions

The method varies by client:

  • VS Code with GitHub Copilot - Add to .github/copilot-instructions.md in your project root
  • Cursor - Add to "Cursor Rules" in settings
  • Claude Code - Add to a CLAUDE.md file in your project root
  • Claude Desktop - Add to custom instructions in settings
  • Other MCP clients - Consult your client's documentation for custom instruction configuration

Example Workflow Instructions

Below is a recommended template you can adapt for your agent:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- First use `remediate` tool for EACH violation found
- Provide the exact HTML element, rule ID, and issue description
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. For each violation: remediate → Get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Why This Matters

These instructions ensure your agent:

  • Uses Deque's expertise - Leverages AI models trained on decades of accessibility assessment data instead of general LLM knowledge
  • Follows best practices - Applies consistent, WCAG-compliant fixes rather than generic solutions
  • Verifies changes - Always confirms fixes actually resolved the issues
  • Avoids false confidence - Doesn't assume it knows how to fix accessibility issues without expert guidance

While optional, providing these instructions significantly improves the quality and reliability of accessibility fixes in your codebase.

Configuration Options

The axe MCP Server supports several environment variables for customization:

Env var Description Default
AXE_API_KEY API key for authentication (see Option A: API Key above). Mutually exclusive with AXE_ACCESS_TOKEN.
AXE_ACCESS_TOKEN OAuth 2.0 Bearer token for authentication (see Option B: OAuth 2.0 above). Mutually exclusive with AXE_API_KEY.
AXE_SERVER_URL The base URL of your organization's axe Account Portal. Only required if your organization does not use the default shared US SaaS instance. See below for details. "https://axe.deque.com"
BROWSER_TIMEOUT_MS The number of milliseconds we'll allow browser interactions to wait before timing out 30000
LOG_LEVEL Follows the Syslog Protocol; supported values are "debug", "info", "warn", and "error" "info"

AXE_SERVER_URL

The default value (https://axe.deque.com) is correct for most users — those on Deque's shared US SaaS instance. If your organization uses any of the following, you must set AXE_SERVER_URL to your instance's base URL:

  • A regional SaaS instance (EU, Australia, Frankfurt, etc.)
  • A private cloud deployment
  • An on-premises installation

If you are unsure which instance your organization uses, check the URL you use to log into the axe Account Portal, or ask your administrator.

Set AXE_SERVER_URL explicitly in the env block of your MCP server configuration. The IDE-specific setup guides for VS Code with Copilot and Cursor include examples showing exactly where to add it.

Troubleshooting

Common Issues

Server fails to start:
  • Ensure Docker is running
  • Verify your credentials are correct: either your AXE_API_KEY or your AXE_ACCESS_TOKEN, but not both (the server fails at startup if both are set)
  • Check that you have access to the axe MCP Server (contact support if needed)
Scan timeouts:
  • Increase BROWSER_TIMEOUT_MS for complex pages
  • Ensure the target URL is accessible from your network
  • Check for network connectivity issues
ERR_CONNECTION_REFUSED when analyzing a local development server

If the analyze tool fails with a net::ERR_CONNECTION_REFUSED error while trying to scan a locally running dev server, this is likely because axe MCP Server runs inside a Docker container and cannot reach services bound only to localhost (i.e., 127.0.0.1) on your host machine.

Error example:

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Solution: Start your dev server with the --host flag set to 0.0.0.0 so it listens on all network interfaces, making it reachable from within the Docker container:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0
Authentication errors
API key
  • Verify your API key is valid and hasn't expired
  • Ensure your axe Account Portal subscription includes MCP Server access
  • Check that the API key was created for "axe MCP Server" product
  • Confirm only AXE_API_KEY is set — if AXE_ACCESS_TOKEN is also set, the server will fail at startup
  • Confirm your axe server URL is correct — if your organization uses a regional, private cloud, or on-premises axe instance, AXE_SERVER_URL must be set to your instance's base URL. See Configuration Options for details.
OAuth
  • Confirm only AXE_ACCESS_TOKEN is set — if AXE_API_KEY is also set, the server will fail at startup
  • Run npx @deque/axe-auth token in your terminal to confirm you have a valid token; if it exits with a non-zero code, re-authenticate with npx @deque/axe-auth login
  • Confirm your axe server URL is correct
  • If your token has expired mid-session, restart the MCP server connection in your IDE (e.g., restarting Claude Code, toggling the server off and on in Cursor's MCP settings, or clicking VS Code's CodeLens "Restart" button directly above the axe MCP Server entry in mcp.json) to obtain a fresh token
  • See OAuth 2.0 Authentication for full troubleshooting steps
  • Ensure Docker daemon is running
  • Check Docker permissions
  • Verify network connectivity for Docker image downloads
  • Ensure Docker has enough memory by running a docker system prune

Getting Help

If you encounter issues not covered in this troubleshooting section:

  1. Check the VS Code Developer Console for detailed error messages
  2. Review the Docker container logs for additional debugging information
  3. Contact our support team at helpdesk@deque.com with:
    • Your VS Code version
    • Docker version
    • Complete error messages
    • Steps to reproduce the issue

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 within the Docker container on your machine
  • 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 in a Docker container on your machine. It does not require broad file system access or elevated privileges beyond what Docker requires.

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?