graylog-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GRAYLOG_URL | No | URL of the Graylog instance | |
| GRAYLOG_PROXY | No | Proxy URL for the env-only instance | |
| GRAYLOG_TOKEN | No | Access token of a read-only Graylog user | |
| GRAYLOG_PASSWORD | No | Password for basic auth instead of a token | |
| GRAYLOG_TIMEZONE | No | Display timezone and zone for naive times (default UTC) | UTC |
| GRAYLOG_USERNAME | No | Username for basic auth instead of a token | |
| GRAYLOG_CA_BUNDLE | No | Path to a CA bundle for TLS verification | |
| GRAYLOG_MCP_CONFIG | No | Path of a TOML config file | |
| GRAYLOG_VERIFY_TLS | No | TLS verification for the env-only instance | |
| GRAYLOG_APP_PACKAGES | No | Application packages for stack trace folding, e.g. com.acme,/srv/app/ | |
| GRAYLOG_MCP_HTTP_TOKEN | No | Bearer token required by the HTTP transport | |
| GRAYLOG_REDACTION_PACKS | No | Redaction packs to enable, e.g. vn,eu |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access to Graylog logs. Nothing you do here changes Graylog. Sensitive values are already masked ([REDACTED], [EMAIL], [CARD], [PHONE], ...); never try to recover them.
Query syntax (Lucene, as in the Graylog search bar):
field:value, field:"exact phrase", AND / OR / NOT (upper case), parentheses for grouping.
Wildcards: message:time* (no leading wildcard). Existence: exists:trace_id.
Ranges: http_status:[500 TO 599], took_ms:>1000, level:<=3.
Escape special characters in values with quotes: path:"/api/v1/orders".
Field names are case-sensitive; call describe(what='fields') when unsure. Streams accept names or ids.
level is usually a syslog number: 0 emerg, 1 alert, 2 crit, 3 error, 4 warning, 5 notice, 6 info, 7 debug. The configured error query (see describe(what='fields')) is what aggregate kind='errors' and compare_periods use.
Environments and groups: each Graylog instance is one environment (dev, staging, prod...), often of one system group (ERP, CXP, PAYMENT...). Call describe to see them. Pass instance='/' (e.g. 'payment/prod'), or the group alone for its default environment, or the environment alone when only one group has it. When the user names a system or an environment, pick that instance; when it is ambiguous, ask. Never mix results from different instances without saying which is which. Focus: inside a repository, search_logs, aggregate, compare_periods and root_cause view='changes' only look at that repository's service (results carry 'focus' with the filter added). Search other services or streams only when the user asks for them: pass streams=['*'] for everything, explicit streams, or a query naming the service field (e.g. application:"other-service"). trace_request and the other root_cause views always span every service. Inside a group's repository only that group is loaded (describe shows 'scope'); if the user asks about another group, say it is not loaded here and how to enable it, as the error explains.
Searches that find nothing: search_logs and aggregate kind='count' try the likely fixes and return 'suggestions', each with its exact count and why (a misspelled field, a level in the other form, letter case, a prefix wildcard, outside the focus, a wider range). Run the one that fits the question rather than guessing again. 'diagnosis' says which AND clause matches nothing and the values its field really has ('did_you_mean'). When a result carries 'rewritten', the query you sent could not match as written (a field this Graylog does not have, a level word on a numeric field) or a fix learned from earlier searches applied: it ran 'ran' instead, for the reasons in 'why'; tell the user when that changes the meaning of their question.
Time: range='15m' | '2h' | '7d', or from_time/to_time as ISO 8601 or 'YYYY-MM-DD HH:MM' (interpreted in the instance timezone shown in results). Output timestamps carry their offset.
Scanning (for "is anything wrong?", "scan for errors", "check X", a health check):
One scan call, not a loop of searches: it runs every rule concurrently with exact counts against a baseline and returns only what fired, most severe first. Triage fast with min_severity='high'.
A specific need becomes ad hoc rules in that same call: checks=[{'name': ..., 'query': ...} + a condition]: threshold (fires when count > N; 0 = any occurrence is bad), growth (the rate grew N times; for things that normally happen, with min_count against noise), or group_by + new_groups (a value the baseline never saw). Put several checks in one call; rules=[names or tags] runs configured rules (describe(what='scan_rules')).
Accurate queries: quoted phrases ("Connection refused") and field:value with real field names (describe); no leading wildcards or regex; add exclude for known noise; errors_only=true reuses the error query.
Growth checks on things that follow traffic (errors, 5xx, timeouts) take per_traffic=true: a busy hour is not an incident. A growth fires only when significant ('confidence' in the result); a 'note' on a quiet rule says it grew but within chance: do not report that as a problem.
Window from the question. Baseline: the period right before by default; baseline='24h' when the window is short; baseline_shift='1d' (or '7d') when traffic has a daily (weekly) curve, e.g. morning peaks.
Read the result as: findings (fired), quiet (checked, normal), skipped (could not check: say so, never call it healthy); 'baseline_note' means the comparison is weaker (missing baseline data). Report severity, count vs baseline, trend, confidence, first seen and the sample's ref.
Then drill into a finding with its 'query': aggregate kind='histogram' (when), kind='errors' (what), search_logs (lines); several findings at once: root_cause.
Suggested investigation flow: 0. For "what is causing this?": root_cause first. It ranks the service that broke first, with nearby deploys (view='changes') and the call graph (view='service_map') as evidence; then verify with the tools below.
Size the problem: aggregate kind='count' / 'histogram' (the 'onset' field marks when a spike started).
Group it: aggregate kind='errors' (exact counts per exception/logger/source, first/last seen, one sample).
Before/after a deploy or incident start: compare_periods with split_at.
Drill down: search_logs with a narrow query; get_message with a 'ref' for one message.
Follow one request across services: trace_request with a trace/correlation/request id.
See what happened around one message: get_message with its 'ref' and context_seconds. Counts from aggregate are exact (computed by Graylog); 'count' inside search_logs groups only covers the returned page. Results are size-capped: when 'truncated' is true, narrow the query or page with next_offset. A field 'ui' is a local link to the same view in the admin page, for the user: give it to them as it is; do not open, fetch or edit it.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_logsA | Search log messages with a Lucene query. Returns compact, redacted lines with a 'ref' (index/id) usable by get_message. Default range: last 15 minutes. |
| aggregateA | Exact counts computed by Graylog. kind='count': number of matching messages, cheap, to size a problem. 'histogram': counts over time with the peak, first/last non-empty bucket and the 'onset' of a spike, to find when a problem started. 'top': top values of the group_by field with counts and percentages. 'errors': errors (configured error query) grouped by exception, logger, source or any field, with first/last seen and a sample message per group. |
| get_messageA | One message with all its fields (redacted), by ref. Long values are cut to keep the answer small: 'cut_fields' names them with their size; pass those names in 'fields' to read them. With context_seconds: the messages logged around it instead. |
| trace_requestA | Follow one request across services: searches the configured trace fields (falls back to full text) on all streams and returns a chronological timeline, per-service steps with durations, and the first error. |
| compare_periodsA | Compare two periods (default: last window vs the one before; or around split_at). Lists groups that are new, increased, gone or decreased, normalised per hour. Defaults to errors only. |
| scanA | Health scan in one call: runs every scan rule (crashes, resource exhaustion, error spikes, new error types, 5xx, timeouts/connectivity, database, auth failures, plus the rules in the config) concurrently with exact counts against a baseline, and returns only what fired, most severe first, with the query, top groups and a sample. Start here for 'is anything wrong?', 'scan for errors', 'check X'. For a specific need pass rules (names/tags) or checks (ad hoc rules). |
| root_causeA | Find which service broke first and why. Compares every service's errors, traffic and latency with a baseline, pins the first error of each to the millisecond, detects deploys/restarts/host rollouts from the logs, infers the call graph from traces, and returns a ranked verdict with a timeline and evidence. Start here for 'what is causing this incident?'. view='changes': only the deploys and restarts found in the logs (new version-field values, host rollouts, start/stop lines). view='service_map': only which service calls which, from sampled traces, with traffic, error rate and p50/p95 latency per edge. |
| describeA | What is there to query. 'instances': configured Graylog instances with detected version, the API in use and active redaction rules. 'streams': streams (id, title, description) the token can read. 'fields': field names (and types where available), plus the configured trace fields and error query; use before writing queries on unfamiliar logs. 'presets': named queries from the configuration. 'scan_rules': scan rules with their query, condition, severity and tags. |
| run_presetA | Run a named preset query, optionally overriding its arguments. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| scan | Scan the logs for problems (all rules, or a target) and report the findings |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 9 tools
Each tool has a reasonably distinct role, and the descriptions include explicit routing hints ('start here for is anything wrong' vs 'what is causing this incident') that separate scan from root_cause. The main soft overlaps are search_logs vs run_preset and aggregate kind='errors' vs scan/compare_periods, but those are clarified enough in text to avoid most misselection.
All names use snake_case and most are verb-first (search_logs, get_message, trace_request, compare_periods, run_preset). Minor deviations are single-verb names (describe, aggregate, scan) and a noun name (root_cause), so the pattern is predictable but not perfectly uniform.
Nine tools is well within the ideal 3-15 range and every tool corresponds to a distinct investigative need (discover, search, count, inspect, trace, compare, scan, diagnose, replay preset). No tool looks like filler and none is obviously missing at this scale.
The surface covers the full read-only log-analysis lifecycle: metadata discovery, querying, aggregation, single-message inspection, cross-service tracing, period comparison, health scanning, root-cause verdicts, and saved presets. Gaps are minor, e.g. no explicit handling of alerts/events or saved-search management, but no typical agent workflow dead-ends.