Setup in Claude Code

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

Before configuring, choose a distribution (Docker or npm) and set up authentication (API key or OAuth 2.0). Then add the matching configuration below.

Axe MCP server can be added at either the project or user level:

  • Project-level: Create a file at .mcp.json in your project's root directory (best for sharing settings with a team)
  • User-level: Add the server to the mcpServers object in ~/.claude.json in your home directory (applies across all of your projects). You can also manage user-level servers with the claude mcp add --scope user command — see the Claude Code MCP documentation for details.
info

If you already have other servers defined, add the axe-mcp-server block inside the existing mcpServers object.

Docker

API key

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--add-host=host.docker.internal:host-gateway",
        "-i",
        "--rm",
        "-e",
        "AXE_SERVER_URL",
        "-e",
        "AXE_API_KEY",
        "dequesystems/axe-mcp-server:latest"
      ],
      "env": {
        "AXE_SERVER_URL": "https://axe.deque.com",
        "AXE_API_KEY": "${AXE_API_KEY}"
      }
    }
  }
}

The configuration uses "AXE_API_KEY": "${AXE_API_KEY}" for secure input handling. The ${AXE_API_KEY} syntax instructs Claude Code to pull the value from your shell environment. For more information, see the Claude Code MCP documentation.

Set your API key as an environment variable in your shell:

export AXE_API_KEY="your-api-key-here"

For permanent setup, add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

note

Using a regional, private cloud, or on-premises axe instance? Update the AXE_SERVER_URL value in the env block with your instance's base URL:

"env": {
  "AXE_API_KEY": "${AXE_API_KEY}",
  "AXE_SERVER_URL": "https://your-axe-instance.example.com"
}

If omitted, the server defaults to https://axe.deque.com (Deque's shared US SaaS instance). See Configuration Reference for details.

OAuth 2.0

Before configuring, complete Step 1: Authenticate in the Authentication guide.

This uses @deque/axe-auth token to obtain a fresh access token each time the server starts.

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "docker run --add-host=host.docker.internal:host-gateway -i --rm -e \"AXE_ACCESS_TOKEN=$(npx -y @deque/axe-auth token)\" dequesystems/axe-mcp-server:latest"
      ]
    }
  }
}
note

Using a regional, private cloud, or on-premises axe instance? Add AXE_SERVER_URL to the Docker command and an env block with your instance's base URL:

"args": [
  "-c",
  "docker run --add-host=host.docker.internal:host-gateway -i --rm -e AXE_SERVER_URL -e \"AXE_ACCESS_TOKEN=$(npx -y @deque/axe-auth token)\" dequesystems/axe-mcp-server:latest"
],
"env": {
  "AXE_SERVER_URL": "https://your-axe-instance.example.com"
}

If omitted, the server defaults to https://axe.deque.com (Deque's shared US SaaS instance). See Configuration Reference for details.

note

This configuration uses sh -c to allow shell substitution. $(npx -y @deque/axe-auth token) runs at server startup and injects a valid access token into the Docker container. The -y flag skips the first-run "Ok to proceed?" prompt that npx would otherwise ask in a non-interactive shell. Do not set AXE_API_KEY alongside AXE_ACCESS_TOKEN.

caution

Windows users: This configuration uses a POSIX shell (sh) and command substitution ($(...)), which is not available in cmd.exe or PowerShell by default. Run your editor from a Git Bash or WSL shell so that sh is on your PATH.

npm

The npm distribution runs on Node.js. Use an active Node.js LTS release — older releases may not be supported.

The npm distribution needs a Chromium browser — either install one via Playwright or point at an existing binary. See Choosing a Distribution.

API key

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "axe-mcp-server"],
      "env": {
        "AXE_API_KEY": "${AXE_API_KEY}"
      }
    }
  }
}

Set AXE_API_KEY in your shell as shown above so Claude Code can pull it from the environment.

OAuth 2.0

OAuth 2.0 is supported with the npm distribution as well — set AXE_ACCESS_TOKEN instead of AXE_API_KEY, injecting a fresh token from @deque/axe-auth token at startup. See Authentication for the full flow.

note

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

Usage and verification

Once configured, restart Claude Code to load the MCP server.

  1. Launch Claude Code from your terminal: claude
  2. Type /mcp to manage MCP server connections
  3. You should see axe-mcp-server listed with the analyze, remediate, and igt tools available

To ensure Claude Code uses the axe MCP Server tools correctly, add the recommended analyze-then-remediate workflow instructions to a CLAUDE.md file in your project root. See Configuring Your AI Agent for the full template.

Is this page helpful?

Help us improve this page

Still need help?