webroot-mcp

MCP-Server für Webroot (OpenText Endpoint Security / SecureAnywhere, verwaltet über die Global Site Manager "GSM"-Konsole). Stellt die GSM-Konsolen-Sites, Endpoints, Gruppen, Richtlinien, Bedrohungsverlauf, Echtzeit-Agentenstatus und DNS Protection (DNSP)-Methoden der Webroot Unity API als MCP-Tools bereit.

Overview

• Zustandsloser HTTP-Dienst. Es werden niemals Anmeldeinformationen gespeichert – jede Anfrage liefert ihre eigenen Anmeldeinformationen über Header, die nur für die Dauer dieser einzelnen Anfrage verwendet werden.

• Unterstützt gleichzeitige Anfragen; die Isolierung der Anmeldeinformationen pro Anfrage erfolgt über Python contextvars, nicht über eine globale/ gemeinsame Client-Instanz.

• Einstiegspunkte: POST /mcp (MCP-Protokoll) und GET /health (Gesundheitsprüfung).

• Standardport: 8080 (konfigurierbar über MCP_HTTP_PORT).

Related MCP server: kaseya-vsa-mcp

Authentication

Die Webroot Unity API implementiert standardmäßiges OAuth2 unter Verwendung des Passwort-Grants:

POST https://unityapi.webrootcloudav.com/auth/token
  grant_type=password&username=...&password=...&client_id=...&client_secret=...
  &scope=Console.GSM SkyStatus.GSM
-> {"access_token": "...", "expires_in": 299, "refresh_token": "...", ...}

Das Zugriffstoken ist nur ~5 Minuten gültig, daher authentifiziert sich dieser Server bei jedem einzelnen Tool-Aufruf neu, anstatt es über MCP-Anfragen hinweg zu cachen – nichts wird gecacht oder gespeichert. Jeder echte API-Aufruf sendet dann Authorization: Bearer <access_token>.

HEADER 授权参数说明

Fehlt ein Header, wird 401 zurückgegeben:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Webroot-Username, X-Webroot-Password, X-Webroot-Client-Id, X-Webroot-Client-Secret, X-Webroot-Parent-Keycode headers",
  "required_headers": ["X-Webroot-Username", "X-Webroot-Password", "X-Webroot-Client-Id", "X-Webroot-Client-Secret", "X-Webroot-Parent-Keycode"],
  "optional_headers": []
}

Eine ungültige Anmeldeinformation erscheint als strukturierter Fehler auf Tool-Ebene (siehe „Fehlerbehandlung“ unten) während des internen Anmeldeschritts, nicht als HTTP-Fehler von diesem Server.

Environment Variables

MCP Endpoint

• POST /mcp — MCP-Protokoll (streambarer HTTP-Transport)

• GET /health — Gesundheitsprüfung, gibt {"status": "ok"} zurück (reine lokale Prüfung, hängt nicht von der Webroot-API ab)

Tool List

Alle 10 Tools sind schreibgeschützt (readOnlyHint=True); es gibt keine Schreib-/Lösch-Tools in diesem Dienst.

page_size/batch_size-Obergrenzen: Die öffentliche API-Referenz des Anbieters dokumentiert für diese Parameter auf keinem der obigen Endpunkte ein Maximum, daher wendet dieser Server seinen eigenen Standard (50) und eine harte Obergrenze (200) an, anstatt einen unbegrenzten Wert durchzureichen.

Antworten sind das JSON des Anbieters, kompakt serialisiert (keine hübsche Formatierung, ensure_ascii=False) und auf 20.000 Zeichen begrenzt – ein übermäßig großes Listenfeld wird mit truncated/original_count-Markierungen abgeschnitten, anstatt jemals einen unbegrenzten Blob zurückzugeben.

Error Handling

Fehler werden als In-Band-JSON-Umschlag zurückgegeben (eine normale Tool-Ergebniszeichenfolge, kein MCP-Protokollfehler):

{"error": {"code": "not_found", "message": "...", "retryable": false}}

code ist eines aus einem festen Vokabular: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. retryable teilt dem Aufrufer mit, ob ein erneuter Versuch desselben Aufrufs erfolgreich sein könnte (true für rate_limited/upstream_error, sonst false). Ein leeres Ergebnisset (z. B. eine Site ohne Endpoints) ist ein normales erfolgreiches Ergebnis, kein not_found-Fehler.

Ausgehende Aufrufe an die Webroot-API verwenden ein 5s-Verbindungs- / 30s-Lese-Timeout und wiederholen 429/5xx-Antworten bis zu 3 Mal mit Backoff (unter Beachtung von Retry-After, begrenzt auf 20s), wobei ein einzelner gepoolter HTTP-Client für die Prozesslebensdauer wiederverwendet wird.

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Webroot-Username: admin@example.com" \
  -H "X-Webroot-Password: <your-password>" \
  -H "X-Webroot-Client-Id: <your-client-id>" \
  -H "X-Webroot-Client-Secret: <your-client-secret>" \
  -H "X-Webroot-Parent-Keycode: <your-parent-keycode>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "webroot_get_sites",
      "arguments": {}
    }
  }'

Live-verifiziert (2026-07-30) gegen eine echte GSM-Konsole, alle 10 Tools Ende-zu-Ende über diesen laufenden Server mit echten Anmeldeinformationen aufgerufen: webroot_get_sites gab 92 echte Sites zurück (z. B. „Pinnacle Technologies“, „Hohimer Wealth Management“); webroot_get_policies gab 11 echte Richtlinien zurück; webroot_get_agent_status gab echte Statusdaten pro Gerät zurück; webroot_get_endpoints und webroot_get_groups (unter Verwendung einer echten Site-ID) gaben beide echte Daten zurück (6 Endpoints, 1 Gruppe mit 46 Geräten); webroot_get_threat_history gab ein gültiges (leeres) Ergebnis für einen echten 2-Monats-Zeitraum zurück. Die 4 DNS Protection-Tools (webroot_get_dnsp_categories/_block_reasons/_traffic_summary/_blocked_traffic) erreichten alle korrekt die API und gaben den eigenen dnsp_not_enabled-Fehler des Anbieters zurück – was beweist, dass die Anfrage-/Authentifizierungspipeline korrekt ist; DNS Protection ist für die GSM-Konsole dieses speziellen Testkontos einfach nicht aktiviert (siehe Bekannte Lücken).

API Reference

• Öffentlich, keine Anmeldung erforderlich: https://unityapi.webrootcloudav.com/Docs/en/APIDoc (Leitfaden behandelt die OAuth2-Authentifizierung vollständig; API-Referenz behandelt die Parameter und Antwortform jedes Methodenaufrufs)

Known Gaps

• Der Umfang entspricht genau den 10 konfigurierten Endpunkten von MSPbots, nicht der vollständigen API-Oberfläche des Anbieters – die Unity API deckt auch ECom (Lizenzbestellung/-verwaltung), Benachrichtigungen, Agentenbefehle, Site-Erstellung/-Bearbeitung und die OpenText Secure Cloud Platform API ab; diese sind hier nicht im Umfang enthalten.

• Die 4 DNS Protection (DNSP)-Tools konnten nicht mit echten Daten verifiziert werden – DNS Protection ist ein Add-on-Produkt, das für die GSM-Konsole des Testkontos nicht aktiviert ist (dnsp_not_enabled-Fehler, live bestätigt). Die anderen 6 Tools funktionierten mit echten Daten unter Verwendung desselben Zugriffstokens, was bestätigt, dass dies eine Kontofunktionslücke ist, kein Implementierungsfehler.

• webroot_get_endpoints/webroot_get_groups/webroot_get_threat_history erfordern eine site_id, auf die der authentifizierte GSM-Benutzer tatsächlich Zugriff hat – Webroot GSM-Zugriff ist pro Site; der Versuch, diese Aufrufe gegen eine Site auszuführen, für die der Benutzer keinen Zugriff hat, gibt einen sauberen "User does not have access to this console"-Fehler zurück (live bei einer der 92 Sites während des Tests beobachtet), kein Fehler in diesem Server.

• webroot_get_threat_history lehnt Datumsbereiche über 3 Monate ab (Invalid data entered - Date Range Over 3 Months, live bestätigt) – dieser Server erzwingt oder teilt den Bereich nicht automatisch; er reicht start_date/end_date unverändert durch.