ESET-MCP

A Model Context Protocol server for the entire ESET management surface: ESET Connect (cloud, all regions), ESET PROTECT On-Prem, ESET Inspect, and ESET Cloud Office. Drive any of them from any MCP host (Claude Desktop, Claude Code, or a custom agent) through tools, resources, and prompts.

Built as a single hub for any number of ESET deployments. One process fronts cloud and on-prem consoles at the same time; clients pick the target per request via headers. As long as MCP receives valid credentials (Basic auth, plus an optional URL override and optional Cloudflare Access service token) it routes the call to the right backend, mints its own tokens, and keeps tenants isolated in the pool.

⚠️ Just to be clear, fellas
This is an independent, community-driven open-source project and is not affiliated with, officially supported by, or endorsed by ESET, spol. s r.o. ESET and its product names are registered trademarks of their respective owners.

While every effort has been made to ensure this software is safe and robust (including the strict Read-Only mode gate), this code is provided "AS IS", without any warranty of any kind. You are solely responsible for how you use this tool and any changes made to your ESET environment.

Table of contents

• Features
• Architecture at a glance
• Security
• Quick start
• Configuration
• Multi-tenant deployment (basic-auth mode)
• On-prem ESET PROTECT support
• Production deployment (HTTPS via Caddy)
• Tools, resources & prompts
• Architecture
• Tests
• Refreshing the OpenAPI specs
• License

Features

Complete API coverage

• 102 tools auto-generated from 16 official ESET Connect OpenAPI 3.0.1 specs, covering application-management, asset-management, automation, device-management, identity, incident-management, installer-management, mobile-device-management, network-access-protection, patch-management, policy-management, quarantine-management, user-management, vulnerability-management, and web-access-protection.
• 4 high-level composites that fold 3-6 raw calls into one: eset_search, device_full_profile, incident_full_context, latest_detections.

Read-only / read-write modes

• ESET_MODE=RO → catalog exposes only read-only tools (51 total). Write tools are hidden from list_tools entirely.
• ESET_MODE=RW → all 106 tools advertised; mutating tools carry destructiveHint: true in their MCP annotations.
• Independent of the ESET account's underlying permissions.
• A defence-in-depth in-memory gate rejects RW tool names in RO mode before any HTTP request is sent.

Authentication

• ESET_AUTH_MODE=env - single tenant, credentials from .env.
• ESET_AUTH_MODE=basic - multi tenant, clients pass Authorization: Basic <base64(user:password)> per request (plus optional X-ESET-Region for a different cloud region, or X-ESET-Server-URL to route the request to an on-prem PROTECT console). One server fronts many ESET accounts and can mix cloud + on-prem in the same process.
• Per-tenant OAuth tokens, pooled and isolated by (user, password_hash, deployment, region-or-server-url, cf_secret_hash). Rotating a password or Cloudflare Access service token mints a fresh client; cloud and on-prem clients for the same user never share a pool entry.

Transports

• stdio - JSON-RPC over stdin/stdout for local hosts.
• Streamable HTTP - the current MCP transport (Nov 2025 spec).

Multi-region

eu / de / us / ca / jpn. Fixed via ESET_REGION in env mode; per-request via X-ESET-Region in basic mode.

Cloud + on-prem in one process

In addition to the cloud regions, a single MCP server can front customer-hosted ESET PROTECT On-Prem consoles. The on-prem auth wire format (POST /GetTokens with a camelCase response) and per-host URL structure are handled transparently; clients pick the target per request via the X-ESET-Server-URL header. See On-prem ESET PROTECT support.

Cloudflare Access (optional)

When the on-prem console sits behind a Cloudflare Access tunnel, MCP authenticates as a service token (env-default or per-request X-ESET-CF-Access-Client-Id / X-ESET-CF-Access-Client-Secret) and rides through to the origin. The CF token is an extra ingress layer in front of - not a replacement for - the ESET account credentials. Cloud requests never carry these headers.

Resilience

• OAuth2 with proactive refresh ~5 min before token expiry and a forced refresh + retry on 401.
• 429 retries with exponential backoff (up to 3 attempts, honours Retry-After).
• Pagination (nextPageToken) walked transparently.
• 202 long-polling with the response-id header, up to 10 minutes.

Response shaping (context-window protection)

A single uncapped list_* call can return hundreds of KB - enough to overflow a model's context. Two transformations are applied to every tool response:

• fields projection - every GET tool exposes an optional fields: [string] parameter that filters each list-item down to the requested keys (e.g. ["uuid", "displayName"]). Applied server-side after fetch.
• Byte cap (ESET_MCP_RESPONSE_BYTES_MAX, default 100 KB) - if a payload still exceeds the budget, the longest list is trimmed while every top-level field (nextPageToken, totalSize, …) is preserved, and a _capped metadata block is attached with an actionable hint on how to continue. Agents retain full access to the data through pagination.

Agent-friendly errors

HTTP errors are mapped to readable hints: 403 → check Permission Sets in ESET PROTECT Hub; 401 → server refreshes the token automatically; 429 → back off; 5xx → retry shortly.

Observability (logs + Prometheus)

• Structured logs to stderr. Text (default) for dev, JSON Lines for prod log shippers via ESET_MCP_LOG_FORMAT=json. Every tool call, token refresh, HTTP retry and pool eviction emits a typed event record with low-cardinality fields (tool, deployment, status, duration_ms, response_bytes, ...).
• Prometheus metrics at an opt-in /metrics endpoint (ESET_MCP_METRICS_ENABLED=true, requires pip install eset-mcp[metrics]). Counters for tool calls, token refreshes, HTTP retries, cap hits; histograms for tool duration and response sizes; gauge for client pool size.
• What never enters logs or metrics: passwords, Authorization headers, CF Access secrets, request/response bodies, query strings, substituted path parameters (which can leak UUIDs). A defensive deny-list in the logger strips known-sensitive keys before any formatter sees them.
• Failure isolation: telemetry emission is wrapped in a try/except so a broken metrics registry or formatter can never turn a successful tool call into an error to the agent. /metrics returns 500 (not 503) if exposition ever raises - the worker stays up.
• Quieting in production: set ESET_LOG_LEVEL=WARNING to mute the per-call INFO events but keep retries / errors visible; set ESET_LOG_LEVEL=ERROR to silence everything but hard failures. Disable metrics entirely with ESET_MCP_METRICS_ENABLED=false (default). The three knobs are independent.

Architecture at a glance

The simplest setup: credentials in .env, one MCP host, one ESET cloud region. Good for personal use, a single team, or a desktop AI client like Claude Desktop or Claude Code.

For real multi-tenant or enterprise deployments, put a credentials manager in front of ESET-MCP. The diagram below shows one such pattern using IBM mcp-context-forge as the "creds management" layer - any equivalent MCP gateway (or your own auth proxy) works the same way:

The forge holds per-tenant secrets and injects Authorization: Basic, X-ESET-Region, X-ESET-Server-URL, and X-ESET-CF-Access-* headers per request. ESET-MCP routes each request to the right backend (cloud region, on-prem PROTECT console, or on-prem behind Cloudflare Access) and the per-tenant LRU client pool keeps OAuth tokens fully isolated between tenants. This is a working pattern, not aspirational - the headers, pool keys, and routing rules described here are all in the test suite under tests/test_concurrency.py and tests/test_onprem.py.

Security

Credentials

• In env mode the password is read once at startup and kept in memory.
• In basic mode the password is on the wire only for the duration of the request, and in memory only while the per-tenant client is hot in the LRU pool. It is never logged.
• The pool key uses a SHA-256 hash of the password rather than the password itself.
• OAuth access/refresh tokens are held per-tenant; tokens never cross tenant boundaries within a single session.

Authentication modes & transport