webroot-mcp

MCP server for Webroot (OpenText endpoint security / SecureAnywhere, managed via the Global Site Manager "GSM" console). Exposes the Webroot Unity API's GSM console sites, endpoints, groups, policies, threat history, real-time agent status, and DNS Protection (DNSP) methods as MCP tools.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own credentials via headers, used only for the lifetime of that single request.
• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.
• Entry points: POST /mcp (MCP protocol) and GET /health (health check).
• Default port: 8080 (configurable via MCP_HTTP_PORT).

Authentication

The Webroot Unity API implements standard OAuth2, using the password grant:

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": "...", ...}

The access token is valid only ~5 minutes, so this server re-authenticates fresh on every single tool call rather than caching it across MCP requests — nothing is cached or persisted. Every real API call then sends Authorization: Bearer <access_token>.

HEADER 授权参数说明

Header	类型	是否必填	默认值	枚举值	字段描述	Example
X-Webroot-Username	string	是	无	无	GSM 控制台账号邮箱	admin@example.com
X-Webroot-Password	string	是	无	无	对应密码	••••••••
X-Webroot-Client-Id	string	是	无	无	Unity API Client ID（需联系 Webroot 申请）	client_abc123@example.com
X-Webroot-Client-Secret	string	是	无	无	Unity API Client Secret	a1B2c3D4%e5F6
X-Webroot-Parent-Keycode	string	是	无	无	GSM 控制台的 Parent Key Code	AB12-GSMT-3456-CD78-9EF0

Missing any header returns 401:

{
  "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": []
}

An invalid credential surfaces as a tool-level error during the internal login step, not an HTTP-level error from this server.

Environment Variables

Variable	类型	是否必填	默认值	说明
MCP_HTTP_PORT	int	否	8080	HTTP 监听端口
MCP_HTTP_HOST	string	否	0.0.0.0	HTTP 监听地址
WEBROOT_BASE_URL	string	否	https://unityapi.webrootcloudav.com	Webroot Unity API 基础 URL

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)
• GET /health — health check, returns {"status": "ok", "service": "webroot-mcp", "transport": "http"}

Tool List

Tool	功能	参数
webroot_get_sites	列出该 GSM 控制台下所有站点（客户账号）	无
webroot_get_endpoints	列出指定站点下的受保护终端设备	site_id（必填），page_size（可选，默认 1000）
webroot_get_groups	列出指定站点下的终端分组	site_id（必填）
webroot_get_policies	列出该 GSM 控制台下的安全策略	无
webroot_get_threat_history	获取指定站点在某日期范围内的威胁检测历史（范围不能超过 3 个月）	site_id、start_date、end_date（均必填），page_size、page_nr（可选）
webroot_get_dnsp_blocked_traffic	获取指定站点的 DNS Protection 拦截流量记录（需该控制台已启用 DNSP）	site_id、start_date、end_date（均必填），page_size、page_nr（可选）
webroot_get_dnsp_categories	列出 DNS Protection 内容过滤分类（需该控制台已启用 DNSP）	无
webroot_get_dnsp_block_reasons	列出 DNS Protection 拦截原因代码（需该控制台已启用 DNSP）	无
webroot_get_dnsp_traffic_summary	获取 DNS Protection 流量汇总统计（需该控制台已启用 DNSP）	start_date、end_date（均必填）
webroot_get_agent_status	获取终端 Agent 的实时状态/授权信息	batch_size（可选，默认 500）

Responses are the vendor's raw JSON, pretty-printed, returned as-is.

测试示例

# 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-verified (2026-07-30) against a real GSM console, all 10 tools called end-to-end through this running server with real credentials: webroot_get_sites returned 92 real sites (e.g. "Pinnacle Technologies", "Hohimer Wealth Management"); webroot_get_policies returned 11 real policies; webroot_get_agent_status returned real per-device status data; webroot_get_endpoints and webroot_get_groups (using a real site ID) both returned real data (6 endpoints, 1 group with 46 devices); webroot_get_threat_history returned a valid (empty) result for a real 2-month range. The 4 DNS Protection tools (webroot_get_dnsp_categories/_block_reasons/_traffic_summary/ _blocked_traffic) all correctly reached the API and returned the vendor's own dnsp_not_enabled error — proving the request/auth pipeline is correct; DNS Protection is simply not enabled for this particular test account's GSM console (see Known Gaps).

API Reference

• Public, no login required: https://unityapi.webrootcloudav.com/Docs/en/APIDoc (Guide covers OAuth2 authentication in full; API Reference covers every method's parameters and response shape)

Known Gaps

• Scope is exactly MSPbots' 10 configured endpoints, not the vendor's full API surface — the Unity API also covers ECom (license order/management), Notifications, agent command issuance, site creation/editing, and the OpenText Secure Cloud platform API; those are out of scope here.
• The 4 DNS Protection (DNSP) tools could not be verified with real data — DNS Protection is an add-on product that is not enabled for the test account's GSM console (dnsp_not_enabled error, confirmed live). The other 6 tools succeeded with real data using the exact same access token, confirming this is an account feature gap, not an implementation bug.
• webroot_get_endpoints/webroot_get_groups/webroot_get_threat_history require a site_id the authenticated GSM user actually has access to — Webroot GSM access is per-site; attempting these calls against a site the user isn't granted access to returns a clean "User does not have access to this console" error (observed live for one of the 92 sites during testing), not a bug in this server.
• webroot_get_threat_history rejects date ranges over 3 months (Invalid data entered - Date Range Over 3 Months, confirmed live) — this server does not enforce or auto-split the range; it passes start_date/end_date through as-is.