checkpoint-mcp

MCP server for Check Point Harmony Endpoint (endpoint protection/EDR, part of Check Point's Infinity Portal). Exposes the Harmony Endpoint Web Management API's policy, asset, vulnerability posture, quarantine, and remediation methods as MCP tools.

Naming note: MSPbots' own integration is registered as "Check Point Harmony Endpoint" (subjectCode=CHECKPOINT). This MCP covers exactly the 11 methods MSPbots itself has configured.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own Infinity Portal API key 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

Check Point's Infinity Portal uses a 2-step API-key exchange, and the Harmony Endpoint Web Management API on top of that requires both resulting tokens together on every real call:

1. POST {region}/auth/external with {clientId, accessKey} → a portal bearer token (data.token), valid ~30 minutes.
2. POST {region}/app/endpoint-web-mgmt/harmony/endpoint/api/v1/session/login/cloud with Authorization: Bearer <portal token> → a management-service apiToken, valid only ~6 minutes.
3. Every real endpoint call requires both Authorization: Bearer <portal token> and x-mgmt-api-token: <apiToken> headers together, plus x-mgmt-run-as-job: on.

Because the apiToken is short-lived anyway, this server performs this entire 2-step login fresh on every single tool call — nothing is cached or persisted across MCP requests.

All 11 methods are asynchronous jobs. The initial call only returns {"jobId": ...}; the real result is fetched by polling GET .../jobs/{jobId} until the job leaves an in-progress state (this server polls every 1s, up to a 30s timeout, per tool call).

HEADER 授权参数说明

Header	类型	是否必填	默认值	枚举值	字段描述	Example
X-CheckPoint-Client-Id	string	是	无	无	Infinity Portal API Key 的 Client ID	45217fa1-6c33-4389-a169-909fa72e99dd
X-CheckPoint-Access-Key	string	是	无	无	Infinity Portal API Key 的 Secret/Access Key	911b25e9-149a-45b3-a9a7-a9d43be24635
X-CheckPoint-Region	string	是	无	https://cloudinfra-gw-us.portal.checkpoint.com（US）、https://cloudinfra-gw.portal.checkpoint.com（EU）、https://cloudinfra-gw.ap.portal.checkpoint.com（AP）	租户所在数据驻留区域的网关地址，与 MSPbots 集成配置里的 Region 下拉选项一致	https://cloudinfra-gw.ap.portal.checkpoint.com

Missing any header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-CheckPoint-Client-Id, X-CheckPoint-Access-Key, and X-CheckPoint-Region headers",
  "required_headers": ["X-CheckPoint-Client-Id", "X-CheckPoint-Access-Key", "X-CheckPoint-Region"],
  "optional_headers": []
}

Environment Variables

Variable	类型	是否必填	默认值	说明
MCP_HTTP_PORT	int	否	8080	HTTP 监听端口
MCP_HTTP_HOST	string	否	0.0.0.0	HTTP 监听地址

MCP Endpoint

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

Tool List

Tool	功能	参数
checkpoint_get_policy_metadata	列出所有 Harmony Endpoint 策略规则的元数据	无
checkpoint_get_policy_modifications	获取指定策略规则的修改历史	rule_id（必填）
checkpoint_get_policy_assignments	获取指定策略规则的分配对象	rule_id（必填）
checkpoint_get_computers_filtered	列出受管计算机/端点（可选过滤条件）	filter（可选，vendor 自定义过滤对象）
checkpoint_search_organization_tree	搜索组织架构树（组/用户/计算机）	search_term、search_type、entity_types、offset、page_size（均可选）
checkpoint_get_vulnerability_data	列出组织级漏洞态势数据	offset、page_size（均可选）
checkpoint_get_vulnerability_devices	获取指定设备的漏洞态势详情	device_ids（必填），offset、page_size（可选）
checkpoint_get_vulnerability_scan_status	获取漏洞扫描状态	无
checkpoint_get_quarantine_files	列出隔离区文件	offset、page_size（均可选）
checkpoint_get_remediation_status	列出修复/响应操作的状态	无
checkpoint_get_remediation_results_slim	获取指定修复操作的简要结果	remediation_id（必填），offset、page_size（可选）

Responses are the vendor's job-result JSON, pretty-printed ({"status": "DONE", "statusCode": ..., "data": ...}), 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-CheckPoint-Client-Id: <your-client-id>" \
  -H "X-CheckPoint-Access-Key: <your-access-key>" \
  -H "X-CheckPoint-Region: https://cloudinfra-gw.ap.portal.checkpoint.com" \
  -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": "checkpoint_get_policy_metadata",
      "arguments": {}
    }
  }'

Live-verified (2026-07-30) against a real Harmony Endpoint tenant, all 11 tools called end-to-end through this running server: ..._policy_metadata returned real policy rules (e.g. "Testing App Control", several organization-default rules across the Access/Threat Prevention/Data Protection/OneCheck/General Settings/Deployment/Agent Settings/Data Loss Prevention families); ..._policy_assignments returned the real "Entire Organization" assignment for a default rule; ..._computers_filtered returned 18 real managed computers with live agent health data; ..._search_organization_tree returned real groups (Virtual Directory Structure, ChromeOsDesktops, etc.); ..._vulnerability_scan_status returned real per-device scan statuses; ..._remediation_status returned a real completed DA_COLLECT_LOGS remediation action; ..._remediation_results_slim (using that action's real ID) returned its real per-machine result; ..._quarantine_files returned a real quarantined file record; ..._vulnerability_data and ..._vulnerability_devices returned valid empty result sets (no vulnerability data present for this tenant at test time — a legitimate empty response, not an error); ..._policy_modifications (using a real rule ID) returned statusCode 204 (no modification history for that rule — also a legitimate response).

API Reference

• Auth flow discovered and confirmed via the third-party Shuffle SOAR platform's public integration docs (Check Point does not appear to publish this specific 2-step token exchange in an easily discoverable public reference of their own): https://shuffler.io/apps/Harmony_Endpoint_Management/integrations/Checkpoint
• No further official public API reference for the Harmony Endpoint Web Management API's individual method schemas was found; behavior for each of the 11 methods in this README was determined via MSPbots' own stored apiConfig (path/params) cross-checked against live calls with real credentials (see Live-verified above), following this program's standing rule to never trust stored config as ground truth without confirming against the real API.

Known Gaps

• Scope is exactly MSPbots' 11 configured endpoints, not the vendor's full API surface — Harmony Endpoint Web Management exposes many more categories (Session, Jobs, Indicators of Compromise, Remediation & Response - Agent/Threat Prevention, etc. per the Shuffle integration's own category list) that MSPbots does not use; those are out of scope here.
• checkpoint_get_computers_filtered's filter parameter shape is undocumented — MSPbots' own stored config sends an empty body, so this server accepts an optional generic dict and defaults to {} (an unfiltered listing) rather than guessing at a specific filter schema.
• Async job polling timeout is fixed at 30s (1s interval) — all live test calls completed in well under a second, but a tenant with a very large dataset could plausibly exceed this; not configurable via env var in this version.
• Job responses can validly be non-200/204 without being an error — e.g. checkpoint_get_policy_modifications returned statusCode: 204 or checkpoint_get_vulnerability_data returned an empty data array; this server surfaces the job result as-is rather than treating anything other than 200 as a tool-level error, since the async job framing means the vendor's own success/failure signaling lives inside the JSON body, not the outer HTTP status code.