🛡️ forticnapp-mcp — FortiCNAPP MCP Server

Expose FortiCNAPP (formerly Lacework) API 2.0 as typed, auth-aware tools for any MCP client

Overview • Install • Configure • stdio • HTTP • Architecture • Security • Tools • Quick Reference

📋 Overview

forticnapp-mcp is an MCP (Model Context Protocol) server for FortiCNAPP API 2.0. Tools are not hand-written — they are generated at startup from the Lacework swagger spec (lw.yaml), so the tool surface tracks whichever spec you point it at.

The same tool registry ships behind two interchangeable transports. Pick the one that matches how you run the server.

Both modes share every other module (config.py, openapi_loader.py, auth.py, http_client.py, tool_registry.py). http_server.py only adds a Starlette app, a bearer-token gate and a /healthz endpoint in front of the same mcp.server.lowlevel.Server that main.py runs over stdio.

🤔 Why This Exists

FortiCNAPP's API 2.0 spec makes naive OpenAPI-to-tool generation unreliable:

See CLAUDE.md for the full list of spec quirks the design accounts for.

Related MCP server: OpenAI-Compatible MCP Gateway

📦 Installation

Requires Python 3.11+

pip install -e ".[dev]"

⚙️ Configuration

Credentials come from the FortiCNAPP/Lacework console (Settings → API Keys), which issues a keyId and a secret — both are required for the default auth mode.

🚀 Option A — Interactive setup (recommended)

Prompts for credentials, validates them against the real FortiCNAPP token endpoint, and writes .env, a portable .mcp.json and .gitignore.

forticnapp-mcp-setup

✍️ Option B — Manual

cp .env.example .env
# then fill in FORTICNAPP_API_BASE_URL, FORTICNAPP_KEY_ID, FORTICNAPP_API_SECRET

🔑 Key environment variables

See .env.example for every supported variable.

1️⃣ stdio Mode (local)

The client (e.g. Claude Desktop) launches the server as a subprocess and talks JSON-RPC over its stdin/stdout.

forticnapp-mcp
# equivalently:
python -m forticnapp_mcp.main

The server validates configuration and loads the spec before it starts listening. On failure it exits with a clear one-line error on stderr — it will not start with a broken configuration. This is the default mode.

🖥️ Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "forticnapp": {
      "command": "python",
      "args": ["-m", "forticnapp_mcp.main"],
      "cwd": "/absolute/path/to/mcp_forticnapp",
      "env": {
        "FORTICNAPP_API_BASE_URL": "https://YourAccount.lacework.net",
        "FORTICNAPP_KEY_ID": "YOUR_KEY_ID",
        "FORTICNAPP_API_SECRET": "YOUR_SECRET",
        "FORTICNAPP_OPENAPI_SPEC": "/absolute/path/to/mcp_forticnapp/lw.yaml"
      }
    }
  }
}

2️⃣ HTTP Mode (shared/remote)

Use the forticnapp-mcp-http entry point for one server shared by multiple MCP clients. Every request to /mcp requires a bearer token (FORTICNAPP_MCP_HTTP_TOKEN) — a separate secret from your FortiCNAPP credentials, protecting the HTTP endpoint itself.

Bare metal

cp .env.example .env
# fill in FORTICNAPP_API_BASE_URL / KEY_ID / API_SECRET as usual, plus:
# FORTICNAPP_MCP_HTTP_TOKEN=<a long random secret>

forticnapp-mcp-http
# equivalently:
python -m forticnapp_mcp.http_server

Docker

docker compose up --build

🌐 Endpoints

The server listens on 0.0.0.0:8000 by default.

Generic Streamable HTTP client config (shape varies by client)

{
  "mcpServers": {
    "forticnapp": {
      "type": "http",
      "url": "http://<host>:8000/mcp/",
      "headers": { "Authorization": "Bearer <FORTICNAPP_MCP_HTTP_TOKEN>" }
    }
  }
}

🏗️ Architecture

flowchart LR
    subgraph Clients["MCP Clients"]
        A["Claude Desktop<br/>Claude Code"]
        B["Remote MCP clients"]
    end

    subgraph Server["forticnapp-mcp"]
        M["main.py<br/>stdio"]
        H["http_server.py<br/>Streamable HTTP + bearer gate"]
        R["tool_registry.py<br/>OperationSpec → MCP Tools"]
        L["openapi_loader.py<br/>lw.yaml → OperationSpec"]
        C["http_client.py<br/>retries · 401 refresh · pagination"]
        U["auth.py<br/>keyId + secret → bearer token"]
    end

    API[("FortiCNAPP API 2.0")]

    A -->|stdio| M
    B -->|HTTPS + token| H
    M --> R
    H --> R
    L --> R
    R --> C
    C --> U
    C --> API

    style R fill:#DA291C,color:#fff,stroke:#DA291C
    style API fill:#24292f,color:#fff

🧩 Modules

📨 Tool response envelope

Every tool call returns the same structured JSON envelope:

{
  "success": true,
  "status_code": 200,
  "operation_id": "forticnapp_alerts_list",
  "request": {"method": "GET", "path": "/api/v2/Alerts", "query_keys": ["startTime"], "has_body": false},
  "data": { "...": "..." },
  "pagination": {"rows": 50, "total_rows": 400, "next_page_url": "https://...", "has_more": true},
  "error": null
}

🔧 Customizing the token exchange

If your deployment's token endpoint differs from the documented contract (self-hosted, FedRAMP, a future API revision), there is exactly one place to change: ApiKeyToTokenStrategy._acquire_token in auth.py.

It builds the token request and parses the response using field names from a TokenOperationHint, inferred from the spec at startup (openapi_loader.discover_token_operation) with fallback defaults matching FortiCNAPP's current contract:

Token caching, proactive refresh and 401-triggered re-acquisition are wire-format-agnostic and live in the surrounding ApiKeyToTokenStrategy methods — you shouldn't need to touch them.

🛡️ Security

.env
.mcp.json

🧰 MCP Tools

37 read-only tools across 9 categories.

Prefix: mcp__remote-devices__forticnapp__ — each name below is prefixed with this. The server also appeared earlier under mcp__claude-device__lcl-forticnapp-.

• forticnapp_alerts_list

• forticnapp_alerts_get

• forticnapp_alerts_search

• forticnapp_alerts_entities_get

• forticnapp_alerts_entity_details_get

• forticnapp_cloud_accounts_list

• forticnapp_cloud_accounts_search

• forticnapp_cloud_accounts_by_type_get

• forticnapp_cloud_accounts_by_intg_guid_get

• forticnapp_entities_machines_search

• forticnapp_entities_machine_details_search

• forticnapp_entities_containers_search

• forticnapp_entities_images_search

• forticnapp_entities_k8s_pods_search

• forticnapp_entities_applications_search

• forticnapp_entities_packages_search

• forticnapp_entities_processes_search

• forticnapp_entities_command_lines_search

• forticnapp_entities_files_search

• forticnapp_entities_new_file_hashes_search

• forticnapp_entities_users_search

• forticnapp_entities_network_interfaces_search

• forticnapp_entities_internal_ip_addresses_search

• forticnapp_events_search

• forticnapp_inventory_search

• forticnapp_inventory_scan_list

• forticnapp_reports_list

• forticnapp_policies_list

• forticnapp_policies_get

• forticnapp_policies_search

• forticnapp_policies_tags_list

• forticnapp_vulnerabilities_hosts_search

• forticnapp_vulnerabilities_containers_search

• forticnapp_vulnerabilities_containers_scan_get

• forticnapp_vulnerability_exceptions_list

• forticnapp_vulnerability_exceptions_get

• forticnapp_vulnerability_exceptions_search

🧪 Development

ruff check src/
pytest

⚡ Quick Reference

stdio (local)

pip install -e ".[dev]"
forticnapp-mcp-setup      # interactive credentials + .env + .mcp.json
forticnapp-mcp            # launched by the MCP client as a subprocess

HTTP (shared)

cp .env.example .env      # set FORTICNAPP_* and FORTICNAPP_MCP_HTTP_TOKEN
docker compose up --build
curl http://<host>:8000/healthz

Client call

POST http://<host>:8000/mcp/
Authorization: Bearer <FORTICNAPP_MCP_HTTP_TOKEN>

🔒 Keep secrets out of source control · Mutations are opt-in · Rotate API keys regularly