WatchGuard Cloud

WatchGuard Cloud MCP Server

AI アシスタントおよび WYRE Conduit ゲートウェイ向けの、WatchGuard Cloud の REST API 用 MCP サーバーです。MSP アカウントの管理、デバイス／ライセンスの有効化、オペレーター（ユーザー）の管理に対応しています。

認証

WatchGuard Cloud で API アクセスを有効にすると（Account Settings > API Access）、独立した 2 つの認証情報が発行されます。

1. AccessID/Password のペアです。POST /oauth/token（grant_type=client_credentials、HTTP Basic 認証）で、有効期間の短い（1 時間）OAuth アクセストークンと交換します。このサーバーは、その交換処理と有効期限切れ時の更新処理を内部で行います。
2. OAuth ベアラートークンとともに、すべてのリクエストで専用のヘッダーとして送信する、別個の WatchGuard-API-Key です。

呼び出し元が指定する必要があるのは、以下の有効期間の長い 3 つの値だけです。有効期間の短いアクセストークンは必要ありません。

設定

.env.example をコピーし、以下の変数を設定します。このファイルの CONDUIT_S2S_SECRET は空のままにしてください。

環境変数	説明
WATCHGUARDCLOUD_ACCESS_ID	WatchGuard Cloud API Access の AccessID です。stdio および AUTH_MODE=env で必須です。
WATCHGUARDCLOUD_PASSWORD	AccessID に対応するパスワードです。stdio および AUTH_MODE=env で必須です。
WATCHGUARDCLOUD_API_KEY	API アクセスの有効化時に生成された WatchGuard-API-Key です。stdio および AUTH_MODE=env で必須です。
WATCHGUARDCLOUD_REGION	usa（デフォルト）、deu（EMEA）、または jpn（APAC）です。アカウントのデータ保存リージョンを指定します。
MCP_TRANSPORT	stdio（デフォルト）または http です。
AUTH_MODE	env（デフォルト。上記の変数を読み込みます）または gateway（Conduit ゲートウェイによって挿入される X-WatchGuardCloud-* ヘッダー経由で、リクエストごとに認証情報を受け取ります）。コンテナーイメージと Compose では gateway が設定されます。ゲートウェイモードでは、WATCHGUARDCLOUD_* へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP トランスポートの起動に必須です。空の場合、または既知のプレースホルダー（changeme、your-s2s-secret、secret、placeholder、その他のサンプル値）の場合、プロセスはエラーをログに記録して、ゼロ以外の終了コードで終了します。未設定の場合、Compose は起動しません。実際の値をコミットしないでください。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S を検証せず、127.0.0.1 のみでバインドします。このモードでは、0.0.0.0 を含むループバック以外の MCP_HTTP_HOST は無視されます。プレースホルダーのシークレットは引き続き拒否されます。
MCP_HTTP_HOST	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定の場合、従来のデフォルト値 0.0.0.0 が使用されます。コンテナーイメージと Compose では 0.0.0.0 が設定されます。実際のシークレットがない場合、リスナーは 127.0.0.1 のみで待ち受けます。
MCP_HTTP_PORT	HTTP ポートです。デフォルトは 8080 です。
LOG_LEVEL	debug | info（デフォルト）| warn | error です。

/health は認証不要のままで、ベンダーの認証情報を読み込みません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http かつ実際の CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 は、CONDUIT_S2S_SECRET をキーとして、リテラル文字列 t=<unix seconds> の HMAC-SHA256 を 16 進数で表したものです。ヘッダーがない場合、または無効な場合は 401 を返します。タイムスタンプはサーバー時刻の前後 5 分以内でなければなりません。

ゲートウェイは、各 /mcp 呼び出しに署名します。

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${sig}" \
  -H "X-WatchGuardCloud-Access-ID: $WATCHGUARDCLOUD_ACCESS_ID" \
  -H "X-WatchGuardCloud-Password: $WATCHGUARDCLOUD_PASSWORD" \
  -H "X-WatchGuardCloud-API-Key: $WATCHGUARDCLOUD_API_KEY" \
  -H "X-WatchGuardCloud-Region: usa" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp では X-WatchGuardCloud-Access-ID、X-WatchGuardCloud-Password、X-WatchGuardCloud-API-Key も必要です（X-WatchGuardCloud-Region は省略可能です）。これら 3 つのいずれかが欠けているリクエストは 401 を返します。そのリクエストの認証情報は、これらのヘッダーからのみ取得されます。

AUTH_MODE=env でも、有効な X-Gateway-S2S ヘッダーが必要です。その後、プロセス環境から WATCHGUARDCLOUD_* を使用します。

リクエスト制限

• HTTP リクエストボディは 256 KiB（262144 バイト）に制限されています。X-Gateway-S2S のチェックが通過した後、Content-Length が上限を超えている場合は、JSON-RPC エラーとともに 413 が返されます。Content-Length のないボディは、MCP SDK のトランスポートによって制限されます。認証されていないリクエストには、引き続き最初に 401 が返されます。
• tools/call の引数は 10,000 個の要素（すべての配列項目と、あらゆる深さにあるオブジェクトのキー）に制限されています。これを超える入力には isError ツール結果が返され、ディスパッチされません。

これらの制限は、CVE-2026-111768 / GHSA-46jr-4wx8-v453（検証中のメモリ枯渇）と GHSA-f897-62hf-6gxq（リクエストボディ／バッチの上限がないこと）への対策です。

ツール

アカウント

• watchguardcloud_get_account - アカウントの詳細を取得します。
• watchguardcloud_create_account - 管理対象（子）アカウントを作成します。
• watchguardcloud_update_account - 管理対象アカウントの名前／主要連絡先を更新します。
• watchguardcloud_delete_account - 管理対象アカウントを削除します。
• watchguardcloud_list_managed_accounts - あるアカウントが管理する（委任された）アカウントを一覧表示します。

アクティベーション

• watchguardcloud_create_activation - アクティベーションキーを使って、Firebox／ハードウェアデバイスまたは SaaS ライセンスを有効化します。
• watchguardcloud_list_recent_activations - およそ過去 30 日間のアクティベーションバッチを一覧表示します。
• watchguardcloud_get_activation_status - アクティベーションバッチ内の各項目のステータスを取得します。

オペレーター管理

• watchguardcloud_create_operator - 権限ロールを指定してオペレーター（ユーザー）アカウントを作成します。
• watchguardcloud_update_operator - オペレーターの名前／電話番号／ロールを更新します。
• watchguardcloud_delete_operator - オペレーターアカウントを削除します。
• watchguardcloud_get_operator_transaction_status - 非同期の作成／更新／削除処理の結果をポーリングします。
• watchguardcloud_list_operators - アカウントのすべてのオペレーターと、そのロール／MFA ステータスを一覧表示します。

対象範囲

これは、WatchGuard Cloud プラットフォーム API のうち、最も詳細に文書化されている 3 つ（アカウント、アクティベーション、オペレーター管理）を対象とする v1 の機能です。現時点で明示的に対象外としているのは、Firebox デバイスの設定／管理と Endpoint Security ポリシー管理です。どちらも別個の WatchGuard API として存在しますが、執筆時点では、確信を持って実装できるほど具体的なリクエスト／レスポンスの詳細が公開ドキュメントにありません。より詳細なドキュメントが整い次第、追加できます。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

CONDUIT_S2S_SECRET に実際のシークレットが設定されていないと、HTTP は起動しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

サービス間シークレットを使わないローカル HTTP は、開発専用です。127.0.0.1 にバインドし、警告をログに記録します。

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトで AUTH_MODE=gateway に設定されます。ポートをループバックで公開し、S2S シークレットを渡してください。ゲートウェイモードでは、WatchGuard の認証情報はリクエストごとにヘッダーとして渡され、環境変数からは読み取られません。

docker build -t watchguard-cloud-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  watchguard-cloud-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE=gateway を設定して、127.0.0.1:8080:8080 を公開します。また、ベンダーの静的な認証情報は注入しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。そのうえで、WATCHGUARDCLOUD_ACCESS_ID、WATCHGUARDCLOUD_PASSWORD、WATCHGUARDCLOUD_API_KEY を使用します。これはゲートウェイ Compose サービスとは別の構成です。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e WATCHGUARDCLOUD_ACCESS_ID="$WATCHGUARDCLOUD_ACCESS_ID" \
  -e WATCHGUARDCLOUD_PASSWORD="$WATCHGUARDCLOUD_PASSWORD" \
  -e WATCHGUARDCLOUD_API_KEY="$WATCHGUARDCLOUD_API_KEY" \
  -e WATCHGUARDCLOUD_REGION=usa \
  -p 127.0.0.1:8080:8080 \
  watchguard-cloud-mcp