Loki MCP Server Tools Reference

The TalkOps Loki MCP Server provides 9 specialized tools divided into 4 categories: schema discovery, log structure analysis, preflight query safety, and unified LogQL execution.

---

1. Schema & Label Discovery Tools

get_cluster_labels

Discover the global label taxonomy indexed in the Loki cluster. Always call this tool first to avoid hallucinating non-existent label names.

Parameters:

Parameter	Type	Required	Description
start	string	No	Start time (ISO timestamp or duration string like '1h', '24h').
end	string	No	End time (ISO timestamp). Defaults to current time.

Example Invocation:

{
  "start": "24h"
}

---

get_label_values

Retrieve all distinct indexed values for a specific label name, with optional stream selector scoping.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Label name to inspect (e.g. app, namespace, environment).
query	string	No	Stream selector expression to scope values.
start	string	No	Start time.
end	string	No	End time.

Example Invocation:

{
  "name": "app",
  "query": "{namespace=\"production\"}"
}

---

get_active_series

Validate active streams matching a selector and inspect per-label cardinality. Use this to identify high-cardinality labels that should not be placed in stream selectors.

Parameters:

Parameter	Type	Required	Description
match	array[string]	Yes	Array of stream selector expressions.
start	string	No	Start time.
end	string	No	End time.

Example Invocation:

{
  "match": ["{app=\"frontend\"}"]
}

---

2. Structure & Pattern Analysis Tools

get_log_patterns

Discovers recurring log line structures and auto-suggests pattern parser expressions. Requires Loki's pattern ingester.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Target stream selector expression.
start	string	No	Start time window.
end	string	No	End time window.

Example Invocation:

{
  "query": "{app=\"payment-service\"}"
}

---

get_detected_fields

Discovers structured JSON/logfmt keys, data types, estimated cardinality, and recommended parser stages from matching log entries. (Requires Loki 3.0+).

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Target stream selector expression.
start	string	No	Start time window.
end	string	No	End time window.

Example Invocation:

{
  "query": "{namespace=\"production\"}"
}

---

3. Safety & Preflight Tools

get_query_stats

Estimates query cost before running heavy operations. Returns total streams, chunks, entries, and estimated bytes to scan.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	LogQL query expression to evaluate.
start	string	No	Start time.
end	string	No	End time.

Example Output:

{
  "total_streams": 12,
  "total_chunks": 48,
  "total_entries": 14200,
  "estimated_bytes": 18450000,
  "estimated_bytes_formatted": "17.6 MB",
  "safe_to_execute": true
}

---

4. Query Execution Tools

execute_logql_instant

Executes point-in-time LogQL instant queries for scalar answers, current rate snapshots, and top-N ranking metrics.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	LogQL metric expression.
time	string	No	Instant evaluation timestamp. Defaults to now.
limit	integer	No	Maximum series to return (default: 100).

Example Invocation:

{
  "query": "topk(5, sum(rate({app=\"api\"} |= \"error\" [5m])) by (endpoint))"
}

---

execute_logql_query

Primary query execution tool. Executes LogQL range queries for raw log streams or time-series metrics (rate(), count_over_time(), quantile_over_time()).

Parameters:

Parameter	Type	Required	Description
query	string	Yes	LogQL stream or metric expression.
start	string	No	Start time (ISO timestamp or duration like '15m', '2h').
end	string	No	End time (ISO timestamp).
limit	integer	No	Maximum log lines to return (default: 1000, clamped to 5000).
step	string	No	Step interval for metric queries (e.g. '15s', '1m').
direction	string	No	Log stream sort order: 'backward' (newest first) or 'forward'.

Example Invocation:

{
  "query": "{namespace=\"production\", app=\"auth-service\"} |= \"error\" | json",
  "start": "1h",
  "limit": 100
}

---

loki_query_a2ui

Executes a LogQL range query and formats the returned logs directly into an interactive A2UI table structure with severity color coding and field expansion.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	LogQL query expression.
start	string	No	Start time.
end	string	No	End time.
limit	integer	No	Maximum entries to render (default: 200).