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:

Atlas credential type	Env var	Covers
Atlas	ATLAS_API_TOKEN	/finding, /tickets, /mvs — read and write
Atlas Readonly	ATLAS_API_TOKEN	same paths, reads only
Threat Intelligence	ESENTIRE_TI_TOKEN	/ti/ipwatch, /ti/indicators
GenAI	—	not implemented (undocumented endpoints)

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

Variable	Default	Purpose
ATLAS_API_TOKEN	—	Atlas credential (Findings / Ticketing / MVS)
ESENTIRE_TI_TOKEN	—	Threat Intelligence credential
ESENTIRE_API_BASE	https://api.esentire.com	API root
ESENTIRE_CUSTOMER_CODE	—	Default tenant code, so callers can omit it
ESENTIRE_ENABLED_SURFACES	findings,tickets,ti,mvs	Comma list; drop mvs if not licensed
ESENTIRE_READ_ONLY	false	1 refuses every mutating call at the door
MCP_TRANSPORT	http	http or stdio
MCP_HOST / MCP_PORT	0.0.0.0 / 3000	Bind address
MCP_PUBLIC_URL	—	External URL; required for OAuth
MCP_AUTH	none	none | bearer | oauth/azure | github
MCP_BEARER_TOKEN	—	Shared secret when MCP_AUTH=bearer
AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET	—	Entra app for MCP_AUTH=oauth
TI_CACHE_TTL	3600	Seconds. Matches the feed's hourly refresh
MAX_RESPONSE_CHARS	40000	Per-tool response ceiling
LOG_LEVEL	info

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.

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.