Avanan (Legacy) MCP Server

An MCP server for the legacy Avanan SmartAPI (Check Point Harmony Email & Collaboration), hosted on smart-api-production-*.avanan.net. It covers two areas:

• MSP portfolio (MSP API key): customer tenants, licenses and add-ons, monthly and daily usage for billing, child MSP partners and MSP portal users.

• Security operations: security events, secured entities such as emails, allow / block exception rules, and quarantine / restore actions with task tracking.

• Transport: MCP Streamable HTTP at POST /mcp, health probe at GET /health

• Stateless and multi-tenant: credentials arrive on every request as HTTP headers and are never stored; the access token is requested per request and not cached

• Python 3.12, uv, FastMCP, httpx

• License: Apache-2.0, Copyright 2026 MSPbots.ai

Authentication headers

X-Avanan-Client-Id and X-Avanan-Client-Secret are accepted as alternative names for the first two headers.

Where to get them:

• Client id / secret: issued by Avanan / Check Point support when the SmartAPI is enabled. MSPs use the MSP API key, which also works for every customer tenant in that region.

• Region: keys are regional; a key only works against its own region, and you need one key per region you manage. MSP management endpoints are not available in the UAE region.

Every request is signed: x-av-sig is the SHA-256 hex digest of the Base64 of request id + app id + date (+ request path and query) + secret. A request to /mcp without the required headers gets HTTP 401 listing them; an unknown region gets HTTP 400.

Related MCP server: proofpoint-essentials-mcp

Tools

All tools return a JSON string. List tools return {items, count, total, has_more, scroll_id}; pass scroll_id back as scrollId for the next page.

MSP portfolio:

Security operations:

With an MSP key, event and email queries cover all customer scopes by default; action tools need a single scope (from avanan_list_scopes).

Errors come back as a JSON envelope instead of an exception:

{"error": {"code": "unauthorized", "message": "Avanan rejected the app id / secret for this region (token request failed)", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. An HTTP 200 response whose responseEnvelope.responseCode is not 0 is reported as invalid_argument with Avanan's response text.

Run locally

uv sync
uv run python -m avanan_legacy_mcp          # listens on 0.0.0.0:8080

or with Docker:

docker build --platform linux/amd64 -t avanan-legacy-mcp:dev .
docker run --rm -p 8080:8080 avanan-legacy-mcp:dev

Configuration (environment variables, all optional): MCP_HTTP_HOST (default 0.0.0.0), MCP_HTTP_PORT (default 8080), LOG_LEVEL (default INFO). Credentials are never read from the environment.

Testing example

# list tools
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Avanan-App-Id: US:your-app-id" \
  -H "X-Avanan-Secret: your-app-secret" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# phishing events since a date
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Avanan-App-Id: US:your-app-id" \
  -H "X-Avanan-Secret: your-app-secret" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"avanan_query_events","arguments":{"eventTypes":["phishing"],"startDate":"2026-01-01T00:00:00.000Z"}}}'

Unit tests (no network access needed):

uv run pytest

Delivery notes

• Tool count (33). Above the suggested 20 because the tool names are an existing contract; none were merged or removed.

• Header names. The server reads X-Avanan-App-Id / X-Avanan-Secret / X-Avanan-Region / X-Avanan-Token as registered for this integration, and also accepts X-Avanan-Client-Id / X-Avanan-Client-Secret.

• Write tools. 15 tools change data (create, update, delete, license, quarantine, restore). They are annotated (readOnlyHint=false; delete and quarantine also destructiveHint=true) and their descriptions tell the agent to act only on an explicit request. The exception list and get tools are read-only.

License

Apache License 2.0 - see LICENSE and NOTICE.