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

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:

{
  "mcpServers": {
    "falco-events": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Docker

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.

kubectl apply -f k8s/falco-mcp-deployment.yaml
kubectl apply -f k8s/falco-mcp-service.yaml