Watchguard Cloud MCP Server

WatchGuard Cloud MCP Server

MCP server for WatchGuard Cloud's REST API - MSP account management, device/license activation, and operator (user) management - for AI assistants and the WYRE Conduit gateway.

Authentication

Enable API access in WatchGuard Cloud (Account Settings > API Access) to receive two independent credentials:

1. An AccessID/Password pair, exchanged for a short-lived (1-hour) OAuth access token via POST /oauth/token (grant_type=client_credentials, HTTP Basic auth). This server handles that exchange, and its refresh on expiry, internally.
2. A separate WatchGuard-API-Key, sent as its own header on every request alongside the OAuth bearer token.

Callers only ever need to supply the three long-lived values below - not the short-lived access token.

Configuration

Copy .env.example and set the variables below. Leave CONDUIT_S2S_SECRET empty in that file.

/health stays unauthenticated and does not read vendor credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and a real CONDUIT_S2S_SECRET, every /mcp request must include X-Gateway-S2S:

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

v1 is the hex HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET. A missing or invalid header returns 401. The timestamp must be within five minutes of the server clock.

The gateway signs each /mcp call:

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"}'

In AUTH_MODE=gateway, /mcp also requires X-WatchGuardCloud-Access-ID, X-WatchGuardCloud-Password, and X-WatchGuardCloud-API-Key (X-WatchGuardCloud-Region is optional). A request missing any of those three returns 401. Those headers are the only credential source for that request.

AUTH_MODE=env still requires a valid X-Gateway-S2S header, then uses WATCHGUARDCLOUD_* from the process environment.

Request limits

• HTTP request bodies are capped at 256 KiB (262144 bytes). After the X-Gateway-S2S check passes, a Content-Length above the cap returns 413 with a JSON-RPC error; bodies without Content-Length are capped by the MCP SDK transport. Unauthenticated requests still get 401 first.
• tools/call arguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return an isError tool result and are never dispatched.

These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).

Tools

Accounts

• watchguardcloud_get_account - get an account's details.
• watchguardcloud_create_account - create a managed (child) account.
• watchguardcloud_update_account - update a managed account's name/primary contact.
• watchguardcloud_delete_account - delete a managed account.
• watchguardcloud_list_managed_accounts - list accounts managed by (delegated from) an account.

Activations

• watchguardcloud_create_activation - activate a Firebox/hardware device or SaaS license by activation key.
• watchguardcloud_list_recent_activations - list activation batches from roughly the last 30 days.
• watchguardcloud_get_activation_status - per-line-item status for an activation batch.

Operator Management

• watchguardcloud_create_operator - create an operator (user) account with a privilege role.
• watchguardcloud_update_operator - update an operator's name/phone/role.
• watchguardcloud_delete_operator - delete an operator account.
• watchguardcloud_get_operator_transaction_status - poll an async create/update/delete result.
• watchguardcloud_list_operators - list every operator and its role/MFA status for an account.

Scope

This is a v1 surface covering the three best-documented WatchGuard Cloud platform APIs (account, activation, and operator management). Explicitly out of scope for now: Firebox device configuration/management and Endpoint Security policy management - both exist as separate WatchGuard APIs, but their public documentation does not (at the time of writing) carry enough concrete request/response detail to implement with confidence. They can be added as a follow-up once better-documented.

Development

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

HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

Local HTTP without a service-to-service secret is development-only. It binds 127.0.0.1 and logs a warning:

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode, WatchGuard credentials arrive on each request as headers; they are not read from the environment.

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 refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not inject static vendor credentials:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses WATCHGUARDCLOUD_ACCESS_ID, WATCHGUARDCLOUD_PASSWORD, and WATCHGUARDCLOUD_API_KEY. This is separate from the gateway Compose service:

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