cisco-umbrella-mcp

Cisco Umbrella MCP 서비스 — Cisco Umbrella REST API v2(최신 Secure Access/SASE 제품이 아닌 기존 Umbrella)를 래핑하는 무상태 HTTP MCP 서버로, MSPbots가 현재 사용하는 10개 엔드포인트로 범위가 제한됩니다: DNS/프록시/방화벽/AMP 사후 분석 활동 보고서, 로밍 컴퓨터, 앱 검색(애플리케이션/프로토콜/애플리케이션 카테고리), 관리형 제공업체 고객 목록, 제공업체 콘솔 요약.

기술 스택: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

에이전트가 이 도구를 사용하는 경우

Cisco Umbrella는 DNS/웹 계층에서 고객의 네트워크를 보호합니다 — 악성 도메인을 차단하고, 카테고리별로 웹 콘텐츠를 필터링하며, 네트워크 활동을 기록합니다. 에이전트는 다음과 같은 요청에 이 MCP를 사용해야 합니다:

• "이 도메인이 최근 이 고객의 네트워크에서 조회되거나 차단되었나요?" → cisco_umbrella_get_activity_dns

• "이 고객에 대해 어떤 웹 카테고리/URL이 필터링되거나 프록시되고 있나요?" → cisco_umbrella_get_activity_proxy

• "지난 하루 동안 이 고객의 네트워크에 대한 방화벽 허용/차단이 있나요?" → cisco_umbrella_get_activity_firewall

• "정상으로 보였던 파일이 나중에 악성코드로 플래그되었나요?" → cisco_umbrella_get_activity_amp_retrospective

• "이 고객의 로밍 노트북과 마지막 동기화/상태를 나열해 주세요" → cisco_umbrella_list_roaming_computers

• "Cisco Umbrella에서 관리하는 고객 조직을 나열해 주세요" / "고객별 Umbrella 패키지 사용량은 어떻게 되나요?" → cisco_umbrella_list_customers, cisco_umbrella_get_providers_console

주의사항: 이 자격 증명 세트는 고객별 자격 증명이 아닌 관리형 제공업체(MSSP) 루트 조직 키이므로, 위의 고객별 활동/장치 도구는 실제로 비어 있을 수 있습니다 — 검증된 세부 사항은 아래 알려진 격차를 참조하세요.

Related MCP server: cisco-secure-access-mcp

인증 방법 참고

Cisco Umbrella의 기존 REST API는 OAuth2 client_credentials 그랜트를 지원합니다 — 사용자 브라우저 리디렉션이 없는 순수한 서버 간 교환입니다. 관리자는 Umbrella 대시보드(Admin > API Keys)에서 API Key + Key Secret 쌍을 생성하며, 이 서비스는 호출할 때마다 해당 쌍을 단기(1시간) 베어러 토큰으로 교환합니다(리프레시 토큰이 없으므로 요청 간 캐싱이 없음 — covedataprotection-mcp/webroot-mcp/logmein-mcp와 동일한 "호출마다 재로그인" 패턴).

POST https://api.umbrella.com/auth/v2/token
Authorization: Basic base64(apiKey:keySecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

지역 참고: MSPbots의 Cisco Umbrella 통합 구성에는 dataCenter 필드(us/eu)가 있습니다. Cisco 자체 개발자 문서에 포함된 원시 OpenAPI 사양을 10개 엔드포인트 모두와 인증/토큰 엔드포인트에 대해 직접 검증했습니다: 모든 엔드포인트가 정확히 하나의 호스트 https://api.umbrella.com을 나열합니다 — 기존 Umbrella에는 별도의 EU 호스트가 없습니다. (Cisco의 최신 "Secure Access" 제품에는 자체 지역 개념이 있지만, 이 서비스가 대상으로 하는 제품과는 다른 제품입니다.) 따라서 이 서비스는 dataCenter 값을 완전히 무시합니다. 이 10개 엔드포인트에는 필요하지 않습니다.

빠른 시작

# Install dependencies
cd D:\claude\project\cisco-umbrella-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

구성

.env.example을 .env로 복사하고 값을 입력하세요:

HEADER 인증 매개변수 설명

게이트웨이 모드에서 각 요청은 다음 두 HTTP 헤더를 반드시 포함해야 합니다:

Claude Desktop 설정

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "cisco-umbrella": {
      "command": "uv",
      "args": ["run", "--directory", "D:/claude/project/cisco-umbrella-mcp", "cisco-umbrella-mcp"],
      "env": {
        "UMBRELLA_API_KEY": "your_api_key",
        "UMBRELLA_KEY_SECRET": "your_key_secret"
      }
    }
  }
}

전송 모드

stdio (Claude Desktop / CLI)

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

HTTP — 단일 테넌트

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="env"
uv run cisco-umbrella-mcp

HTTP — 게이트웨이 / 멀티 테넌트

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run cisco-umbrella-mcp
# Each request must include: X-Umbrella-Api-Key and X-Umbrella-Key-Secret headers

사용 가능한 도구 (10)

from_/to는 Umbrella 보고 API 규칙에 따라 에포크 밀리초, ISO-8601 또는 상대 오프셋(예: "-1days", "-7days", "now")을 허용합니다. (from_는 from이 Python 예약어이므로 끝에 밑줄이 있습니다 — 내부적으로 리터럴 from 쿼리 매개변수에 매핑됩니다.)

알려진 격차

두 개의 실제 관리형 제공업체(MSSP) 계정으로 테스트했습니다. 10개 도구 중 2개만 검증된 실제 데이터로 확인되었습니다; 나머지 8개는 차단되었거나 검증되지 않았습니다(빈 결과는 정확성을 증명하지 않습니다 — 오류가 발생하지 않았다는 의미일 뿐입니다).

✅ 확인됨 (실제, 비어 있지 않음, 교차 검증된 데이터):

• cisco_umbrella_get_providers_console — 두 테스트 계정 모두에서 실제 구독 요약(customerCount: 77 및 customerCount: 47 각각).

• cisco_umbrella_list_customers — 계정 1에서 77개의 실제 고객 조직(실제 회사 이름)을 반환했습니다. 계정 2에서는 403 Access Forbidden으로 실패 — 해당 계정의 토큰을 디코딩하여 admin.customers:read 범위가 실제로 없다는 것을 확인했습니다(계정 1의 76개 범위 대비 총 20개 범위). 코드 버그가 아니라 실제 키별 권한 차이입니다.

⚠️ 검증되지 않음 — 두 계정 모두에서 형식은 올바르지만 빈 결과를 반환, 정확성이 입증되지 않음: cisco_umbrella_get_activity_dns, _proxy, _firewall, _amp_retrospective, cisco_umbrella_list_roaming_computers. Activity DNS의 라이브 OpenAPI 매개변수 정의를 Cisco 자체 문서와 직접 교차 확인했습니다(요약이 아닌 원시 사양을 가져옴) — from/to/limit는 구현된 것과 정확히 일치하며, 누락되거나 잘못 명명된 매개변수가 없습니다. 그럴듯한 설명은 두 테스트 계정 모두 관리형 제공업체 루트 조직이며, 자체 DNS/프록시/방화벽/AMP 트래픽이나 로밍 컴퓨터가 없다는 것입니다 — 해당 데이터는 각 관리 고객 조직 아래에 개별적으로 존재합니다. 기존 Umbrella에 대한 "이 고객 조직으로 쿼리" 범위 지정 매개변수/헤더를 Cisco 문서에서 검색했지만 찾지 못했습니다("Multi-Org" 토큰 범위 지정 개념이 존재하지만, 기존 Umbrella가 아닌 별도의 Secure Access/SASE 제품에만 해당). 고객별 데이터에 대한 의도된 경로로 보이는 별도의 "Providers" API 제품군(/providers/customers/{customerId}/...)이 있지만, 이 빌드에서 확인된 10개 엔드포인트 범위를 벗어납니다. 이 5개를 실제로 확인하려면 (제공업체 수준이 아닌) 실제 단일 고객 조직 자격 증명이 필요합니다.

• cisco_umbrella_list_applications, _protocols, _application_categories (App Discovery) — 차단이 확인되었으며 코드 버그가 아닙니다. 두 테스트 계정 모두와 동일한 토큰을 사용한 직접 curl에서 동일하게 재현되었습니다(요청 구성 문제를 배제함): 계정 1에서는 403 Access Forbidden, 계정 2에서는 500/403. 두 토큰의 범위 목록에 reports.appdiscovery:read가 포함되어 있었으므로, 이는 권한이나 매개변수 문제가 아니라 패키지/자격 제한(유료 애드온인 App Discovery가 두 계정의 "Umbrella for MSSPs" 티어에 포함되지 않음)일 가능성이 가장 높습니다.

• cisco_umbrella_get_providers_console는 목록이 아닌 단일 구독 요약 객체를 반환합니다 — 두 라이브 테스트를 통해 확인되었습니다. MSPbots 자체 구성 API 목록의 복수 이름("Providers Consoles")에도 불구하고, MSPbots의 기존 수집기가 기대하는 것(배열 vs 단일 객체)과 대조하여 다시 확인하십시오.

• Applications 앱 검색 엔드포인트의 선택적 매개변수 목록이 완전히 빠짐없이 나열되지 않았을 수 있습니다(연구 중 해당 엔드포인트 스키마 끝부분의 매개변수 몇 개가 완전히 캡처되지 않음) — 여기에 문서화된 매개변수(sources, identity, labels, controllable, categories, subcategory, limit, offset)는 실제로 확인된 것이며, 아직 추가되지 않은 매개변수가 한두 개 더 있을 수 있습니다.

• 범위는 MSPbots가 현재 사용하는 10개 작업(사용자 확인됨)으로 제한되며, Umbrella의 전체 API 표면(Networks, Internal Domains, Sites, Network Tunnels, Policies, Tagging, 고객별 작업을 위한 별도의 "Providers" API, API 키 자체를 관리하기 위한 Key Admin API도 포함)은 포함하지 않습니다.

API 참조

• Cisco Umbrella API 인증

• Cisco Cloud Security API 문서 (DevNet)