認証

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

axe MCPサーバーは2つの認証方法をサポートしています。どちらも全てのユーザーが利用可能で、ワークフローに合った方法を選択してください。

  • APIキー — axeアカウントポータルで生成された長期間使用可能なキー。最も簡単なセットアップです。
  • OAuth 2.0 — ブラウザーベースのログイン、@deque/axe-auth CLIを介し、トークンはOSのキーチェーンに保存され、自動で更新されます。

選択した認証情報をクライアントセットアップガイドで設定します。各セットアップページには、APIキーとOAuthの設定が並んで表示されます。

note

AXE_API_KEYかAXE_ACCESS_TOKENのどちらか一方を設定してください。両方の変数を設定すると、サーバーは起動時に失敗します。

APIキー

  1. axeアカウントポータルにログインしてください
  2. APIキーのページへ移動してください
  3. 新しいAPIキーを追加をクリックしてください
  4. axe MCPサーバーを製品として選択してください
  5. APIキーの説明名を入力します
  6. 保存をクリックしてください
  7. 生成されたAPIキーをコピーします — サーバーへのAXE_API_KEY環境変数として渡します

OAuth 2.0

OAuth 2.0はPKCEを用いた認可コードフローを使用し、トークンをOSのキーチェーンに安全に保存します。これにより、1度認証を行うだけで、CLIがトークンの更新を自動で行います。

認証は@deque/axe-authによって管理されます。これはホストマシンに別途インストールするスタンドアロンのCLIです。

前提条件

  • Node.js 22.13.0 以上（サーバー自体の npm ディストリビューションは 22.19.0 以上が必要）@deque/axe-authが必要です。
  • 選択したaxe MCPサーバーディストリビューションがインストールされています — 配布版の選択をご覧ください

ステップ1: 認証

ログインコマンドを実行します。

npx @deque/axe-auth login

CLIの動作:

  1. デフォルトのブラウザを開き、ログインページを表示
  2. axeアカウントの認証情報でサインインを促す
  3. 結果のトークンをシステムキーチェーンに安全に保存
note

トークンが初めて保存される際に、OSがキーチェーンアクセスの許可を求める場合があります。

完了すると、ターミナルに確認メッセージが表示されます。

✓ Authenticated.

loginをマシンごとに一度だけ実行する必要があります。次の起動時には、npx @deque/axe-auth tokenは保存されたリフレッシュトークンを使用してアクセス・トークンを静かに更新します。

プライベートクラウド、米国外、またはオンプレミスのインストール

組織がプライベートクラウドやオンプレミスのaxeインスタンスを使用している場合、--serverでインスタンスURLを渡します（またはAXE_SERVER_URL環境変数を設定します）：

npx @deque/axe-auth login --server https://your-axe-instance.example.com

ステップ2: クライアントの設定

MCPクライアント構成で@deque/axe-auth tokenを使用して、サーバーが起動するたびに有効なアクセストークンを注入します。特定のセットアップ説明についてはクライアントを選択してください：

各セットアップページには、APIキーの指示に加えてOAuth構成セクションが含まれています。

セッションの管理

トークンの有効期間

OAuth アクセストークンは短期間で有効期限が切れます。@deque/axe-auth tokenでトークンを注入する設定は、サーバーの起動時に一度だけトークンを取得します。そのため、トークンの有効期限を超えて動作するエージェントセッションは、認証エラーを返し始めます。

これを処理する方法は2つあります。

  • 推奨 — @deque/axe-auth runの下でサーバーを実行します。これにより、トークンは自動的にセッション全体の間新鮮な状態に保たれます。
  • それ以外の場合 — クライアントで MCP サーバー接続を再起動します。設定はサーバーの起動ごとに@deque/axe-auth tokenを再実行し、新しいトークンを取得します。

長いセッションを維持する

@deque/axe-auth runは axe MCP サーバーを起動して管理し、アクセス トークンが期限切れになる前に更新します。これにより、数時間続くセッションでもトークンの期限切れに達することがなく、再起動や手動操作は不要になります。

MCP クライアントを、サーバー自体の代わりにサーバーコマンドとしてrunに向け、--の後に起動コマンドを渡します。これは、他の標準 I/O サーバーと同様にサーバープロセスのライフタイムを管理します。

npm ディストリビューション：

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

Docker ディストリビューション — ホストループバックにリフレッシュポートを公開し、認証変数をコンテナにフォワードし、その中で0.0.0.0にリスナーをバインドします：

{
  "command": "npx",
  "args": [
    "-y",
    "@deque/axe-auth",
    "run",
    "--",
    "docker",
    "run",
    "-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"
  }
}
important

DockerではAXE_TOKEN_REFRESH_HOST=0.0.0.0が必要です。 パブリッシュされたポートは、コンテナのネットワークインターフェースにフォワードされ、ループバックにはフォワードされないため、デフォルトのループバックバインドは到達不能になります。127.0.0.1:9223:9223として公開することで、エンドポイントがホストの外部インターフェースから外れ、コンテナの隔離ではなく、共有シークレットがエンドポイント自体を保護します。

note

リフレッシュトークンは決してマシンを離れません。 短命のアクセストークンのみが、セッション用にrunが生成した共通シークレットで認証されたループバック接続を介してサーバーにプッシュされます。これは、リフレッシュトークンをコンテナ外に保持するための同じ隔離プロパティです。

関与するサーバーサイドの環境変数についてはトークンリフレッシュ変数をご覧ください。

ログアウト

サーバー側でトークンを無効化し、システムキーチェーンから削除するには：

npx @deque/axe-auth logout

サーバー側の無効化が失敗した場合（たとえばネットワークエラーによる）、ローカルトークンはクリアされ警告が表示されます。

再認証

リフレッシュトークンが期限切れまたは取り消された場合、@deque/axe-auth tokenはコード1で終了し、再ログインするよう指示します。再度npx @deque/axe-auth loginを実行してください。再認証確認プロンプトをスキップするには--forceを渡します：

npx @deque/axe-auth login --force

コマンドリファレンス

login

ブラウザを開き、OAuth 2.0 Authorization Code + PKCEフローを完了し、トークンをOSキーチェーンに保存します。

npx @deque/axe-auth login [options]
フラグ 説明
--server <url> axeインスタンスのベースURL。デフォルトはhttps://axe.deque.comです。プライベートクラウド、非US地域、またはオンプレミスのインストールでのみ必要です。
--force 既にログインしている場合、再認証確認をスキップします。
--allow-insecure-issuer 非ループバックhttp URLを許可（デフォルトはhttpsのみ；ループバックhttpは常に許可されます）。loginのみに適用されます；tokenとlogoutはログイン時に保持されたポリシーを使用します。
--no-allow-insecure-issuer allowInsecureIssuer=falseを新しいlogin（およびそれが保持するエントリ）に強制します。--allow-insecure-issuerとは相互排他的です。tokenとlogoutはこのフラグを無視します。

token

現在有効なアクセストークンをstdoutに出力します。保存されたトークンが期限切れの場合、静かに更新されます。認証されていない場合、コード1で終了します。

npx @deque/axe-auth token

logout

保存されたリフレッシュトークンをサーバー側で無効化し、ローカルキーチェーンをクリアします。

npx @deque/axe-auth logout

run

axe MCPサーバーを起動して管理し、セッションのライフにわたってアクセス トークンを新鮮な状態に保ちます。手で呼び出すのではなく、MCPクライアントのサーバーコマンドとして構成してください。長いセッションを維持するを参照してください。

npx @deque/axe-auth run [options] -- <server launch command>
フラグ 説明
--port <port> サーバーにリフレッシュされたトークンをプッシュする際に使用されるループバックポート。AXE_TOKEN_REFRESH_PORTに相当します。npmの下ではオプション：それがない場合、runはセッションのための空きポートを選びます。ラップされたコマンドがコンテナランタイム（docker、podman、またはnerdctl）である場合は必須で、それは公開するポートにしか到達できません — runは固定ポートがないものを拒否します。
--secret <secret> 各プッシュを認証する共通シークレット。AXE_TOKEN_REFRESH_SECRETに相当します。値を固定しない限り自動的に生成されます。

macOS、Windows、Linux上のnpmおよびDockerディストリビューションで動作します。

--help

@deque/axe-authおよびそのコマンドに関するヘルプ情報を表示します。

npx @deque/axe-auth --help
npx @deque/axe-auth <command> --help

プラットフォームサポート

プラットフォーム トークン保管
macOS macOSキーチェーン
Windows Windowsクレデンシャルマネージャー
Linux D-Busシークレットサービス（GNOME Keyring、KWalletなど）
caution

Linux: @deque/axe-authはD-Bus Secret Serviceが動作している必要があります。ヘッドレスまたはミニマルデスクトップ環境では利用できない場合があります。以下のようなエラーが表示された場合：

System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).

システム管理者にGNOME Keyringまたは互換性のあるシークレットサービスプロバイダを設定するよう依頼してください。

OAuthのトラブルシューティング

ブラウザが自動的に開かない

loginがブラウザを開けない場合、認証URLを端末に表示します。URLをコピーして手動で開き、認証を完了してください。

長時間のセッション中のトークンの期限切れ

@deque/axe-auth runの下でサーバーを実行し、トークンを自動的に更新して問題を完全に解決します。これがない場合は、新しいトークンを取得するためにクライアントでMCPサーバー接続を再起動してください。上記のトークンの有効期間をご覧ください。

tokenからの「認証されていません」エラー

セッションが期限切れになったか、トークンがクリアされました。再認証するには再度npx @deque/axe-auth loginを実行してください。

MCPサーバーの認証エラー

  • AXE_ACCESS_TOKENのみが設定されていることを確認してください（AXE_API_KEYはされていません）
  • AXE_SERVER_URLがaxeインスタンスURLと一致していることを確認してください — これはログイン時に--serverと一緒に使用したのと同じURLである必要があります（デフォルトを使用した場合はhttps://axe.deque.com）
  • 有効なトークンを持っていることを確認するためにnpx @deque/axe-auth tokenを直接端末で実行してください
  • コード1で終了した場合、npx @deque/axe-auth loginで再認証してください

」を上記の注記を参照してください。

上記のプラットフォームサポートの記述を参照してください。

Is this page helpful?

Help us improve this page

Still need help?