Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
GRAYLOG_URLNoURL of the Graylog instance
GRAYLOG_PROXYNoProxy URL for the env-only instance
GRAYLOG_TOKENNoAccess token of a read-only Graylog user
GRAYLOG_PASSWORDNoPassword for basic auth instead of a token
GRAYLOG_TIMEZONENoDisplay timezone and zone for naive times (default UTC)UTC
GRAYLOG_USERNAMENoUsername for basic auth instead of a token
GRAYLOG_CA_BUNDLENoPath to a CA bundle for TLS verification
GRAYLOG_MCP_CONFIGNoPath of a TOML config file
GRAYLOG_VERIFY_TLSNoTLS verification for the env-only instance
GRAYLOG_APP_PACKAGESNoApplication packages for stack trace folding, e.g. com.acme,/srv/app/
GRAYLOG_MCP_HTTP_TOKENNoBearer token required by the HTTP transport
GRAYLOG_REDACTION_PACKSNoRedaction 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.

  1. Size the problem: aggregate kind='count' / 'histogram' (the 'onset' field marks when a spike started).

  2. Group it: aggregate kind='errors' (exact counts per exception/logger/source, first/last seen, one sample).

  3. Before/after a deploy or incident start: compare_periods with split_at.

  4. Drill down: search_logs with a narrow query; get_message with a 'ref' for one message.

  5. Follow one request across services: trace_request with a trace/correlation/request id.

  6. 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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

NameDescription
scanScan the logs for problems (all rules, or a target) and report the findings

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 9 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues