設定リファレンス

このページでは、Axe MCPサーバーが読み込む環境変数と、AIエージェントのための推奨カスタム指示について記載しています。これらは両方に適用されますDockerおよびnpmディストリビューション。これらの値をどこに配置するかは、クライアントセットアップガイドを参照してください。

設定オプション

Axe MCPサーバーは、カスタマイズ用にいくつかの環境変数をサポートしています：

AXE_SERVER_URL

デフォルト値（https://axe.deque.com）は、Deque の共有 US SaaS インスタンスを使用しているほとんどのユーザーに適しています。次のいずれかを使用している場合、AXE_SERVER_URLをインスタンスの基礎 URL に設定する必要があります：

• （EU、オーストラリア、フランクフルトなど）（EU、オーストラリア、フランクフルトなど）
• オンプレミス デプロイメント
• 明示的に設定します インストール

どのインスタンスを組織が使用しているか不明な場合、Axeアカウントポータルにログインするために使用しているURLを確認するか、管理者に問い合わせてください。

MCP サーバー構成の env ブロックに AXE_SERVER_URL を明示的に設定します。クライアントセットアップガイド にはそれを正確に追加する場所を示す例が含まれています。

AXE_CHROME_PATH

npm配布のみ。 これは Docker ではサポートされていません。Docker は常にバンドルされたブラウザを使用するため、AXE_CHROME_PATH が Docker 配布に設定されている場合、サーバーは起動に失敗します。

デフォルトでは、npm 配布はPlaywrightを通してインストールした Chromium ビルドを使用します。AXE_CHROME_PATH を既存の Chrome/Chromium バイナリの完全なパスに設定して、その代わりにそれを使用し、Playwright のインストールをスキップします。

• その値は 実行可能なバイナリファイル でなければならず、.app バンドルやディレクトリではありません。例として、macOS ではバンドル内のバイナリを指定します：/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing。
• バイナリは存在しなければならず、macOSおよびLinuxでは--versionを起動して応答する必要があります。サーバーは起動時にこれを確認し、できない場合はファイルが実行可能でない、またはシステムライブラリが欠けているなどの理由でメッセージとともに停止します。Windowsでは、サーバーはファイルが存在するかどうかのみを確認するため、起動できないバイナリは最初のスキャンが始まるときに失敗します。
• ブランド化されたGoogle Chrome 137以降はサポートされません。 テスト用Chrome またはその他の Chromium 互換バイナリを使用します。

analyze と igt ツールは、呼び出しごとに設定可能な chromePath 引数も受け入れます。これはその呼び出しでAXE_CHROME_PATHより優先されます。

AXE_ADVANCED_RULES

サーバーが実行するすべてのスキャンに対して高度なルール信頼プリセットを設定し、組織のAxe設定のデフォルトを上書きします—ただし、管理者がユーザーに設定変更を許可している場合に限ります。

受け入れられる値は"precise"（または"90%"）、"balanced"（または"70%"）、"thorough"（または"50%"）、および"disabled"です。値は大文字小文字を区別しません。

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

analyzeツールは、advancedRules引数をコールごとに受け入れることもでき、これがそのコールに対してAXE_ADVANCED_RULESよりも優先されます。管理者が設定をロックしている場合、どちらも無視され、組織のプリセットが優先されます。完全な優先順位ルールとadvancedRules応答ブロックについては、高度なルールを参照してください。

AXE_SCREENSHOT_DIR

Sets the directory the analyze tool writes screenshots into when a call passes screenshot.save without an explicit path. It has no effect on calls that set screenshot.saveTo, which always wins, and none on calls that don't save at all.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

相対パスはサーバーの作業ディレクトリを基準として解決されます。デフォルトはオペレーティングシステムの一時ディレクトリです。

トークンリフレッシュ変数

これらはOAuth 2.0のみに適用され、実行中のサーバーが新たに更新されたアクセストークンを受け入れることができるようにし、トークンを超えたセッションが再起動せずに済むようにします。リスナーはデフォルトではオフで、AXE_TOKEN_REFRESH_PORTおよびAXE_TOKEN_REFRESH_SECRETが設定されている場合にのみ開始されます。

通常、これらを手動で設定することはありません。@deque/axe-auth runがサーバーを監視し、それらを提供します — ポートを選択すれば、シークレットが生成されます。

リフレッシュトークンはサーバーに送信されません — 短命のアクセストークンのみが渡され、共有シークレットがエンドポイントを守ります。完全なDockerおよびnpm設定については長時間のセッションを維持するを参照してください。

IGT_TIMEOUT_MS

テスト開始の瞬間から結果が返ってくる瞬間まで測定された、1回のインテリジェントガイドテスト実行を制限します。それはanalyze呼び出しとigtToolsに合格した呼び出し、および廃止予定のigt ツールに適用されます。

テストはAIによって駆動され、ページのインタラクティブ要素を一度に1つずつ処理するため、スキャンよりもはるかに長時間実行されます。そのためのデフォルトサイズが大きく、BROWSER_TIMEOUT_MSよりもはるかに大きくなっています。予算を超えた実行は、予算を超えたことを知らせるエラーと共に失敗します:

IGT timed out after 200000ms

エラーはテストが到達した最後のステップとその時点からどのくらい経ったかも示し、それにより進行中であったのか停止していたのかが分かります。

IGT timed out after 200000ms (last checkpoint: keyboard:tabstops:start 83s ago; last step: analyze-tabstops-ai 61s ago; last tick 2s ago)

ページに十分なインタラクティブ要素があり、余分な時間が必要な場合はIGT_TIMEOUT_MSを増やしてください。BROWSER_TIMEOUT_MSを増やしても役立ちません。このページのすべてのタイムアウトは独自の予算であり、テストが始まる前にスキャンはすでに終了しています。

{
  "env": {
    "IGT_TIMEOUT_MS": "400000"
  }
}

プロキシ変数

Zscalerのように、ネットワークからのアウトバウンドトラフィックがプロキシを通過する必要がある場合、プロキシの完全なURLを設定すると、サーバーはスタートアップ、APIキーのチェック、修復を含め、すべてのリクエストをaxeサーバー経由で送信します。

小文字の綴り（https_proxy、http_proxy、no_proxy）も機能し、両方が設定されている場合は小文字の方が優先されます。

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NO_PROXY": "intranet.example.com"
  }
}

• スキャンブラウザは、サーバーのaxeサーバーへのリクエストと同じプロキシを使用します。 スキャンするイントラネットサイトをNO_PROXYにリストしてください。
• npm配布: ローカルアドレス（localhost、*.localhost、127.0.0.0/8、および[::1]）は常に直接接続されるため、ローカル開発サーバーのスキャンには影響ありません。
• Docker配布: サーバーはlocalhost URLをDockerホストのアドレスに書き換えます（ローカル開発サーバースキャンを参照）、これはコンテナ内ではローカルアドレスではありません。そのアドレスをNO_PROXYに追加して、これらのスキャンが直接接続できるようにします。サーバーは、localhost ページをスキャンするたびに、書き換えられたURLをRewriting localhost URL using resolved IP of docker hostの下にログします。
• スキャンブラウザは、ユーザー名とパスワードを必要とするプロキシを使用できません。 プロキシURLに認証情報が含まれている場合、サーバーは警告をログに記録します。
• URLは完全なhttp://またはhttps:// URLでなければなりません。 サーバーがAXE_SERVER_URLに使用するプロキシがそうでない場合、サーバーは起動時に変数名を挙げたメッセージとともに停止します。デフォルトのhttps:// axeサーバーでHTTP_PROXYのように、サーバーが使用しないプロキシ変数は無視されます。
• プロキシがTLSトラフィックを検査する場合、 NODE_EXTRA_CA_CERTSをプロキシのCA証明書のパスに設定します。

Docker配布の場合、これらを-eを使用してコンテナに渡し、AXE_API_KEYと同じ方法で行います。

OAuth 2.0対応のプロキシ

OAuth 2.0を使用する場合、@deque/axe-auth CLIがサインインしてトークンをリフレッシュするにはプロキシも必要です。Node.jsがリクエストをプロキシ経由で送信できるように、NODE_USE_ENV_PROXY=1をHTTPS_PROXYと一緒に設定します。これにはNode.js 22.21以降が必要です。

axe-auth runを通してサーバーを起動するとき、同じenvブロックに追加してください。

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NODE_USE_ENV_PROXY": "1"
  }
}

axe-auth loginを自分で実行する場合、最初に同じターミナルで両方の変数を設定します。

NODE_EXTRA_CA_CERTS

ネットワークが内部CAまたはTLSトラフィックを検査するプロキシを使用している場合、NODE_EXTRA_CA_CERTSを組織のCA証明書を含むPEMファイルのパスに設定します。サーバーはすべてのプラットフォームでこれを読み取り、ファイルが解析されるとそのCAを信頼しますので、axeサーバーへの自分のリクエストがそれを信頼します。

スキャンブラウザもCAを信頼するかどうかはプラットフォームに依存します。

• Docker — 自動的に機能します。コンテナに証明書をマウントし、変数がそれを指すようにします。

  {
    "mcpServers": {
      "axe-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "AXE_API_KEY",
          "-e",
          "NODE_EXTRA_CA_CERTS=/certs/ca.pem",
          "-v",
          "/path/to/your/ca.pem:/certs/ca.pem:ro",
          "dequesystems/axe-mcp-server"
        ],
        "env": {
          "AXE_API_KEY": "<your-api-key>"
        }
      }
    }
  }

• Linux上のnpm — certutilがインストールされていると自動的に機能します（Debian/Ubuntu上のlibnss3-tools、RHEL/Fedora上のnss-tools）。インストールされていない場合、サーバーはブラウザの信頼なく起動し、警告をログに記録します。CAはサーバーが終了した後も、そのマシン上のChromiumで信頼され続けます。

• macOSおよびWindows上のnpm — CAを手動でログインキーチェーン（macOS）または現在のユーザートラストルートストア（Windows）に追加し、SSL専用で信頼するようにします。サーバーは起動時にどのストアを使用するかをログに記録します。

LinuxおよびDockerでは、ファイル内の最初の証明書のみがブラウザに追加されるため、NODE_EXTRA_CA_CERTSをサイトのチェーンにある単一のCAに向けます。

サーバーは起動時にのみNODE_EXTRA_CA_CERTSを読み取り、変数を設定または変更した後は再起動する必要があります。スキャンがまだ失敗する場合は、信頼されていない証明書を参照してください。

NODE_TLS_REJECT_UNAUTHORIZED

NODE_TLS_REJECT_UNAUTHORIZEDを"0"に設定すると、サーバーとスキャンブラウザの両方で証明書チェックが無効になります。これはNODE_EXTRA_CA_CERTSがオプションでない場合に対する最後の手段であり、自己署名証明書を持つサイトに対するクイックローカルテスト時などに使用されます。

{
  "env": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Docker配布の場合、これを-e NODE_TLS_REJECT_UNAUTHORIZED=0を使用してコンテナに渡します。

段階的選択変数

これらはインタラクティブ要素IGT段階的選択に適用されます。最初の呼び出しはランを一時停止し、エージェントが2回目の呼び出しを行うまでブラウザーを開いたままにします。したがって、これらは一時停止の待機時間と一度に開けるブラウザーの数を制限します。

定期的に要素の長いリストをレビューするのに3分以上必要な場合はSELECTION_SESSION_TTL_MSを引き上げてください。両方の値は正の整数でなければならず、そうでない場合はサーバーは起動しません。

{
  "env": {
    "SELECTION_SESSION_TTL_MS": "600000"
  }
}

AXE_PAGE_LOAD_DELAY_MS

上記の変数とは異なり、これはタイムアウトではありません。ナビゲーションが完了した後、before アクションの実行前とスキャンの前にサーバーが常に待つ固定の遅延です。読み込んだ後もレンダリングを続け、信頼できる待ち条件がないページに対応するために存在します。このサーバーが実行するすべてのスキャンはこの遅延を完全に負担するため、遅延を小さく保ってください。

{
  "env": {
    "AXE_PAGE_LOAD_DELAY_MS": "2000"
  }
}

ページが落ち着いた後にのみ存在する要素を指定できるanalyzeツールのbefore配列内でwaitFor ステップを推奨します。waitForはその要素が現れる瞬間に続行するため、より信頼性が高く、通常は包括的な遅延よりも迅速です。

AIエージェントの設定 (推奨)

AIコーディングエージェントがAxe MCPサーバーツールを正しく使用し、アクセシビリティのベストプラクティスに従うようにするために、カスタム指示を提供することができます。これらの指示は、エージェントがアクセシビリティ問題を分析し、修正するための適切なワークフローを理解するのを助けます。

指示を追加する場所

方法はクライアントによって異なります：

• VS CodeとGitHub Copilot - プロジェクトのルートに .github/copilot-instructions.md を追加します
• カーソル - 設定の「カーソルルール」に追加します
• クロードコード - プロジェクトのルートにある CLAUDE.md ファイルに追加します
• クロードデスクトップ - 設定でカスタム指示に追加します
• 他のMCPクライアント - カスタム指示設定についてはクライアントのドキュメントを参照してください

ワークフロー指示の例

以下は、エージェントに適応できる推奨テンプレートです：

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

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- 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. remediate → Pass ALL violations in one batched call to 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

なぜこれが重要なのか

これらの指示は、エージェントが以下を保証します：

• Dequeの専門知識を活用する - 一般的な LLM 知識の代わりに、何十年にもわたるアクセシビリティ評価データで訓練された AI モデルを活用します
• ベストプラクティスに従う - 一般的な解決策ではなく、一貫性のある WCAG に準拠した修正を適用します
• 変更を検証 - 修正が実際に問題を解決したことを常に確認します
• 誤った自信を避ける - 専門家の指導なしにアクセシビリティの問題を解決する方法を知っていると仮定しません

任意ではあるが、これらの指示を提供することで、コードベース内のアクセシビリティ修正の品質と信頼性が大幅に向上します。