axe MCP Server

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. API Key Validation - Validates the user's API key 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

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

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. API Key Validation - Validates the user's API key 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

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: Generate 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

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:

• Setup in VS Code with Copilot
• Setup in Cursor

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

Configuring Your AI Agent (Recommended)

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

### 3. 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:

Troubleshooting

Common Issues

Server fails to start:

• Ensure Docker is running
• Verify your API key is correct
• 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

Authentication errors:

• 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

Docker-related issues:

• 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:

• Technical Support: helpdesk@deque.com
• General Inquiries: helpdesk@deque.com
• Sales Questions: sales@deque.com

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 API key validation requests.

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 API key (generated in axe Account Portal; 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

• API Key Security - Store your AXE_API_KEY as an environment variable, not in code
• 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 API key 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