webroot-mcp

Webroot(OpenText 엔드포인트 보안 / SecureAnywhere, Global Site Manager "GSM" 콘솔을 통해 관리)용 MCP 서버. Webroot Unity API의 GSM 콘솔 사이트, 엔드포인트, 그룹, 정책, 위협 기록, 실시간 에이전트 상태 및 DNS 보호(DNSP) 메서드를 MCP 도구로 노출합니다.

개요

• 무상태(Stateless) HTTP 서비스입니다. 자격 증명은 절대 저장되지 않으며, 각 요청이 자체 자격 증명을 헤더로 제공하고 해당 단일 요청의 수명 동안에만 사용됩니다.

• 동시 요청을 지원하며, 요청별 자격 증명 격리는 전역/공유 클라이언트 인스턴스가 아닌 Python contextvars를 통해 수행됩니다.

• 진입점: POST /mcp(MCP 프로토콜) 및 GET /health(헬스 체크).

• 기본 포트: 8080(MCP_HTTP_PORT로 구성 가능).

Related MCP server: mcp-connectwise-psa

인증

Webroot Unity API는 표준 OAuth2를 구현하며 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": "...", ...}

액세스 토큰은 약 5분 동안만 유효하므로, 이 서버는 MCP 요청 간에 토큰을 캐시하지 않고 모든 도구 호출 시마다 새로 인증합니다. 캐시되거나 저장되는 것은 없습니다. 이후 모든 실제 API 호출은 Authorization: Bearer <access_token> 헤더를 전송합니다.

헤더 인증 매개변수 설명

헤더가 하나라도 누락되면 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": []
}

잘못된 자격 증명은 이 서버의 HTTP 수준 오류가 아니라 내부 로그인 단계에서 구조화된 도구 수준 오류로 표시됩니다("오류 처리" 섹션 참조).

환경 변수

MCP 엔드포인트

• POST /mcp — MCP 프로토콜(streamable HTTP 전송)

• GET /health — 헬스 체크, {"status": "ok"} 반환(순수 로컬 프로브이며 Webroot API에 의존하지 않음)

도구 목록

10개 도구 모두 읽기 전용(readOnlyHint=True)이며, 이 서비스에는 쓰기/삭제 도구가 없습니다.

page_size/batch_size 상한: 공급업체의 공개 API 참조 문서에는 위의 어떤 엔드포인트에서도 이러한 매개변수의 최대값이 문서화되어 있지 않으므로, 이 서버는 무제한 값을 그대로 전달하는 대신 자체 기본값(50)과 상한(200)을 적용합니다.

응답은 공급업체의 JSON을 압축 직렬화(예쁘게 출력하지 않음, ensure_ascii=False)하며 20,000자로 제한됩니다. 크기가 큰 목록 필드는 무제한 blob을 반환하는 대신 truncated/original_count 마커로 잘립니다.

오류 처리

오류는 대역 내 JSON 봉투(일반 도구 결과 문자열, MCP 프로토콜 오류 아님)로 반환됩니다:

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

code는 고정 어휘 중 하나입니다: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. retryable은 동일한 호출을 재시도하면 성공할 수 있는지 여부를 호출자에게 알려줍니다(rate_limited/upstream_error의 경우 true, 그 외에는 false). 빈 결과 집합(예: 엔드포인트가 없는 사이트)은 not_found 오류가 아니라 정상적인 성공 결과입니다.

Webroot API에 대한 아웃바운드 호출은 5초 연결 / 30초 읽기 시간 제한을 사용하며, 429/5xx 응답에 대해 백오프를 적용하여 최대 3회 재시도합니다(Retry-After 존중, 20초 상한). 프로세스 수명 동안 단일 풀링된 HTTP 클라이언트를 재사용합니다.

테스트 예시

# 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": {}
    }
  }'

실제 검증 완료(2026-07-30): 실제 GSM 콘솔을 대상으로 이 실행 중인 서버를 통해 실제 자격 증명으로 10개 도구 모두를 종단 간 호출했습니다. webroot_get_sites는 실제 사이트 92개를 반환했고(예: "Pinnacle Technologies", "Hohimer Wealth Management"), webroot_get_policies는 실제 정책 11개를 반환했으며, webroot_get_agent_status는 실제 장치별 상태 데이터를 반환했습니다. webroot_get_endpoints와 webroot_get_groups(실제 사이트 ID 사용)는 모두 실제 데이터를 반환했습니다(엔드포인트 6개, 장치 46개가 포함된 그룹 1개). webroot_get_threat_history는 실제 2개월 범위에 대해 유효한(빈) 결과를 반환했습니다. 4개의 DNS Protection 도구(webroot_get_dnsp_categories/_block_reasons/_traffic_summary/_blocked_traffic)는 모두 API에 올바르게 도달하여 공급업체 자체의 dnsp_not_enabled 오류를 반환했습니다. 이는 요청/인증 파이프라인이 올바르다는 것을 증명합니다. DNS Protection은 단순히 이 특정 테스트 계정의 GSM 콘솔에 대해 활성화되어 있지 않은 것입니다("알려진 제한 사항" 참조).

API 참조

• 공개, 로그인 불필요: https://unityapi.webrootcloudav.com/Docs/en/APIDoc (가이드는 OAuth2 인증을 전체적으로 다루며, API 참조는 모든 메서드의 매개변수와 응답 형식을 다룹니다)

알려진 제한 사항

• 범위는 정확히 MSPbots의 구성된 10개 엔드포인트이며, 공급업체의 전체 API 표면이 아닙니다 — Unity API는 또한 ECom(라이선스 주문/관리), 알림, 에이전트 명령 발행, 사이트 생성/편집 및 OpenText Secure Cloud 플랫폼 API도 다루지만, 이러한 항목은 여기서 범위를 벗어납니다.

• 4개의 DNS Protection(DNSP) 도구는 실제 데이터로 검증할 수 없었습니다 — DNS Protection은 테스트 계정의 GSM 콘솔에 활성화되지 않은 애드온 제품입니다(dnsp_not_enabled 오류, 실시간 확인됨). 나머지 6개 도구는 동일한 액세스 토큰으로 실제 데이터를 사용하여 성공했으며, 이는 구현 버그가 아니라 계정 기능 격차임을 확인합니다.

• webroot_get_endpoints/webroot_get_groups/webroot_get_threat_history는 인증된 GSM 사용자가 실제로 액세스 권한이 있는 site_id가 필요합니다 — Webroot GSM 액세스는 사이트별로 이루어지며, 사용자에게 액세스 권한이 부여되지 않은 사이트에 대해 이러한 호출을 시도하면 이 서버의 버그가 아닌 깔끔한 "User does not have access to this console" 오류가 반환됩니다(테스트 중 92개 사이트 중 하나에서 실시간 관찰됨).

• webroot_get_threat_history는 3개월을 초과하는 날짜 범위를 거부합니다 (Invalid data entered - Date Range Over 3 Months, 실시간 확인됨) — 이 서버는 범위를 강제하거나 자동 분할하지 않으며, start_date/end_date를 그대로 전달합니다.