eSentire Atlas MCP Server

An MCP server exposing the eSentire Atlas API (Findings, Ticketing, MVS) and Threat Intelligence feeds (IP Watch, Advanced/STIX) as tools.

Built for HTTP transport so it can run as a container behind a reverse proxy and be consumed by remote MCP clients.

Credentials

Atlas issues four distinct credential types and they are not interchangeable — presenting the wrong type returns 402/403:

Create them in Atlas → Settings → New API Credentials. Choose Authentication: Token — the static-token flow is the one the Atlas API Reference Guide documents. Optionally add an IP restriction for your Docker host's egress address.

Configuration

MCP_AUTH is the front door — how MCP clients authenticate to this server. It is unrelated to the eSentire tokens, which authenticate this server upstream.

Tools

Findings — findings_search, findings_search_advanced, finding_update

Ticketing — tickets_case_type_configs, tickets_list_cases, tickets_get_case, tickets_create_case, tickets_update_case, tickets_list_comments, tickets_list_emails, tickets_list_attachments, tickets_get_attachment_link, tickets_upload_attachment, tickets_delete_attachment, tickets_list_contacts, tickets_list_locations

Threat Intelligence — ti_ipwatch, ti_check_ip, ti_indicators, ti_indicators_paged, ti_indicators_misp

MVS — mvs_list_assets, mvs_get_asset, mvs_asset_details, mvs_get_asset_vulnerability, mvs_list_vulnerabilities, mvs_get_vulnerability, mvs_list_missing_patches, mvs_assets_affected_by

Design notes

• Filters are native objects. Atlas wants URL-encoded JSON for query, sorts, and filters. Pass real lists/dicts; encoding is handled internally.

• assignee_email implies use_v2. Atlas silently ignores the assignee filter unless the V2 query engine is active, so findings_search enables it for you rather than returning quietly-wrong results.

• STIX is flattened by default. ti_indicators reduces bundles to a compact indicator/observable list. Pass summarize=False for raw STIX 2.1.

• MVS auto-switches GET → POST when the encoded filter payload gets long enough to risk a query-string limit.

• MVS is separately licensed. Its tools are registered by default, but they return a "wrong token type / not entitled" message if the service is not on your account. Drop mvs from ESENTIRE_ENABLED_SURFACES to hide them.

• page and per_page are mandatory on /finding/findings. Undocumented in the Atlas guide, but Atlas returns 400 Missing required query parameter without them, so findings_search always sends both (defaults 1 / 50).

• Findings and MVS use different envelopes. Findings returns {count, items, total_count}; MVS returns {data, paging}.

• 401 bodies are surfaced verbatim. "<CUSTOMERCODE> is not authorized" means the token is valid but the service is not subscribed; a bare "Unauthorized" means the token itself was rejected. Very different fixes.

• Trailing slashes are stripped. Atlas returns 404 for a URL ending in /.

• Tokens are sent raw in Authorization — no Bearer prefix.

• /health never calls upstream. An expired token or an eSentire outage must not make Docker restart-loop an otherwise-healthy container.

Local development

uv venv --python 3.12
uv pip install -e .
MCP_TRANSPORT=stdio ATLAS_API_TOKEN=... uv run python -m esentire_mcp

Deployment

Deployed as a Portainer stack that builds this repo directly on the Docker host — see docker-compose.yml. No local Docker or image registry required.

The service joins two networks: its own esentire_net, and an external mcp-edge that the reverse proxy also sits on, so the proxy can resolve esentire-atlas-mcp:3000 by name. Create it once with docker network create mcp-edge if it does not exist.

Behind a reverse proxy, streamable HTTP needs buffering disabled and long timeouts, or long-lived responses get cut:

proxy_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
chunked_transfer_encoding on;

Set MCP_PUBLIC_URL to the external HTTPS URL. It is required for OAuth and otherwise only used for advertising the server's own address.

Safety

tickets_create_case opens a real support case with eSentire's SOC. Confirm with a human before calling it. Use case_type: "Atlas API Test" for smoke tests. Closed tickets can never be reopened; resolved tickets can — prefer resolving. Set ESENTIRE_READ_ONLY=1 to disable all mutations.