Avanan MCP

Avanan + AI - for Claude, the ChatGPT desktop app, GitHub Copilot, Gemini CLI, and any agent that speaks MCP

Unofficial. Community-built Claude Code Skill and MCP server for the Avanan

API. Not affiliated with, endorsed by, or sponsored by Check Point.

Avanan and Harmony Email & Collaboration are trademarks of Check Point

Software Technologies Ltd.

Full skill page - install, outcomes, safety model.

Every Avanan (Check Point Harmony Email and Collaboration) API operation, plus shift-start triage, phishing campaign clustering, single-message lifecycle timelines, one exception lookup across all seven security engines, and cross-tenant MSP fleet rollups that a stateless API mirror cannot answer in a single call. Works with the AI you already use - ChatGPT (desktop app), Claude Desktop, Codex, Claude Code, Claude Cowork, and GitHub Copilot - plus Gemini CLI. Free, open source, runs on your laptop. Built for MSP owners. No code required.

Works with your agent

The six agents MSP owners actually use (self-serve, works today):

The ChatGPT desktop app runs avanan-mcp locally and shares MCP configuration with Codex (OpenAI). ChatGPT on the web needs a remote server, which msp-skills does not support yet. If your team works there, a hosted gateway is the better pick; check that your AI app is on the gateway's setup list. Setup steps: mcp-install.md.

Also for the Microsoft and Google stacks

Big install base, but an honest heads-up: Gemini CLI runs the local binary you just installed, while Microsoft 365 Copilot and the Gemini app need a remote server, which msp-skills does not support yet.

Install in 60 seconds

Prefer the Claude Code plugin? Add the marketplace once, then install:

/plugin marketplace add Servosity/msp-skills

/plugin install avanan@msp-skills

Path A - paste one prompt into your AI agent (recommended)

Copy this into Claude Code, Codex CLI, or Claude Cowork:

Install the Avanan Skill and MCP server from Servosity/msp-skills in this agent workspace. If this workspace uses a POSIX shell (macOS, Linux, WSL, or Bash), run bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh). If it uses Windows PowerShell, run iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex. Then authenticate per the README and run avanan-cli --help to explore.

The same prompt works in any agent that can run shell.

Path B - run the installer yourself

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh)

The installer drops both avanan-cli (the CLI) and avanan-mcp (the MCP server) into your user bin path. Claude Code, Codex, and Cowork discover the Skill via SKILL.md in this directory.

Verify:

avanan-cli --version

Upgrade to the latest version

The installer always fetches the current release - re-run it to upgrade:

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex

Claude Code plugin users: /plugin update avanan@msp-skills.

Add to Claude Desktop, the ChatGPT desktop app, GitHub Copilot, Gemini CLI, or another MCP client

After the installer runs, see [mcp-install.md](./mcp-install.md) and [docs/which-agent.md](../../docs/which-agent.md) for the per-agent wire-up - one section per agent, including the GitHub Copilot servers key and the ChatGPT desktop app. Claude Desktop's Settings > Extensions panel is the simplest path; the MCP config block (for users who prefer editing JSON) is documented in mcp-install.md.

Install for Hermes

From the Hermes CLI:

hermes skills install servosity/msp-skills/skills/avanan --force

Inside a Hermes chat session:

/skills install servosity/msp-skills/skills/avanan --force

Hermes speaks MCP natively, so it can also use the avanan-mcp server directly - same install path, same env vars.

Install for OpenClaw

Tell your OpenClaw agent (copy this):

Install the avanan skill from https://github.com/servosity/msp-skills/tree/main/skills/avanan. The skill defines how its required CLI (avanan-cli) can be installed via the openclaw: frontmatter block.

OpenClaw isn't generally available yet; the frontmatter wiring is pre-shipped and will activate the moment OpenClaw launches.

Authenticate

Set the application credential the CLI needs (Avanan portal > Settings > API Keys), then mint a session token for your region:

export AVANAN_APP_ID=<your application id>

export AVANAN_CLIENT_SECRET= avanan-cli auth login --region us --save avanan-cli doctor

doctor confirms the credentials work and prints the regional host it resolved, before you run anything that touches data; auth login names the auth scheme it used. It exits 0 even when the credential is rejected, so scripts should add --fail-on error.

Two properties of Avanan credentials are worth knowing up front:

• `--since` filters on Avanan's ingest time, not the message date. The API's startDate/endDate match entityCreated - when Avanan scanned the message - which normally tracks the received header within seconds but can lag it by well over an hour. A window can therefore miss mail that arrived inside it and was scanned after it. Widen the window rather than assuming message age.
• Actions need the SaaS entity type, not a generic one. Quarantine and restore take office365_emails_email or google_mail_email; remediate resolves this from the entity itself, and --entity-type overrides it.
• Regions are hard-isolated. Credentials are issued per region and cross-region reads are refused by design, so a USA key returning nothing for an EU tenant is not a broken key. Valid regions: us, eu, ca, ap, uk, uae, in, plus infinity and infinity-us for the Infinity Portal gateways. On any other Infinity Portal gateway there is no region code - point the CLI at it with --base-url or AVANAN_BASE_URL.
• One application credential can reach many tenants. Run avanan-cli scopes to see exactly which {farm}:{tenant} scopes yours covers. That is also your best control - a credential bound to one tenant puts the whole fleet out of reach. See governance.md.

Sync before you ask

Most of the cross-tenant answers come from a local mirror. Populate it once:

avanan-cli mirror --since 7d

avanan-cli sync --resources msp-tenants

mirror and sync are read-only against the Avanan API and write to a SQLite file under your own user account. Re-run them whenever you want fresher data. The offline commands (triage, campaign, timeline, exceptions find, exceptions audit, msp fleet) read the mirror only and will report empty results against an unpopulated store rather than silently falling back to a live fan-out.

What this skill does

Full command reference: guide.md. For the AI-agent operating contract (--agent, --dry-run, when to confirm before mutating), see AGENTS.md.

What makes this different

Avanan already has integrations for Cortex XSOAR, Microsoft Sentinel, n8n, and two community MCP servers. Every one of them is a plugin that lives inside another product, and every one of them is stateless: one question, one API call, no history. There is no terminal-native tool, and nothing that can answer a question spanning two tenants or two days without paying for N more calls against an API that returns HTTP 429 and publishes no quota.

This skill syncs events, entities, exceptions, and MSP objects into a local SQLite mirror, so those questions become one local join. That is what turns "here are 400 detections" into "here are three campaigns, one of which is still 40% un-remediated."

It also covers more of the API than the published spec does. The SwaggerHub spec omits the auth endpoint, the entire per-sectool exception surface, and the SOAR and download helpers - about 15 operations that are documented on the vendor reference site and proven in shipping XSOAR and Sentinel code. Those are all here.

And it implements the request signature correctly. The legacy handshake signs reqId + appId + date + requestString + secret, and that requestString term is present on every non-auth call and absent from the published docs - so a client that builds the query string differently from the string it signed gets a 401 that looks exactly like a bad credential. This CLI signs and sends through one code path.

The pain this closes

• The event endpoint hands back detections but never buckets them, so a shift starts by re-scrolling the query you already ran an hour ago. avanan-cli triage returns a digest by threat type, severit