Abnormal Security MCP Server

An MCP server for the Abnormal Security REST API. It lets an AI agent review e-mail threats detected by Abnormal (phishing, BEC, account takeover), read the messages behind them, check or trigger remediation, and look at employee-reported campaigns and account-takeover cases.

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

• Stateless and multi-tenant: the API token arrives on every request as an HTTP header and is never stored

• Python 3.12, uv, FastMCP, httpx

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

Authentication headers

Where to get them:

• API token: in the Abnormal portal, open Settings -> Integrations -> Abnormal REST API and generate a token.

• IP allowlist: Abnormal only accepts API calls from allowlisted IP addresses. Add the public egress IP of the environment that runs this server on the same Integrations page; calls from other addresses fail with unauthorized.

• Licenses: the case tools need Abnormal's Account Takeover license.

A request to /mcp without a token gets HTTP 401 listing the required header; an unknown region gets HTTP 400.

Related MCP server: Cisco Secure Access MCP Server

Tools

All tools return a JSON string. List tools return {items, count, page, has_more, next_page}. Abnormal only pages when a time filter is given (<key> gte <time> lte <time>, times like 2026-01-31T00:00:00Z); without one the threat and case lists return the latest 100 IDs.

pageSize defaults to 50 (Abnormal's maximum is 100).

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

{"error": {"code": "unauthorized", "message": "Abnormal returned HTTP 401: ...", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error.

Run locally

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

or with Docker:

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

Configuration (environment variables, all optional): MCP_HTTP_HOST (default 0.0.0.0), MCP_HTTP_PORT (default 8080), LOG_LEVEL (default INFO). The token is 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# threats received since a date
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"abnormal_threats_list","arguments":{"filter":"receivedTime gte 2026-01-01T00:00:00Z","pageSize":10}}}'

Unit tests (no network access needed):

uv run pytest

Delivery notes

• Header name. The token header is Authorization rather than an X-Abnormal-* name because existing gateway registrations and tenant connections already use it. X-Abnormal-Region is a new optional header; without it the US host is used, as before.

• Write tool. abnormal_remediation_manage with remediate / unremediate changes users' mailboxes. Abnormal applies these actions to the whole threat campaign, so the description tells the agent to use them only on explicit request; it is annotated destructiveHint=true. messageId is used for the status action (remediation history of that message).

• Message limits. Abnormal returns at most 10 messages per threat on the threat-detail endpoint, which abnormal_threats_get and abnormal_messages_list use.

License

Apache License 2.0 - see LICENSE and NOTICE.