Falcosidekick UI MCP Server

# Falcosidekick UI MCP Server This folder contains a lightweight Model Context Protocol (MCP) server that exposes the Falcosidekick UI `/api/v1/events/search` endpoint as a tool. The server uses HTTP Basic Auth (default `admin:admin`) and runs in **streamable HTTP** mode so MCP clients can connect over plain HTTP. ## Layout - `falco_mcp_server.py` – FastMCP implementation exposing Falco events over Falcosidekick UI API via two tools - `requirements.txt` – Python dependencies (`mcp`, `httpx`, `boto3`) - `Dockerfile` – Container image that launches the server on port `8080` - `k8s/` – Deployment and Service manifests to run the server in Kubernetes ## Environment variables | Variable | Default | Description | | --- | --- | --- | | `FALCO_BASE_URL` | `http://localhost:8080` | Falcosidekick UI base URL | | `FALCO_EVENTS_PATH` | `/api/v1/events/search` | Override the events endpoint path if needed | | `FALCO_USERNAME` / `FALCO_PASSWORD` | `admin` / `admin` | Basic Auth credentials | | `FALCO_HTTP_TIMEOUT` | `15` | HTTP timeout in seconds | | `PORT` | `8080` | MCP HTTP listener port | | `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP mount path | | `MCP_TRANSPORT` | `streamable-http` | Set to `stdio` if your MCP client expects stdio transport | ## Available tools | Tool | Description | | --- | --- | | `query_falco_events` | Returns Falco events with normalized `output_fields`. Syscall, k8s_audit, and aws_cloudtrail sources keep only their most useful fields (container/process info, Kubernetes target metadata, CloudTrail principals). All events always retain `uuid`, `time`, `priority`, `rule`, `source`, `description`, and `hostname`. Syscall `proc.cmdline` values are truncated to ~120 chars to limit token usage. Use `start_time` / `end_time` for temporal windows instead of embedding time comparisons inside `filter_query`. | | `falco_full_event_by_id` | Fetches the raw Falco event for a single `uuid`. It builds a UUID filter and leaves the response untouched so you can inspect every original field. | When calling either tool you can pass `start_time` / `end_time` arguments. Provide timestamps in ISO 8601 UTC form (e.g. `2025-11-24T03:59:59.848208Z`). The server converts them to timezone-aware datetimes internally and removes any events that fall outside that window, while still sending `since=1M` upstream to keep the search bounded. ## Local run ```bash cd falco-mcp python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt python3 falco_mcp_server.py ``` Then configure your MCP client with: ```json { "mcpServers": { "falco-events": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` ## Docker ```bash cd falco-mcp docker build -t falco-mcp . docker run -p 8080:8080 \ -e FALCO_BASE_URL=http://falcosidekick-ui.default.svc.cluster.local:2802 \ -e FALCO_USERNAME=admin \ -e FALCO_PASSWORD=admin \ falco-mcp ``` ## Kubernetes The provided manifests assume the Falcosidekick UI is exposed as `http://falcosidekick-ui:2802` and that the admin credentials remain `admin:admin` (see `k8s/falco-mcp-deployment.yaml`). If your environment uses different credentials or a different service name, edit the env vars before deploying. ```bash kubectl apply -f k8s/falco-mcp-deployment.yaml kubectl apply -f k8s/falco-mcp-service.yaml ```