Skip to main content
Every tool registered in the Superlog MCP server is documented below. Tools are grouped by category. All tools default to the session’s active project when you omit project_id — use set_active_project once at the start of a session to avoid repeating it on every call.
Call set_active_project first in any new session. After that, you can omit project_id from every subsequent tool call.
Telemetry-only tokens (scope superlog:telemetry) can only access the Telemetry and Project tools. Incident, Dashboard, Alert, and Agent Config tools require a full-access token. See MCP Overview for token setup.

​
Telemetry Tools

​
query_logs

Search OpenTelemetry log records stored in the active project. Error-level rows automatically include flattened exception_type, exception_message, and exception_stacktrace fields when the log carries an exception attribute.
​
uuid
Project to query. Defaults to the session’s active project.
​
object
Time window. Both fields accept an ISO-8601 timestamp or a ClickHouse time expression such as now() - INTERVAL 1 HOUR. Defaults to the last hour.
  • since — start of the window (inclusive)
  • until — end of the window (inclusive)
​
string
Filter by service.name. Exact match.
​
string
Filter by severity text, e.g. ERROR, WARN, INFO. Case-insensitive.
​
string
Case-insensitive substring match on the log body.
​
array
Filters on OTel resource attributes. Each entry is { key, value, op? } where op is eq (default), neq, or not_contains.Example: [{ "key": "deployment.environment", "value": "prod" }]
​
array
Equality filters on per-record log attributes (LogAttributes). Each entry is { key, value }.Example: [{ "key": "event.name", "value": "auth.failure" }]
​
integer
Maximum rows to return. Range: 1–500. Default: 50.

​
query_traces

Search OpenTelemetry spans stored in the active project. Spans with exception events automatically include flattened exception_type, exception_message, and exception_stacktrace fields.
​
uuid
Project to query. Defaults to the session’s active project.
​
object
Time window with since and until. Same format as query_logs.
​
string
Filter by service.name. Exact match.
​
string
Filter by span name. Exact match.
​
string
OTel span-level status: STATUS_CODE_OK, STATUS_CODE_ERROR, or STATUS_CODE_UNSET.Note: By the OTel HTTP semantic conventions, only 5xx server responses automatically set STATUS_CODE_ERROR on a span — 4xx responses (including 410, 404, etc.) remain STATUS_CODE_UNSET. To filter spans by HTTP status code, use span_attrs with key: "http.response.status_code" instead.
​
number
Only return spans whose duration is at least this many milliseconds.
​
array
Filters on resource attributes. Same format as query_logs.
​
array
Equality filters on per-span attributes (SpanAttributes). Each entry is { key, value }.Use this to filter by HTTP status code, route template, database statement, etc. — those live in SpanAttributes, not in the span’s OTel status_code.Example: [{ "key": "http.response.status_code", "value": "410" }]
​
integer
Maximum rows to return. Range: 1–500. Default: 50.

​
query_metrics

Fetch metric data points across gauge, sum, histogram, and summary tables. Gauge and sum points carry a scalar value. Histogram and summary points carry count and sum (plus min and max for histograms) instead, because they have no single scalar value.
​
uuid
Project to query. Defaults to the session’s active project.
​
string
Filter by metric name. Exact match.
​
string
Filter by service.name. Exact match.
​
object
Time window with since and until. Same format as query_logs.
​
array
Filters on resource attributes. Same format as query_logs.
​
integer
Maximum rows to return. Range: 1–500. Default: 100.

​
list_services

List distinct service.name values that have emitted telemetry in the given time window.
​
uuid
Project to query. Defaults to the session’s active project.
​
object
Time window with since and until. Defaults to the last hour.

​
Incident Tools

Incident tools require a full-access token. Telemetry-only tokens cannot access these tools.

​
get_incident

Fetch one incident by its UUID and everything needed to explain it. No project_id is required — the project is resolved from the incident record itself. The response includes the incident summary with the agent’s findings (root_cause_text, agent_summary, estimated_impact_text), every linked issue with its stored telemetry sample (trace ID, span ID, stacktrace, attributes), and a pointer to the latest investigation run. To pull live telemetry, take a sample’s trace_id and call query_traces, or filter query_logs / query_traces by the issue’s service and exception type — passing the returned project_id.
​
uuid
required
The UUID from the incident’s URL: https://superlog.sh/incidents/<id>.

​
search_incidents

Search incidents in the active project, sorted by most recent activity first. By default, agent-classified noise (status: autoresolved_noise) is hidden. Pass status: "all" to include it, or status: "autoresolved_noise" to inspect only the noise pile.
​
uuid
Project to search. Defaults to the session’s active project.
​
string
Filter by incident status: open, resolved, autoresolved_noise, merged, or all. Omitting this hides auto-classified noise.
​
string
Filter by assigned severity: SEV-1, SEV-2, or SEV-3.
​
string
Exact match on the incident’s primary service.name.
​
string
Case-insensitive substring matched against the incident title and codename.
​
string
ISO-8601 timestamp. Only incidents with last_seen >= since are returned.
​
string
ISO-8601 timestamp. Only incidents with last_seen <= until are returned.
​
integer
Maximum rows to return. Range: 1–200. Default: 50.

​
Project Tools

​
list_projects

List every project the authenticated user can access, across all of their organizations. The currently active project is marked with active: true. No parameters.

​
get_active_project

Return the project that all tools default to when project_id is omitted. Useful for confirming the active project at the start of a session. No parameters.

​
set_active_project

Change the default project for subsequent tool calls in this session. The new default persists for the lifetime of the access token.
​
uuid
required
The project to make active. Use list_projects to discover valid IDs.

​
Dashboard Tools

Dashboard tools require a full-access token.

​
list_dashboards

List all dashboards in the active project (or project_id).
​
uuid
Defaults to the session’s active project.

​
get_dashboard

Fetch a dashboard with all of its widgets.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard ID from list_dashboards.

​
create_dashboard

Create a new dashboard, optionally seeding template variables. Dashboard template variables are named picklists that drive widget filters. Define a variable here and reference it in widget filter values with the token $name or ${name} — for example, { "key": "deployment.environment", "value": "$env" }. At view time, the dashboard shows a dropdown per variable and substitutes the selected option into every filter that references it.
​
uuid
Defaults to the session’s active project.
​
string
required
Dashboard display name (max 120 characters). A URL slug is generated automatically.
​
array
Template variable definitions. Each entry is { name, options[], defaultValue?, label?, attributeKey? }. Variable names must start with a letter and contain only letters, digits, or underscores.

​
update_dashboard

Rename a dashboard.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard to update.
​
string
required
New display name (max 120 characters).

​
add_dashboard_widget

Append a widget to an existing dashboard. Widget types: Omit layout to use the standard size for the widget type. The grid is 12 columns wide (x is 0–11, w is 1–12). Filter values may reference dashboard template variables with $name or ${name}.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard to add the widget to.
​
string
required
Widget type. One of: timeseries_count, timeseries_metric, trace_table, log_table, markdown.
​
string
required
Widget display title (max 200 characters).
​
object
required
Widget configuration object. Shape depends on type.
​
object
Grid placement { x, y, w, h }. Omit to use the standard size for the widget type.

​
update_dashboard_widget

Patch a widget’s title, config, or layout. Provide only the fields you want to change.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard that contains the widget.
​
uuid
required
Widget to update.
​
string
New display title (max 200 characters).
​
object
Replacement widget configuration.
​
object
Replacement grid placement { x, y, w, h }.

​
delete_dashboard_widget

Remove a widget from a dashboard.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard that contains the widget.
​
uuid
required
Widget to remove.

​
set_dashboard_variables

Replace a dashboard’s entire template-variable list. This overwrites the existing list — call get_dashboard first and edit the returned variables if you want to keep any existing ones.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard to update.
​
array
required
Full set of template variable definitions. Same format as create_dashboard.

​
delete_dashboard

Delete a dashboard and all of its widgets. This action is permanent.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Dashboard to delete.

​
Alert Tools

Alert tools require a full-access token.

​
list_alerts

List all alerts in the active project.
​
uuid
Defaults to the session’s active project.

​
get_alert

Fetch a single alert plus its 50 most recent firings.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Alert ID from list_alerts.

​
create_alert

Create a new alert rule. For logs and traces sources, aggregation must be count. For metric source, aggregation must be sum or avg and metric_name is required.
​
uuid
Defaults to the session’s active project.
​
string
required
Display name for the alert (max 200 characters).
​
string
required
Telemetry source: logs, traces, or metric.
​
string
required
How to aggregate the data: count (logs/traces) or sum/avg (metric).
​
string
required
Comparison direction: gt fires when value > threshold; lt fires when value < threshold.
​
number
required
The numeric threshold to compare against.
​
string
Required when source is metric.
​
object
Equality filters that narrow the data the alert evaluates.
​
string
Resource attribute to group by, e.g. service.name. When set, use group_mode to control how groups fire.
​
string
single rolls all groups up into one evaluation; per_group fires independently per distinct group_by value.
​
integer
Evaluation window in minutes. Range: 1–1440. Default: 5.
​
integer
How often the alert is evaluated, in seconds. Range: 15–3600.
​
boolean
Whether the alert is active. Defaults to true.

​
update_alert

Patch an existing alert. Provide only the fields you want to change. Validation runs on the merged result.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Alert to update.
​
string
New display name.
​
string
logs, traces, or metric.
​
string
count, sum, or avg.
​
string
gt or lt.
​
number
New threshold value.
​
boolean
Enable or disable the alert.
​
string
Required when changing source to metric.
​
object
Replacement filter definition.
​
string
Replacement group-by attribute.
​
string
single or per_group.
​
integer
Replacement evaluation window in minutes.
​
integer
How often the alert is evaluated, in seconds. Range: 15–3600.

​
delete_alert

Permanently delete an alert.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Alert to delete.

​
preview_alert

Evaluate a draft alert specification against current data without saving it. Returns whether the alert would breach right now.
​
uuid
Defaults to the session’s active project.
​
string
required
Display name for the draft alert (max 200 characters).
​
string
required
Telemetry source: logs, traces, or metric.
​
string
required
How to aggregate the data: count (logs/traces) or sum/avg (metric).
​
string
required
gt fires when value > threshold; lt fires when value < threshold.
​
number
required
The numeric threshold to compare against.
​
string
Required when source is metric.
​
object
Equality filters that narrow the data the alert evaluates.
​
string
Resource attribute to group by, e.g. service.name.
​
string
single rolls all groups into one evaluation; per_group fires independently per distinct group_by value.
​
integer
Evaluation window in minutes. Range: 1–1440. Default: 5.
​
integer
How often the alert is evaluated, in seconds. Range: 15–3600.
​
boolean
Whether the alert is enabled in the preview evaluation.

​
test_alert

Re-evaluate a saved alert against current data and return the result.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Alert to test.

​
Agent Config Tools

These tools let you tune how Superlog’s investigation agent works for a project — its issue filter, project context, and durable memories.
Agent config tools require a full-access token.

​
get_issue_filter

Read the project’s issue filter: per-kind include/exclude attribute clauses that decide which ERROR events become issues and incidents. Exclude clauses win. A non-empty include list means an event must match at least one include clause to become an issue.
​
uuid
Defaults to the session’s active project.

​
update_issue_filter

Update the project’s issue filter. Each bucket you provide replaces that bucket; omit a bucket to leave it unchanged; pass [] to clear it. Call get_issue_filter first if you want to add to existing rules rather than overwrite them. Call preview_issue_filter before saving to verify the effect.
​
uuid
Defaults to the session’s active project.
​
array
Log events must match at least one of these clauses (if non-empty) to become an issue. Each clause is { key, value }.
​
array
Span events must match at least one of these clauses (if non-empty) to become an issue.
​
array
Log events matching any of these clauses are dropped and never become issues.
​
array
Span events matching any of these clauses are dropped and never become issues.

​
preview_issue_filter

Preview which recent ERROR events (last 24 hours) would still become issues under a candidate filter, without saving. The buckets you pass are merged over the project’s current filter — same semantics as update_issue_filter. Omit all buckets to preview the currently saved filter.
​
uuid
Defaults to the session’s active project.
​
array
Candidate include clauses for logs.
​
array
Candidate include clauses for spans.
​
array
Candidate exclude clauses for logs.
​
array
Candidate exclude clauses for spans.

​
get_project_context

Read the project’s freeform context — the human-written description of the system (architecture, conventions, key services) that the investigation agent reads on every run.
​
uuid
Defaults to the session’s active project.

​
set_project_context

Overwrite the project’s freeform context (max 8000 characters; longer input is truncated). This replaces the whole field. Call get_project_context first and edit the returned text if you want to preserve existing content. Use this for durable, system-level facts that apply to every investigation; for narrower learnings, prefer create_agent_memory.
​
uuid
Defaults to the session’s active project.
​
string
required
The full context text. Replaces the existing value entirely.

​
create_agent_memory

Store a durable, reusable learning so future investigations inherit it. Record a memory whenever you uncover something worth remembering across investigations — a root-cause pattern, an infra or architecture fact, a domain term, or a correction about how to investigate. Keep the title a short handle and the body the specific, reusable fact — not a one-off incident narrative. Check list_agent_memories first to avoid creating duplicates.
​
uuid
Defaults to the session’s active project.
​
string
required
Memory category:
  • feedback — a correction or preference for how the agent should behave
  • terminology — a domain term or acronym
  • infra — how the system is deployed or operates
  • project — general project facts
​
string
required
Short handle for the memory (max 200 characters).
​
string
required
The specific, reusable fact or instruction (max 4000 characters).

​
list_agent_memories

List all active (and archived) memories stored for the project.
​
uuid
Defaults to the session’s active project.

​
update_agent_memory

Patch a stored memory. Provide only the fields you want to change. Set status: "archived" to retire a memory without deleting it — archived memories stop being injected into investigations but remain visible in list_agent_memories.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Memory ID from list_agent_memories.
​
string
New category: feedback, terminology, infra, or project.
​
string
New title (max 200 characters).
​
string
New body text (max 4000 characters).
​
string
active or archived.

​
delete_agent_memory

Permanently delete a stored memory by ID. To retire a memory reversibly, prefer update_agent_memory with status: "archived" — archived memories stop being injected into investigations but remain visible in list_agent_memories.
​
uuid
Defaults to the session’s active project.
​
uuid
required
Memory ID from list_agent_memories.
  • MCP Overview — authentication setup, client configuration, and token management