MCP Tools Reference

The groundcover MCP server exposes tools for querying observability data (logs, traces, events, live entities, monitor issues, metrics, monitor definitions), discovering metadata (field names and values) before writing those queries, and running optional groundcover Agent async tasks for exploration, root-cause analysis, log analysis, trace analysis, and generating dashboards and monitors. Most query tools accept a gcQL pipeline; query_metrics accepts PromQL.

Tenant & backend scoping

Each tool call runs against a single workspace (tenant and backend), resolved automatically: with OAuth your agent selects it via the list_workspaces tool; with an API key the tenant comes from the key and a single backend is auto-selected. When the choice is ambiguous (you have multiple workspaces, or a tenant with multiple backends), target one explicitly with the optional tenant_uuid / backend_id parameters described under list_workspaces.

Tool Overview

Tool	Category	Signal	Query language	Time-bound
list_workspaces	Workspace discovery	—	n/a	no
query_logs	Signal query	Logs	gcQL	yes
query_traces	Signal query	Traces / spans	gcQL	yes
query_events	Signal query	Kubernetes events	gcQL	yes
query_entities	Signal query	Live entities	gcQL	no (live state)
query_issues	Signal query	Monitor issue firings	gcQL	yes
query_metrics	Signal query	Metrics	PromQL (4 modes)	yes
query_monitors	Signal query	Monitor definitions	gcQL filter	no
async_explore_data	groundcover Agent async	Logs / traces / metrics / events / entities / issues / APM	natural language	yes
async_investigate_rca	groundcover Agent async	Cross-signal investigation	natural language	no
async_analyze_logs	groundcover Agent async	Logs	natural language	no
async_generate_dashboard	groundcover Agent async	Dashboard draft	natural language	no
async_generate_monitor	groundcover Agent async	Monitor draft	natural language	no
async_analyze_trace	groundcover Agent async	Traces	natural language	no
get_async_job	Async lifecycle	—	n/a	no
cancel_async_job	Async lifecycle	—	n/a	no
search_logs_metadata	Metadata discovery	Logs	n/a	yes
search_traces_metadata	Metadata discovery	Traces	n/a	yes
search_events_metadata	Metadata discovery	Events	n/a	yes
search_metrics_metadata	Metadata discovery	Metrics	n/a	yes

Workspace Discovery

list_workspaces

List the tenants (workspaces) and their backends that the authenticated caller can query. Call this first to discover which tenant_uuid and backend_id values to pass to the query tools.

For OAuth (member) auth, it returns every tenant you belong to; for API-key (service-account) auth, it returns the single tenant the credential is scoped to.

Parameters

None.

Returns

A list of workspaces, sorted by organization name. Each entry contains:

Field	Type	Description
tenant_uuid	string	Tenant UUID — pass as tenant_uuid to a query tool to target this workspace.
org_name	string	Organization name.
tenant_name	string	Tenant name, when set.
backends	string[]	Active backend IDs for the tenant — pass one as backend_id when the tenant has more than one.

Routing query tools

Every query_* and search_* tool accepts two optional routing parameters:

Parameter	Type	Required	Description
tenant_uuid	string	no	Tenant to route the call to. Only needed when your account has more than one workspace.
backend_id	string	no	Backend to route the call to. Only needed when the tenant has more than one backend.

A single workspace (and single backend) is selected automatically, so you only need these when the choice is ambiguous.

groundcover Agent async tools

groundcover Agent async tools start longer-running agent work and return immediately with a job descriptor. They do not return the final result in the start call.

How async jobs work

Start with one of the async_* tools. The response includes job_id, conversation_id, and a next_action for get_async_job. Call get_async_job with those values until job.status is completed, failed, or cancelled. Each get_async_job call uses bounded long polling; wait_seconds can be 0 through 20 seconds. A disconnected poll does not cancel the durable run.

groundcover Agent async tools are available only when AI features are enabled for the selected backend. They create private retained agent run state, but they do not edit monitors, acknowledge alerts, change pipelines, create incidents, deploy code, or persist dashboards.

Common async start parameters

Parameter	Type	Required	Description
prompt	string	yes	Natural-language request. Include the relevant scope, resources, time range, and goal.
conversation_id	string	no	Conversation ID from a previous async job, when you want to continue or refine the same conversation.
tenant_uuid	string	no	Tenant to route the call to. Only needed when your account has more than one workspace.
backend_id	string	no	Backend to route the call to. Only needed when the tenant has more than one backend.

async_explore_data also accepts the time-window parameters used by query tools (start, end, period) and an optional signal selector.

async_explore_data

Start an asynchronous exploration of observability data from a natural-language request. It submits the widget agent and returns job_id and conversation_id; call get_async_job to retrieve the final widget result.

When to use it

• Scout a visualization or data slice before writing exact queries.

• Explore a cross-signal question where the best source is not obvious yet.

• Generate a widget-shaped result that includes query specs and, when available, sampled data.

Additional parameters

Parameter	Type	Required	Description
signal	string	no	Optional data type to force: logs, traces, metrics, events, entities, issues, or apm. Leave empty to let the agent infer or combine signals.

Completed result

A widget result envelope containing output, optional data, optional time_range, conversation_id, and queried_signals. Treat the returned data as a lead: confirm important findings with direct query and metadata tools.

Example prompt

Use groundcover to explore p95 latency and error rate for checkout over the last hour.

async_investigate_rca

Start an asynchronous root-cause investigation from a natural-language request. It returns job_id and conversation_id; call get_async_job to retrieve the report.

When to use it

• Investigate a suspected incident or monitor firing across multiple signals.

• Ask for a structured RCA summary after providing the affected service, namespace, issue link, or time window.

Completed result

A Markdown RCA report. Verify material conclusions with direct query tools before treating them as confirmed facts.

Example prompt

Use groundcover to investigate why checkout errors spiked in production around 10:30 UTC.

async_analyze_logs

Start an asynchronous log analysis from a natural-language request. It returns job_id and conversation_id; call get_async_job to retrieve the analysis.

When to use it

• Summarize patterns in logs for a scoped service, namespace, workload, or time range.

• Group recurring errors and highlight examples that deserve a direct follow-up query.

Completed result

A Markdown log-analysis report. Verify important patterns with query_logs or search_logs_metadata before presenting them as final evidence.

Example prompt

Use groundcover to analyze error logs for the payments namespace in the last 30 minutes.

async_generate_dashboard

The tool does not create a dashboard directly in groundcover, instead it generates the JSON which can be uploaded via API or a provisioner like Terraform.

Start asynchronous dashboard draft generation from a natural-language request. It returns job_id and conversation_id; call get_async_job to retrieve the dashboard draft.

When to use it

• Draft a dashboard layout and widgets from a goal, service, namespace, or troubleshooting scenario.

• Generate a starting point that a human can review before saving as a dashboard.

Completed result

A dashboard draft wrapper containing:

Field	Type	Description
name	string	Suggested dashboard name.
description	string	Optional dashboard description.
preset	object	Dashboard preset JSON.

Preserve the full wrapper when presenting the draft; only the nested preset is serialized when using dashboard-create APIs.

Example prompt

Use groundcover to draft a dashboard for checkout service health: request rate, error rate, p95 latency, and pod restarts.

async_generate_monitor

The tool does not create a monitor directly in groundcover, instead it generates a YAML draft which can be uploaded via API or a provisioner like Terraform.

Start asynchronous monitor draft generation from a natural-language request. It returns job_id and conversation_id; call get_async_job to retrieve the monitor draft.

When to use it

• Draft an alerting monitor from a goal, service, namespace, or alerting scenario.

• Generate a starting point that a human can review before creating the monitor.

Completed result

A YAML monitor draft.

Example prompt

Use groundcover to draft a monitor that alerts when checkout error rate exceeds 5% over 10 minutes.

async_analyze_trace

Start asynchronous trace analysis from a natural-language request. It returns job_id and conversation_id; call get_async_job to retrieve the analysis.

When to use it

• Analyze a single trace by trace_id/span_id.

• Analyze a population of traces for a workload, filter, or time range.

Completed result

A Markdown trace-analysis report. Verify important conclusions with query_traces before presenting them as confirmed facts.

Example prompt

Use groundcover to analyze why trace abc123 in the checkout service was slow.

get_async_job

Read an async job's current status and, when complete, its tool-specific result.

Parameters

Parameter	Type	Required	Description
job_id	string	yes	Job ID returned by an async start tool.
conversation_id	string	yes	Conversation ID returned by an async start tool.
wait_seconds	integer	no	Long-poll wait time from 0 through 20 seconds. Defaults to 15.
tenant_uuid	string	no	Tenant UUID from the async tool's next_action.
backend_id	string	no	Backend ID from the async tool's next_action.

Returns

A stable job envelope. While job.status is working, call get_async_job again with the returned arguments. When job.status is completed, the response includes the original tool-specific result. When job.status is failed, the response includes a sanitized error. When job.status is cancelled, there is no result.

cancel_async_job

Request cancellation for an async job and read the resulting durable status.

Parameters

Parameter	Type	Required	Description
job_id	string	yes	Job ID returned by an async start tool.
conversation_id	string	yes	Conversation ID returned by an async start tool.
tenant_uuid	string	no	Tenant UUID from the async tool's next_action.
backend_id	string	no	Backend ID from the async tool's next_action.

Cancellation can race with completion or failure. If the run has not reached a terminal state yet, the tool returns working and a next_action for get_async_job.

Signal Query Tools (gcQL)

Common Parameters

All gcQL signal tools share the parameters below. query_entities is the exception on time: it queries live state and ignores start / end / period.

Parameter	Type	Required	Description
query	string	yes	gcQL query string. Must start with a filter or *. Always include | limit N.
start	string (RFC3339)	no	Window start. Defaults to 1 hour ago.
end	string (RFC3339)	no	Window end. Defaults to now.
period	string (ISO 8601 duration)	no	Relative window, for example PT15M, PT1H, P1D. Defaults to PT1H.

query_metrics and query_monitors use a different shape - see their dedicated sections below.

Every gcQL query_* tool returns the JSON response of the executed pipeline. When the row count exactly equals the effective limit, the server appends a follow-up text block warning that results were truncated, plus a link to the gcQL reference - the agent should refine the query rather than paginate.

query_logs

Run a gcQL query against logs.

When to use it

• Investigate errors, warnings, or arbitrary log text for a workload, namespace, or trace.

• Aggregate log volume, error rates, or latest message per group.

• Correlate logs with traces or issues via _from subqueries inside join / union / in().

Examples

Latest 10 production errors, newest first:

filter env:production level:error | sort by (_time desc) | limit 10

Error rate per workload, surfacing only workloads above 5% errors, in a single query:

* | stats by (env, cluster, namespace, workload)
    count() as total,
    count() if (level:error) as errors
| math errors / total * 100 as error_pct
| filter error_pct > 5
| sort by (error_pct desc)
| limit 20

query_traces

Run a gcQL query against trace spans.

When to use it

• Identify slow services, endpoints, or operations.

• Quantify HTTP error rates (4xx / 5xx) or span-level errors.

• Pull the spans behind a specific trace_id to investigate a request.

Examples

Slow checkout calls (>500 ms):

* | filter service.name:checkout | filter duration_seconds>0.5 | limit 10

5xx count per service:

* | filter http_status_code>=500 | stats by (service.name) count() as errors | sort by (errors desc) | limit 20

p95 latency per workload, top 5:

* | stats by (workload) quantile(0.95, duration_seconds) as p95
| sort by (p95 desc)
| limit 5

query_events

Run a gcQL query against Kubernetes events.

When to use it

• Find OOMKills, crash loops, scheduling failures, or any abnormal cluster event.

• Correlate cluster activity with logs and traces during an incident.

Examples

Recent OOMKilled events:

* | filter type:Warning reason:OOMKilled | sort by (_time desc) | limit 10

Top warning reasons in production:

* | filter env:production type:Warning
| stats by (reason) count() as count
| sort by (count desc)
| limit 20

query_entities

Run a gcQL query against the live state of entities tracked by groundcover. This includes Kubernetes resources (Pods, Deployments, Services, Nodes, etc.) as well as non-Kubernetes entities. Reflects the current snapshot - does not accept time parameters.

When to use it

• Inspect the spec or status of a specific resource (a Deployment, a Pod, a Node).

• Count or group entities by current state (Running / Pending / Failed).

• Discover which entity kinds and fields exist in the cluster.

Examples

Fetch a single deployment:

kind:Deployment name:chat-app | limit 1

Running pods, top 10:

kind:Pod status_phase:Running | limit 10

Deployment readiness summary:

kind:Deployment | fields name, namespace, ready_replicas, replicas | limit 20

Node count by status:

kind:Node | stats by (status) count() | limit 10

Drilling into the underlying Kubernetes object

The full Kubernetes object is exposed as discoverable raw_json.* paths (not as a single scalar column - | fields raw_json returns empty). Project specific paths and filter by them directly:

kind:Pod namespace:flux-system | fields name, raw_json.spec.serviceAccountName, raw_json.spec.containers | limit 5

The exact paths depend on the kind. For Pods the container/SA paths are raw_json.spec.containers and raw_json.spec.serviceAccountName. For Deployments and other workloads that wrap a Pod template they are raw_json.spec.template.spec.containers and raw_json.spec.template.spec.serviceAccountName. Use kind:<EntityKind> | field_names to enumerate every available path for that kind.

Notes

• Field discovery for entities is kind-scoped: kind:Pod | field_names, kind:Deployment | field_names, etc. The available fields differ between kinds. See the field discovery cheat sheet.

• raw_json itself has no scalar column; it surfaces only via dotted paths like raw_json.metadata.*, raw_json.spec.*, raw_json.status.*.

query_issues

Run a gcQL query against monitor issue instances - active alerts and historical firings produced by your monitors. Use query_monitors first to find a monitor's identity, then drill into its firings here.

When to use it

• List active alerts in an environment or namespace.

• Identify the noisiest monitors (most firings) over a window.

• Drill from a monitor's identity into the underlying signals (with query_logs / query_traces afterward).

Examples

Recent issues in production:

* | filter env:production | sort by (_time desc) | limit 10

CPU-related monitors, most recent firing first:

* | filter monitor_name:*cpu* | sort by (_time desc) | limit 10

Firing count per monitor:

* | stats by (monitor_name) count() as firings | sort by (firings desc) | limit 20

Notes

• Common fields: id, monitor_id, monitor_name, state, previous_state, severity, cluster, env, namespace, workload, summary, silence_ids, timestamp. Use * | field_names to discover the full list.

• An issue is silenced when silence_ids is non-empty.

---

query_metrics

Query metrics from groundcover. Unlike the gcQL signal tools, query_metrics runs PromQL and exposes several modes:

Mode	Purpose
get_names	Discover metric names, optionally filtered by substring or required names.
get_labels	List the label keys for a specific metric.
query_instant	Execute a PromQL query at a point in time.
query_range	Execute a PromQL range query over a time window.

Parameters

Parameter	Type	Required	Description
mode	enum	yes	One of get_names, get_labels, query_instant, query_range.
metricName	string	for get_labels	The metric to inspect.
promql	string	for query modes	PromQL expression. Use names verified via get_names.
filter	string	no	Substring filter for get_names / get_labels.
required	string[]	no	Required metric names for get_names.
step	string	no	Step interval for range queries (default 1m).
clusters / envs	string[]	no	Optional cluster / environment filters.
start / end / period	see common params	no	Time window.
limit / skip	integer	no	Pagination for discovery modes.

Examples

Discover CPU-related groundcover metrics:

{
  "mode": "get_names",
  "filter": "groundcover_node_cpu",
  "limit": 10
}

Get the labels for a metric:

{
  "mode": "get_labels",
  "metricName": "groundcover_node_capacity_cpum_cpu",
  "period": "PT15M"
}

Instant query - total CPU capacity per cluster:

{
  "mode": "query_instant",
  "promql": "sum(groundcover_node_capacity_cpum_cpu) by (cluster)",
  "period": "PT5M"
}

Notes

• Native groundcover metrics start with the groundcover_ prefix and include both a description and a unit in the get_names response.

• Always pull names with get_names first - the response carries the canonical name to plug into promql.

• Returned timestamps are in UTC.

---

query_monitors

List configured monitor definitions and their current health status. Use this to discover monitors before drilling into their firings via query_issues.

Parameters

Parameter	Type	Required	Description
query	string	no	gcQL filter string. Supported fields: monitor_name, type. Examples: monitor_name:*api*, type:prometheus.
limit / skip	integer	no	Pagination.

This tool is not time-bound and does not accept start / end / period.

Examples

List all monitors (paged):

(no query)

Find checkout-related Prometheus monitors:

monitor_name:*checkout* type:prometheus

Find all traces-driven monitors:

type:traces

Notes

• Returns objects shaped { uuid, title, type }. Note the field-name mapping when crossing tools: the filter field here is monitor_name, but the result field is title; both carry the same value. In query_issues, the corresponding fields are monitor_id (matches uuid) and monitor_name (matches title).

• Use query_monitors for definitions, query_issues for instances - don't try to fetch alert history here.

---

Metadata Discovery Tools

These tools take a list of keywords and return matching field names with sample values. Use them to discover what fields exist before writing a query_* call.

Common Parameters

Parameter	Type	Required	Description
keywords	string[]	yes	Search terms matched against field names and values. At least one keyword required.
limit	integer	no	Max results to return. Defaults to 1000.
start	string (RFC3339)	no	Window start. Defaults to 1 hour ago.
end	string (RFC3339)	no	Window end. Defaults to now.
period	string (ISO 8601 duration)	no	Relative window. Defaults to PT1H.

Field Discovery Cheat Sheet

Pick the right discovery method based on what you're querying:

To discover...	Use
Log fields	search_logs_metadata
Trace / span fields	search_traces_metadata
Event fields	search_events_metadata
Metric names and labels	search_metrics_metadata (or query_metrics with mode:get_names / mode:get_labels)
Entity fields (live state)	kind:<EntityKind> | field_names inside query_entities (kind-scoped)
Issue fields	* | field_names inside query_issues
Monitor definitions	query_monitors (filter on monitor_name / type; results return title and uuid - same values, different field names)

search_logs_metadata

Search log field names and sample values.

When to use it

• The agent doesn't know the exact log attribute name (workload vs k8s.workload.name, etc.).

• The user mentions a domain term ("checkout", "tenant", "request_id") and the agent needs to find which fields surface it.

Example call

{
  "keywords": ["checkout"],
  "period": "PT1H"
}

search_traces_metadata

Search span attribute keys and sample values.

When to use it

• Discover trace attributes for a service (service.name, http.path, http_status_code, etc.).

• Find which span attributes carry a particular business identifier.

Example call

{
  "keywords": ["http", "status"],
  "period": "PT15M"
}

search_events_metadata

Search Kubernetes event fields and sample values.

When to use it

• Look up event reasons (OOMKilled, BackOff, FailedScheduling) before filtering.

• Find the correct entity / object fields for a specific resource kind.

Example call

{
  "keywords": ["OOMKilled"],
  "period": "P1D"
}

search_metrics_metadata

Search metric names and their label keys / values.

When to use it

• Quick keyword-based discovery of what metrics exist.

• For more structured discovery (filtered name lists, label keys for a single metric), prefer query_metrics with mode:get_names or mode:get_labels.

Example call

{
  "keywords": ["cpu", "container"],
  "period": "PT1H"
}