Setup in Claude Code

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.

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

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

OAuth 2.0

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

Launch the server through @deque/axe-auth run, which keeps the running server's access token fresh for as long as the session lasts.

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@deque/axe-auth",
        "run",
        "--",
        "docker",
        "run",
        "--add-host=host.docker.internal:host-gateway",
        "-i",
        "--rm",
        "-p",
        "127.0.0.1:9223:9223",
        "-e",
        "AXE_ACCESS_TOKEN",
        "-e",
        "AXE_TOKEN_REFRESH_PORT",
        "-e",
        "AXE_TOKEN_REFRESH_SECRET",
        "-e",
        "AXE_TOKEN_REFRESH_HOST=0.0.0.0",
        "dequesystems/axe-mcp-server:latest"
      ],
      "env": {
        "AXE_TOKEN_REFRESH_PORT": "9223"
      }
    }
  }
}

npx -y @deque/axe-auth run launches the container and supervises it for the life of the session, pushing a freshly minted access token to the running server before the current one expires. Your refresh token never leaves your machine — only short-lived access tokens reach the server. The -y flag skips the first-run "Ok to proceed?" prompt that npx would otherwise ask in a non-interactive shell.

The remaining flags exist to make that push reachable inside the container:

• -p 127.0.0.1:9223:9223 publishes the server's refresh listener on host loopback only, keeping it off your machine's external interfaces.
• -e AXE_ACCESS_TOKEN, -e AXE_TOKEN_REFRESH_PORT, and -e AXE_TOKEN_REFRESH_SECRET forward the values run generates into the container. Pass the names alone, with no =value — run supplies them.
• -e AXE_TOKEN_REFRESH_HOST=0.0.0.0 binds the listener to the container's network interface. A published port forwards there rather than to the container's loopback, so the default loopback bind would be unreachable. The shared secret, not container isolation, is what guards the endpoint.

9223 is an example — any free port on your machine works, as long as AXE_TOKEN_REFRESH_PORT and the -p publish name the same one. See Token refresh variables for the full reference.

"args": [
  "-y",
  "@deque/axe-auth",
  "run",
  "--",
  "docker",
  "run",
  "--add-host=host.docker.internal:host-gateway",
  "-i",
  "--rm",
  "-p",
  "127.0.0.1:9223:9223",
  "-e",
  "AXE_SERVER_URL",
  "-e",
  "AXE_ACCESS_TOKEN",
  "-e",
  "AXE_TOKEN_REFRESH_PORT",
  "-e",
  "AXE_TOKEN_REFRESH_SECRET",
  "-e",
  "AXE_TOKEN_REFRESH_HOST=0.0.0.0",
  "dequesystems/axe-mcp-server:latest"
],
"env": {
  "AXE_TOKEN_REFRESH_PORT": "9223",
  "AXE_SERVER_URL": "https://your-axe-instance.example.com"
}

npm

The npm distribution runs on Node.js and requires 22.19.0 or later. An active Node.js LTS release satisfies this, but an older Node 22 patch release may not.

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. Wrap the server in @deque/axe-auth run exactly as above — there is no container to publish a port into, so the command is shorter:

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@deque/axe-auth",
        "run",
        "--",
        "npx",
        "-y",
        "axe-mcp-server"
      ],
      "env": {
        "AXE_TOKEN_REFRESH_PORT": "9223"
      }
    }
  }
}

npx -y @deque/axe-auth run launches the server and supervises it for the life of the session, pushing a freshly minted access token to the running process before the current one expires. No port publish is needed here: the wrapped process inherits AXE_TOKEN_REFRESH_PORT directly and the listener stays on loopback. 9223 is an example — any free port on your machine works, and the variable is optional here: omit it and run picks a free port for the session.

See Authentication for the full flow.

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

Configuring Claude Code (recommended)

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.