Custom Graylog MCP server

Dockerizovaný MCP server pre Graylog s natívnymi nástrojmi, Streamable HTTP transportom a voliteľným OpenAI orchestration nástrojom ask_graylog.

Spustenie

Copy-Item example.env .env
# uprav Graylog URL a API token; OPENAI_API_KEY je voliteľný
docker compose up -d --build

Vďaka pull_policy: build funguje aj jednoduché docker compose up -d; Compose image najprv lokálne zostaví a nebude ho hľadať v Docker registry.

Na lokálne overenie Compose konfigurácie bez produkčných údajov je pripravený example.env:

docker compose --env-file example.env config

Related MCP server: Graylog MCP Server

HTTP/HTTPS reverse proxy cez Caddy

Aplikácia počúva na dvoch samostatných portoch: MCP_PORT pre MCP a agentské REST API, WEBUI_PORT pre WebUI a administračné API. Tieto porty nie sú publikované na hostiteľovi; Caddy k nim pristupuje cez privátnu Compose sieť a je spúšťaný automaticky:

docker compose up -d --build

Nastavenia Caddy sú v .env:

• CADDY_DOMAIN je doména, na ktorej bude služba dostupná. Pri verejnej doméne Caddy automaticky vybaví a obnovuje certifikát Let’s Encrypt; DNS musí smerovať na server a porty 80/443 musia byť dostupné.

• CADDY_EMAIL je kontaktný e-mail pre ACME registráciu.

• CADDY_TLS_DIRECTIVE nechajte prázdne pre Let’s Encrypt. Pre vlastný certifikát nastavte napr. tls /etc/caddy/certs/fullchain.pem /etc/caddy/certs/privkey.pem a súbory vložte do adresára CADDY_CERTS_DIR (predvolene ./caddy/certs).

• CADDY_HTTP_PORT zostáva vyhradený pre ACME overenie a automatické presmerovanie na HTTPS; pri verejnom Let's Encrypt nasadení má zostať na porte 80.

• CADDY_WEBUI_HTTP_PORT, CADDY_MCP_HTTP_PORT, CADDY_WEBUI_HTTPS_PORT a CADDY_MCP_HTTPS_PORT menia porty publikované na hostiteľovi bez úpravy docker-compose.yml. Predvolené hodnoty sú 8080 pre voliteľný HTTP WebUI, 8081 pre voliteľné HTTP MCP, 443 pre HTTPS WebUI a 8443 pre HTTPS MCP.

• CADDY_HTTP_BIND, CADDY_WEBUI_HTTP_BIND, CADDY_MCP_HTTP_BIND, CADDY_WEBUI_BIND a CADDY_MCP_BIND určujú hostiteľské rozhranie pre každý publikovaný port; 0.0.0.0 znamená všetky rozhrania a 127.0.0.1 iba lokálny prístup.

Caddy uchováva ACME účty a certifikáty v ./caddy/data, takže automatická obnova pretrvá aj po reštarte kontajnera. Po zmene certifikátu stačí reštartovať Caddy: docker compose restart caddy.

Endpointy sú oddelené už v aplikácii a Caddy ich iba preposiela: voliteľný HTTP WebUI je na http://logs.example.com:8080/, voliteľný HTTP MCP na http://logs.example.com:8081/mcp, HTTPS WebUI na https://logs.example.com/ a HTTPS MCP na https://logs.example.com:8443/mcp. MCP_PORT odmieta WebUI cesty a WEBUI_PORT odmieta MCP aj agentské /api/v1 cesty. Caddy navyše blokuje MCP cestu na oboch WebUI listeneroch. Port 80 ostáva Caddy k dispozícii pre ACME a HTTPS presmerovanie.

Pre verejný HTTP WebUI cez Caddy a obe natívne rozhrania dostupné iba lokálne použite napríklad MCP_BIND=127.0.0.1, WEBUI_BIND=127.0.0.1, CADDY_WEBUI_HTTP_BIND=0.0.0.0, CADDY_WEBUI_HTTP_PORT=8080 a UI_COOKIE_SECURE=false. MCP_HOST aj WEBUI_HOST ponechajte na 0.0.0.0, aby sa k nim Caddy dostal cez internú Docker sieť. Čisté HTTP nešifruje prihlasovacie údaje ani session cookie; pre nedôveryhodnú sieť používajte HTTPS a UI_COOKIE_SECURE=true.

MCP endpoint pre agenta je cez Caddy http://localhost:8081/mcp (alebo HTTPS https://localhost:8443/mcp; hodnoty portov a cesty sú v .env). Natívny MCP_PORT=8000 je interný Compose port a nie je publikovaný na hostiteľovi. Health check je na /health. Web UI is available through Caddy at http://localhost:8080/ (optional HTTP) or https://localhost/ (HTTPS) and uses a session-based login form at /login with UI_USERNAME and UI_PASSWORD. The native WEBUI_PORT=8001 is internal to the Compose network and is not published. It contains Graylog Servers, MCP Clients, Query Rules, and Audit Log sections. The floating navigation changes to a hamburger menu on mobile. Graylog servers can be added, edited, and tested; leaving the API token blank while editing preserves the existing token.

Query rules are managed in SQLite from the Query Rules UI section. A rule controls the Lucene filter, message/aggregation mode, time range, result limit, grouping, metrics, time bucket, default template parameters, and agent instructions. Definitions from queries.yaml are imported only as initial defaults and can then be edited in the UI. Agentské REST API je dostupné cez Caddy MCP port (http://localhost:8081/api/v1 alebo https://localhost:8443/api/v1), interaktívna Swagger dokumentácia cez http://localhost:8081/docs alebo https://localhost:8443/docs a OpenAPI schéma na /openapi.json. Natívny MCP_PORT=8000 je interný Compose port a nie je publikovaný. Administračné /ui/api je dostupné cez Caddy WebUI port.

MCP klient sa pripája na /mcp cez Authorization: Bearer <agent-api-key>. Rovnaký Bearer kľúč vyžadujú všetky /api/v1 endpointy okrem /health. Každý agent je databázovo viazaný na jeden Graylog server; server sa vyberá podľa API kľúča a klient ho nemôže zmeniť. Výsledky /api/v1/audit sú obmedzené na záznamy daného klienta. Admin operácie v UI sú chránené oddelenými UI_USERNAME/UI_PASSWORD údajmi, CSRF tokenom a obmedzením neúspešných prihlásení.

Nový agent dostane API kľúč v odpovedi pri vytvorení. Kľúč si ulož, pretože databáza uchováva iba jeho hash a posledné štyri znaky.

Oprávnenia MCP klientov

Každý MCP klient má vlastný zoznam povolených nástrojov. Nastavuje sa pri vytvorení alebo úprave klienta v sekcii MCP Clients cez voľby Allowed Graylog tools. Rovnaká kontrola platí pre natívne MCP volania, ask_graylog aj agentské REST API; nepovolený nástroj skončí odpoveďou HTTP 403 s kódom tool_forbidden. Prázdny zoznam znamená zákaz všetkých nástrojov.

Existujúci klienti po migrácii databázy automaticky zachovajú doterajšie správanie a dostanú všetky aktuálne nástroje. Nový klient bez zvoleného obmedzenia má tiež všetky nástroje, takže nasadenie neporuší existujúce integrácie. Pre produkciu odporúčame vytvoriť klienta s minimálnou sadou, napríklad iba search_messages, aggregate a get_log_context.

Príklady REST volaní:

$headers = @{ Authorization = "Bearer AGENT_API_KEY" }
Invoke-RestMethod http://localhost:8081/api/v1/search/messages -Headers $headers -Method Post -ContentType 'application/json' -Body '{"query":"level:3","minutes":15,"limit":20}'
Invoke-RestMethod http://localhost:8081/api/v1/search/aggregate -Headers $headers -Method Post -ContentType 'application/json' -Body '{"query":"*","minutes":60,"group_by":[{"field":"service"}],"metrics":[{"function":"count"}]}'

Audit databáza SQLite sa ukladá do ./data/audit.db a eviduje AI otázky/odpovede aj Graylog API volania/odpovede. Citlivé polia konfigurované cez AUDIT_REDACT_FIELDS sa pred zápisom nahradia hodnotou [REDACTED]. Retenciu nastavujú AUDIT_RETENTION_DAYS, AUDIT_MAX_ROWS a AUDIT_MAX_PAYLOAD_CHARS; čistenie prebieha pri štarte a po každom zápise. Audit log obsahuje aj SQLite FTS5 fulltext index. Vo web UI ho možno prehľadávať podľa slov, fráz, prefixov (timeout*) a boolean výrazov (error OR failed), s voliteľným filtrovaním podľa zdroja.

Bezpečnostné nastavenia

• UI_COOKIE_SECURE=true nastavte pri HTTPS nasadení. Pri lokálnom HTTP musí zostať false.

• TRUSTED_PROXY_CIDRS určuje jediné proxy siete, od ktorých aplikácia prijme X-Forwarded-For. Bez tejto hodnoty sa pre CIDR pravidlá používa bezprostredná adresa spojenia.

• SECRET_ENCRYPTION_KEY voliteľne zapne autentifikované šifrovanie Graylog API tokenov v SQLite. Použite aspoň 32 náhodných znakov, hodnotu bezpečne zálohujte a nemeňte; bez nej sa už zašifrované tokeny nedajú načítať.

• UI_LOGIN_MAX_ATTEMPTS, UI_LOGIN_WINDOW_SECONDS a UI_LOGIN_MAX_CLIENTS riadia obmedzenie neúspešných prihlásení aj maximálnu veľkosť jeho pamäťového úložiska.

• Ručne zadaný MCP API kľúč musí mať najmenej 24 znakov. Automaticky generované kľúče používajú kryptograficky bezpečný generátor.

• Databáza pri štarte zapína foreign keys, WAL a busy timeout a automaticky doplní bezpečné P0 migrácie.

Managed query rules

Queries are created and edited in the Query Rules section of the Web UI and persisted in SQLite. Supported types are messages and aggregate. Template parameters such as ${name} can be supplied through the run_saved_query MCP tool. The bundled queries.yaml file is used only to seed an empty database.

Native tools: search_messages, aggregate, list_streams, list_saved_queries, run_saved_query, search_error_patterns, compare_time_windows, get_log_context, and ask_graylog.

AI-facing search and aggregation tools return compact responses with the original query, time range, result count, truncation status, and normalized items/groups. Use aggregate or search_error_patterns before requesting raw messages. The specialized analysis tools compare adjacent time windows, group recurring error patterns, and retrieve bounded context around an ISO-8601 timestamp. The same operations are available through /api/v1/search/error-patterns, /api/v1/search/compare-windows, and /api/v1/search/context.

Graylog calls use bounded retries for transient network and 429/5xx failures, with exponential backoff and a circuit breaker. Configure these with GRAYLOG_RETRY_ATTEMPTS, GRAYLOG_RETRY_BACKOFF_SECONDS, GRAYLOG_CIRCUIT_FAILURE_THRESHOLD, and GRAYLOG_CIRCUIT_RECOVERY_SECONDS. The AI orchestration stores a structured internal result containing the answer, round count, tool calls, tool errors, and truncation status; the public MCP response remains text-compatible. Evaluation scenarios are maintained in evals/graylog_questions.yaml and can be extended with production questions.

API compatibility and extension points

The /api/v1 contract is versioned by the X-API-Version: 1 response header. Existing response payloads remain unchanged for compatibility; errors use the stable public error shape (code, detail, and request_id). New API versions will be introduced under a new path or after a documented deprecation period.

The application factory accepts optional repository, secret-provider, and session-store implementations. The bundled SQLite repository, local Fernet secret cipher, and bounded in-process sessions remain the defaults. Custom implementations only need to follow the protocols in graylog_mcp/persistence/protocols.py; route and authentication code does not need to be changed.

Operational procedures for health/readiness, backup, migrations, rollback, proxy trust and security are documented in OPERATIONS.md. SQLite is stored in the Docker named volume graylog_data; this is intentional for deployments whose source tree is on OneDrive or another synchronised filesystem.

The project quality gate is reproducible with uv sync --locked --group dev; CI runs tests with a 70% coverage threshold, Ruff, mypy, pip-audit, Gitleaks, Compose validation, and a container build. Runtime probes are /health for process liveness, /ready for database readiness, and /metrics for the Prometheus-compatible operational counters.

Poznámky

Server používa Graylog Search Scripting API endpointy /api/search/messages a /api/search/aggregate. Graylog autentifikácia používa API token v Basic Auth formáte TOKEN:token; nastavuje sa cez GRAYLOG_API_TOKEN. Agregačné group_by položky používajú Graylog formát, napr. {field: service}; časové buckety možno pridať cez interval. Pri staršej alebo výrazne customizovanej verzii Graylogu sa endpointy dajú zmeniť v graylog_mcp/graylog.py. Do produkcie odporúčam HTTPS/reverse proxy pred MCP endpointom a Graylog používateľa s minimálnymi potrebnými právami.