# forticnapp-mcp

An MCP (Model Context Protocol) server that exposes FortiCNAPP (formerly Lacework) API 2.0
operations as typed, auth-aware tools. Tools aren't hand-written: they're generated at startup
from lw swagger.json (`lw.yaml`), so the tool surface tracks the spec you point it at.

Choose STDIO if you are building or running tools locally on your own machine. Choose Streamable HTTP if you need to share the server across multiple users, deploy it to the cloud, or require centralized authentication.

The same tool registry ships behind **two interchangeable transports** — pick whichever fits how
you're running the server:

| | stdio (`forticnapp-mcp`) | HTTP (`forticnapp-mcp-http`) |
|---|---|---|
| Use case | One local client (Claude Desktop, Claude Code) launches the server as a subprocess | One shared server, multiple remote MCP clients over the network |
| Transport | JSON-RPC over stdin/stdout | Streamable HTTP, `POST /mcp/` |
| Process model | Spawned per client, dies with it | Long-running, started once (bare metal or Docker) |
| Auth | Inherits the FortiCNAPP credentials from its own env | Same FortiCNAPP credentials, **plus** a bearer token (`FORTICNAPP_MCP_HTTP_TOKEN`) gating the HTTP endpoint itself |
| Tenancy | One FortiCNAPP account per subprocess | One FortiCNAPP account per running instance — every caller with the bearer token sees the same account, there's no per-client credential isolation |

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
auth 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 doesn't declare OpenAPI `securitySchemes`, has no `operationId` on any
of its 120+ operations, and mixes read-only "search" endpoints in with real mutations under the
same HTTP methods. This server works around all three: it hardcodes the real FortiCNAPP auth
handshake, derives deterministic tool names from method + path, and classifies "is this
mutating" from the path shape rather than the HTTP verb alone. See `CLAUDE.md` for the full list
of spec quirks this design accounts for.

## Install

Requires Python 3.11+.

```bash
pip install -e ".[dev]"
```

## Configure

Quickest path — run the interactive setup command, which prompts for your credentials,
validates them against the real FortiCNAPP token endpoint, and writes `.env`, a portable
`.mcp.json`, and `.gitignore`:

```bash
forticnapp-mcp-setup
```

Or configure by hand:

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

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. See
`.env.example` for every supported variable, including `FORTICNAPP_ENABLED_TAGS` (which OpenAPI
tags become tools) and `ENABLE_MUTATION_TOOLS` (off by default — only read-only tools are
exposed until you opt in).

## Run: stdio mode (local, single client)

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

The server speaks MCP over stdio — the client (e.g. Claude Desktop) launches it as a subprocess
and talks JSON-RPC over its stdin/stdout. It validates configuration and loads the spec before it
starts listening, and exits with a clear one-line error on stderr if either step fails — it will
not start with a broken configuration. This is the default mode; see "Claude Desktop
configuration" below for a full client config.

## Run: HTTP mode (shared/remote, multiple clients)

For a shared/remote deployment (one server, multiple MCP clients over the network) instead of a
local stdio subprocess, use the `forticnapp-mcp-http` entrypoint. It speaks MCP over Streamable
HTTP and requires a bearer token (`FORTICNAPP_MCP_HTTP_TOKEN`) on every request to `/mcp` — this
is a separate secret from your FortiCNAPP credentials, protecting the HTTP endpoint itself. The
server still serves exactly one FortiCNAPP account per instance, same as stdio.

```bash
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
```

Or run it in Docker instead of bare metal:

```bash
docker compose up --build
```

The server listens on `0.0.0.0:8000` by default (`FORTICNAPP_MCP_HTTP_HOST` /
`FORTICNAPP_MCP_HTTP_PORT`). MCP clients should POST to `http://<host>:8000/mcp/` with
`Authorization: Bearer <FORTICNAPP_MCP_HTTP_TOKEN>` (a bare `/mcp` without the trailing slash
307-redirects there). `GET /healthz` is unauthenticated and used by the container's `HEALTHCHECK`
and by any external load balancer/uptime check.

A client config pointing at HTTP mode looks like this (shape varies by client — this is the
generic Streamable HTTP form):

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

## Develop

```bash
ruff check src/
pytest
```

## Claude Desktop configuration (stdio mode)

Add to `claude_desktop_config.json`:

```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"
      }
    }
  }
}
```

`cwd` must be the project root so the default `FORTICNAPP_OPENAPI_SPEC=./lw.yaml` resolves;
alternatively set an absolute path as shown above. Prefer a real `.env` file over inlining
secrets in this config where your setup allows it.

## Architecture

```
config.py          env vars -> validated Settings (pydantic-settings), fails fast
openapi_loader.py   lw.yaml/json -> OperationSpec list (resolves $ref/allOf, builds
                    a pydantic input model per operation, infers the token endpoint's
                    field names)
auth.py             ApiKeyAuthStrategy / BearerTokenStrategy / ApiKeyToTokenStrategy;
                    the last is FortiCNAPP's real keyId+secret -> bearer token handshake
http_client.py      httpx.AsyncClient wrapper: builds requests from validated arguments,
                    retries network/5xx errors, retries once on 401 after refreshing auth,
                    follows FortiCNAPP's cursor-style pagination
tool_registry.py    OperationSpec list -> mcp.types.Tool list (resolving any tool-name
                    collisions) and dispatches call_tool requests to http_client
main.py             wires the above into mcp.server.lowlevel.Server + stdio_server
models.py           OperationSpec/OperationParameter (internal) and the ToolCallResult/
                    RequestMeta/PaginationInfo pydantic models every tool returns
errors.py           ForticnappError hierarchy (auth/validation/api/network/spec), each
                    carrying category/status_code/operation_id/retryable
logging_utils.py    structured JSON logs to stderr with header/secret redaction
utils.py            tool-name derivation, mutation/pagination classification, JSON
                    Schema -> Python type mapping
```

Every tool call returns the same structured JSON envelope:

```json
{
  "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
}
```

To fetch the next page, call the same tool again with `page_url` set to
`pagination.next_page_url` from the previous response — every other argument is ignored when
`page_url` is set.

## Customizing the token exchange

If your FortiCNAPP/Lacework 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` that's inferred from the spec at startup
(`openapi_loader.discover_token_operation`) with fallback defaults matching FortiCNAPP's current
contract (`keyId`/`expiryTime` in, `token`/`expiresAt` out, secret carried in `X-LW-UAKS`).
Token caching, proactive refresh, and 401-triggered re-acquisition are all wire-format-agnostic
and live in the surrounding `ApiKeyToTokenStrategy` methods — you shouldn't need to touch them.

## Security notes

- Tokens and secrets are kept in memory only; nothing is persisted to disk.
- `logging_utils.redact_headers()`/`redact_secret()` are used everywhere a header dict or secret
  reaches a log call — `Authorization`, `X-LW-UAKS`, and cookie headers are never logged in full.
- Mutating operations (anything that isn't a GET or a `POST .../search`) are excluded from the
  tool list unless `ENABLE_MUTATION_TOOLS=true`.