FortiMail MCP Server

Secure AI Gateway for FortiMail — open-source MCP server that speaks only to the FortiMail Engine HTTP API (/v1, Bearer API keys). It does not connect directly to a FortiMail appliance or store appliance admin passwords.

License: MIT. Security disclosures: SECURITY.md.

Features

• 40+ tools mapped to the FortiMail Engine OpenAPI (pnpm run codegen regenerates TypeScript types)

• Bearer-only upstream auth — fme_... API keys with engine-side scopes (fortimail:read / fortimail:write, etc.)

• Dual-backend caching — in-memory (default) or Redis, with per-resource TTLs (MCP response cache only)

• Retry with exponential backoff — transient HTTP errors

• TLS — verify by default; set FORTIMAIL_VERIFY_CERT=false only when appropriate

• Dual transport — Streamable HTTP (remote) or stdio (local)

• Input validation — Zod schemas on every tool

• Truncation safety — ~25K character cap on tool output (final gate for LLM context)

• Optional HTTP authentication — Bearer token and/or API key for POST /mcp

Related MCP server: Zapmail MCP Server

Architecture (thin client)

Upstream contract: vendored openapi/openapi.json. When the engine API changes, refresh that file and run pnpm run codegen.

What the AI can do for you

Security model

Threat model: Anyone who can call /mcp with valid HTTP auth can do whatever the engine API key allows. Protect Redis if used. See SECURITY.md.

Quick Start

pnpm install
pnpm run build
pnpm test

Required environment:

FORTIMAIL_ENGINE_URL=https://your-engine.example.com/v1
FORTIMAIL_ENGINE_API_KEY=fme_your_key

Example .env.local:

FORTIMAIL_ENGINE_URL=https://engine.example.com/v1
FORTIMAIL_ENGINE_API_KEY=fme_...
# FORTIMAIL_VERIFY_CERT=false   # only if engine uses a private CA / self-signed cert

Run:

pnpm start
# HTTP + MCP auth
TRANSPORT=http PORT=3000 MCP_HTTP_BEARER_TOKEN=secret pnpm start

Environment variables

Authentication tools

• fortimail.engine.status — liveness (GET /health); optional detailed readiness (GET /health/detailed, Bearer). Both are requested at the engine origin (same host/port as FORTIMAIL_ENGINE_URL with /v1 stripped), not under /v1.

• fortimail.auth.logout — no-op (legacy name; engine uses API keys only).

• fortimail.cache.flush — clears MCP response cache (not the engine server cache).

Publishing to MCP directories (e.g. Smithery)

This server matches Smithery’s URL publishing expectations:

If Smithery or another gateway shows “couldn’t authenticate with the upstream server”: the gateway is calling your URL without a valid MCP secret. Set MCP_HTTP_BEARER_TOKEN on the host to match the value users enter in Smithery (or Cursor / ChatGPT connector) for MCP Bearer Token. Optional fields in the JSON Schema do not remove the need for that token when the server enforces HTTP auth.

Cloudflare / WAF: allow SmitheryBot and skip JS challenges on POST /mcp so scans succeed (Smithery troubleshooting). For MCP, also disable caching and response buffering on /mcp so SSE streams are not broken.

Reverse proxy (Traefik / nginx / Dokploy): The upstream must receive the same credential headers the client sends. If Authorization is stripped, configure the proxy to forward it, or have the gateway send X-MCP-Bearer-Token (supported by this server). Some setups copy the client Authorization into X-Forwarded-Authorization — that is supported when the primary Authorization header is missing.

Still failing: Set MCP_HTTP_DEBUG_AUTH=true on the container and retry from ChatGPT; check logs for hasAuthorization / hasXMcpBearerToken / queryKeys (no secrets logged). If all are false, the gateway is not forwarding credentials to your origin.

• Name: fortimail-mcp-server

• Description: MCP client for FortiMail Engine API — domains, users, profiles, queue, reports, logs, SMTP

• Required env (process): FORTIMAIL_ENGINE_URL, FORTIMAIL_ENGINE_API_KEY

• Transports: stdio, Streamable HTTP (POST /mcp streams SSE; GET /mcp returns 401 without auth, else 405 with hint)

HTTP mode for Cursor / ChatGPT / Claude (remote URL)

Point the client at https://your-host/mcp and configure the same secret the server expects:

• Authorization: Bearer <MCP_HTTP_BEARER_TOKEN>, or

• Header: X-MCP-Bearer-Token: <MCP_HTTP_BEARER_TOKEN> (matches Smithery mcp_bearer_token / x-mcp-bearer-token), or

• Query: ?mcp_bearer_token=<token> (less ideal; may appear in logs)

MSP and multi-instance

One process = one engine base URL + one API key. For many tenants or appliances, run multiple MCP instances (or let the engine multiplex tenants — the MCP only forwards the Bearer token). See docs/MULTI_INSTANCE.md.

Licensing and commercial roadmap

• Open core: MIT (LICENSE).

• Engine: The FortiMail Engine service that implements openapi.json may be proprietary; this repo stays a thin OSS client.

Contributions: CONTRIBUTING.md. Security: SECURITY.md.

Tool inventory

Engine & cache (3 tools)

• fortimail.engine.status / fortimail.auth.logout / fortimail.cache.flush

Domains (7 tools)

• fortimail.domains.list / fortimail.domains.get / fortimail.domains.create / fortimail.domains.update / fortimail.domains.delete

• fortimail.domains.info.get / fortimail.domains.info.update

Users (10 tools)

• Mail users: fortimail.users.list / .get / .create / .update / .delete

• User maps: fortimail.users.maps.list / .get / .create / .update / .delete

Profiles (20 tools)

• GeoIP, Notification, IMAP auth, SMTP auth — CRUD each (e.g. fortimail.profiles.geoip.list)

Mail queue (6 tools)

• fortimail.queue.list / .search / .view / .delete / .reroute / .download

Reports (6), Logs (2), SMTP (2)

• fortimail.reports.*, fortimail.logs.*, fortimail.smtp.config.*

Repository layout

src/
├── index.ts
├── constants.ts
├── text-utils.ts
├── generated/engine-schema.ts   # pnpm run codegen
├── engine/unwrap.ts
├── services/api-client.ts      # EngineClient (Bearer)
└── tools/

MCP client configuration (stdio)

{
  "mcpServers": {
    "fortimail": {
      "command": "node",
      "args": ["/path/to/fortimail-mcp-server/dist/index.js"],
      "env": {
        "FORTIMAIL_ENGINE_URL": "https://engine.example.com/v1",
        "FORTIMAIL_ENGINE_API_KEY": "fme_..."
      }
    }
  }
}

HTTP mode

TRANSPORT=http PORT=3000 MCP_HTTP_BEARER_TOKEN=your-secret node dist/index.js

Development

See CONTRIBUTING.md. Run pnpm test before submitting changes. After updating openapi/openapi.json, run pnpm run codegen.