Skip to main content

MCP Tools Reference

The MCP server exposes 45 tools. 33 are read-only (annotated with readOnlyHint: true). Twelve are write operations that modify state or trigger actions (readOnlyHint: false). Write tools carry annotation hints so clients can gate confirmation appropriately: run_runbook sets destructiveHint: true; the alert/session/trigger tools set destructiveHint: false (additive, reversible) and idempotent ones (acknowledge_alert, resolve_alert, unsilence_alert, cancel_runbook) set idempotentHint: true. Responses are formatted as markdown tables and truncated to the server's configured token limit (default 4000 tokens).

Structured output

List/table tools also return machine-readable structuredContent with an auto-generated outputSchema alongside the human markdown — a { "columns": [...], "rows": [[...]] } object — so clients can parse results without scraping the text table. Every data-returning tool emits structured output: the table tools use the shared {columns, rows} shape; the rich detail tools (get_host_metrics, compare_hosts, get_host_details, get_alert_context, get_compliance_score, get_rollout, preview_runbook, get_runbook_status) each have a bespoke schema mirroring their markdown (e.g. get_host_metrics exposes computed stats/trend/spikes/series). The three Version Currency tools add a notice string to that shape, carrying the caveat that qualifies every row — a client parsing only structuredContent gets the currency facts and the bound on what they mean.

Pagination metadata

The primary paginated list tools (query_hosts, get_active_alerts, get_changes, list_runbooks, list_rollouts, query_products) include a structured pagination block in their structuredContent — { "count", "total", "limit", "offset", "has_more", "next_offset" } — so clients can page programmatically instead of parsing the human "Showing N of M" line. total is -1 when the backend does not report a total; pass next_offset back as offset to fetch the next page. (MCP has no protocol-native cursor for tool results — this metadata block is the structured equivalent.)

Hosts​

query_hosts​

Search and list infrastructure hosts. Returns a table with hostname, OS, CPU, memory, agent status, and more.

ParameterTypeRequiredDescription
clientstringNoFilter by client name
environmentstringNoFilter by environment name
osstringNoFilter by operating system (e.g. Ubuntu 22.04)
statusstringNoFilter by agent status: online or offline
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip for pagination

Example prompt: "Show me all online Ubuntu hosts in the production environment"


get_host_details​

Get detailed information about a specific host including system info, network, agent status, security settings, and cloud metadata.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server to inspect
sectionsstring[]NoAdditional sections: services, packages, ports, containers, security

Example prompt: "Show me full details for web-01.prod including its services and open ports"


compare_hosts​

Compare two hosts side-by-side showing differences in OS, CPU, memory, agent version, status, and more.

ParameterTypeRequiredDescription
host_astringYesHostname of the first server
host_bstringYesHostname of the second server
fullbooleanNoShow all fields instead of only differences (default false)

Example prompt: "Compare web-01 and web-02 — what's different?"


Metrics​

list_host_metrics​

List all available metric names for a host. Use this to discover what metrics can be queried with get_host_metrics before requesting time-series data.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server

Example prompt: "What metrics are available for db-01?"


get_host_metrics​

Get time-series metrics for a host with summary statistics (current, avg, min, max, P95), trend detection (rising/falling/stable), and spike detection.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server
metricstringYesMetric name (e.g. cpu_usage_percent, memory_usage_percent, disk_usage_percent)
rangestringNoTime range: 1h, 6h, 24h, 7d (default 1h)

Example prompt: "What's the CPU usage trend for db-01 over the last 24 hours?"

Response includes:

  • Summary statistics (current, average, min, max, P95)
  • Trend analysis (rising, falling, or stable with percentage change)
  • Spike detection (values exceeding 2x the average)
  • Downsampled data table

Compliance​

get_compliance_score​

Get compliance posture and scores for a host, environment, or client. Returns framework compliance scores with category breakdowns.

ParameterTypeRequiredDescription
hostnamestringNo*Hostname to get compliance for
environmentstringNo*Environment name to get compliance for
clientstringNo*Client name to get compliance for

*Provide exactly one of hostname, environment, or client.

Example prompt: "What's the compliance score for the staging environment?"


get_compliance_failures​

Get compliance check failures for a host from the latest healthcheck run. Shows failed rules with category, severity, and remediation guidance.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server
categorystringNoFilter by category (e.g. security, patch_and_vuln, networking)
limitintNoMaximum results (default 20)

Example prompt: "Show me all security compliance failures on web-01"


get_findings​

Get security scanner findings (vulnerabilities, CVEs) for a host from the latest scan.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server
severitystringNoFilter by severity: critical, high, medium, low
limitintNoMaximum results (default 20)

Example prompt: "Are there any critical CVEs on db-01?"


list_frameworks​

List available compliance frameworks with their names, versions, and descriptions. Use this to discover which frameworks are configured before querying scores.

No parameters required.

Example prompt: "What compliance frameworks are configured?"


get_top_failures​

Get the top failing compliance controls across an environment or client. Shows control code, title, category, severity, and how many hosts are failing.

ParameterTypeRequiredDescription
environmentstringNo*Environment name to get top failures for
clientstringNo*Client name to get top failures for
limitintNoMaximum results (default 10, max 50)

*Provide exactly one of environment or client.

Example prompt: "What are the top 5 failing controls in the production environment?"


get_compliance_evaluations​

Get detailed compliance control evaluations for a host. Shows each control's status (pass/fail/warning), category, severity, framework, and evaluation reason.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the server
statusstringNoFilter by status: pass, fail, warning, unknown, not_applicable, excepted
framework_idstringNoFilter by framework UUID
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Show me all failing compliance evaluations for web-01"


Changes​

get_changes​

Get recent infrastructure change events. Shows timestamp, hostname, event type, severity, and summary.

ParameterTypeRequiredDescription
hostnamestringNoFilter by hostname
environmentstringNoFilter by environment name
clientstringNoFilter by client name
event_typestringNoFilter by type (e.g. package_installed, service_changed, file_modified)
severitystringNoFilter by severity: critical, high, medium, low, info
rangestringNoTime range: 1h, 6h, 24h, 7d (default 24h)
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "What changed on production hosts in the last 7 days?"


Logs​

search_logs​

Search infrastructure logs using LogsQL queries. Returns matching log lines.

ParameterTypeRequiredDescription
querystringYesLogsQL query expression (e.g. level:ERROR or _msg:timeout)
hostnamestringNoFilter logs by hostname
rangestringNoTime range: 1h, 6h, 24h (default 1h)
limitintNoMaximum log lines (default 50, max 200)

Example prompt: "Search for error logs on web-01 in the last hour"

LogsQL examples:

  • level:ERROR — all error logs
  • _msg:connection refused — logs containing "connection refused"
  • hostname:web-01 AND level:WARN — warnings on a specific host
  • _msg:OOM — out-of-memory events

See Logs (VictoriaLogs) for the full LogsQL query syntax.


Services​

query_services​

Search for services running across infrastructure hosts. Returns hostname, service name, version, status, and port.

ParameterTypeRequiredDescription
namestringNoFilter by service name (e.g. nginx, postgresql)
clientstringNoFilter by client name
environmentstringNoFilter by environment name
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Which hosts are running nginx?"


Version Currency​

get_version_posture​

End-of-life and currency rollup for the visible fleet or one client: counts per bucket, the worst products worst-first, and when the catalog last synced.

ParameterTypeRequiredDescription
clientstringNoFilter to one client by name
environmentstringNoFilter to one environment by name
statusstringNoOne bucket: eol, behind, current, unmatched
limitintNoHow many worst products to list (default 10, max 50)

Example prompt: "What software is end-of-life across the fleet?"


query_products​

List version-currency products with filters, paginated.

ParameterTypeRequiredDescription
namestringNoCase-insensitive substring of the product identifier (see below)
clientstringNoFilter to one client by name
environmentstringNoFilter to one environment by name
statusstringNoOne bucket: eol, behind, current, unmatched
include_untrackedboolNoInclude software the catalog does not grade (default false)
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip for pagination

Example prompt: "Which products are end-of-life in the production environment?"

name matches the product identifier, never a display name. Catalog-matched rows carry the endoflife.date slug (rhel, rocky-linux, postgresql); everything else carries a normalized inventory name (node-exporter). Identifiers are lowercase and hyphenated, so a query containing a space matches nothing — red hat returns an empty report, and rhel is the term that finds Red Hat Enterprise Linux.


get_host_versions​

One machine's software currency, by hostname.

ParameterTypeRequiredDescription
hostnamestringYesHostname of the machine to report on
include_untrackedboolNoInclude software the catalog does not grade (default false)

Example prompt: "Is anything on web-01 end-of-life?"

Rows sourced from Kubernetes are workloads whose pods run on this node, or on the cluster it belongs to — not software installed on its disk.


status takes only the four coarse buckets above, not a precise per-product status. The backend folds eol_soon and outdated into behind, current and update_available into current, and unknown and not_tracked alike into unmatched. A precise status such as outdated is rejected rather than forwarded, because forwarding it would match nothing and return an empty report — a false statement about the fleet produced by a typo.

include_untracked widens the denominator of the unknown share without being able to widen its numerator: the count is of products whose version could not be read (unknown), while untracked rows carry the distinct status not_tracked. Including them therefore dilutes the reported unknown ratio slightly. That is the semantically correct choice — unknown is missing data, not_tracked is software the catalog never claimed to grade — and the widening is named in the response header, but a reader comparing two calls should know why the ratio moved.

Currency is not a cause

All three tools report what is running and how current it is. A product being behind or end-of-life may be contributing context for an incident; it is never evidence that it caused one. Every response states how many products have an unreadable version, because CVE matching is version-range based — a product whose version is unknown contributes no CVE matches, so absence of findings there is missing data rather than a clean result. Alert context deliberately carries no currency data: the agent must ask for it.

Empty responses are worded as statements about what reached the console, never as findings that anything is current. For get_host_versions that reading is doubly load-bearing: the backend narrows its aggregate by host id rather than looking the host up, so a host outside the caller's scope returns the same empty report as a host whose software was never graded.

Catalog administration — unmatched triage, alias mapping, manual sync — is deliberately not exposed: it is super-admin work on a global resource, not fleet Q&A.


Webhooks​

list_webhook_sources​

List configured webhook sources (GitLab, GitHub, ArgoCD). Shows source name, type, enabled status, and client.

ParameterTypeRequiredDescription
clientstringNoFilter by client name
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Show me all configured webhook sources"


get_webhook_deliveries​

Get recent webhook deliveries for a source. Shows event type, response status, processing time, and errors. Useful for debugging webhook integration issues.

ParameterTypeRequiredDescription
source_namestringYesName of the webhook source
limitintNoMaximum results (default 20, max 100)

Example prompt: "Show me recent deliveries for the gitlab-prod webhook source"


Alerts​

get_active_alerts​

List active alert groups. Returns alert name, severity, status, count, and fired-at time.

ParameterTypeRequiredDescription
severitystringNoFilter by severity: critical, warning, info
statusstringNoFilter by status: firing, acknowledged, resolved, silenced (default firing)
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip for pagination

Example prompt: "Are there any firing alerts right now?"


get_alert_context​

Get full context for an alert group: alerts, audit log, and infrastructure correlation (metrics, changes, related alerts, compliance). Provide alert_id or hostname.

ParameterTypeRequiredDescription
alert_idstringNo*Alert group ID (UUID)
hostnamestringNo*Hostname — resolves to the most recent alert group for this host

*Provide at least one of alert_id or hostname.

Example prompt: "Show me the alert context for web-01 — what changed around the time of the alert?"


get_investigation​

Get L1's investigation of an incident: the root-cause claim and its trust level, every operator follow-up question and the answer given, the proposed remediation candidates and which have already run, and what the investigation cost. Provide incident_id or alert_id.

This is L1's reasoning. Use get_alert_context for the raw alert and its infrastructure correlation — the two are complementary.

ParameterTypeRequiredDescription
incident_idstringNo*Incident ID (UUID), as it appears in the incident page URL
alert_idstringNo*Alert group ID (UUID) — resolved to its incident

*Provide at least one of incident_id or alert_id.

An RCA is a claim, not a finding

Every response carries a boundary line, and it is not boilerplate. Measured verified-tier precision is roughly 43% strict, with recorded verified-but-wrong cases, so trust: verified is the strongest signal the product has and is still wrong a meaningful share of the time. Read trust before acting on cause, treat unsupported_claims as the list of what the verifier could not confirm, and never run a remediation on the strength of the cause alone. No candidate is pre-selected, deliberately.

A missing section is never rendered as an empty one: an alert with no incident says so and returns its conclusion alone, and a section that could not be read — a 403 on the session, say — is reported as unknown rather than absent.

Example prompt: "Pull the investigation for this incident and tell me whether the evidence actually supports the cause."

The Console UI has a Copy for Claude Code button on the incident page that copies the exact invocation, so an operator can hand an investigation to a coding agent without retyping a UUID. It deliberately copies the reference rather than the transcript: the receiving agent then reads the live record under its own API key and its own permissions.


acknowledge_alert​

Write operation

This tool modifies data (readOnlyHint: false). LLM clients should confirm with the user before calling it.

Acknowledge an alert group. Marks it as seen but does not resolve it (idempotent). Local to Proxima Console only.

ParameterTypeRequiredDescription
alert_idstringYesAlert group ID to acknowledge (UUID)

Example prompt: "Acknowledge the alert on db-01"


resolve_alert​

Write operation

Modifies data (readOnlyHint: false, idempotentHint: true, destructiveHint: false). Confirm with the user first.

Resolve (close) an alert group, marking the incident as handled. Idempotent.

ParameterTypeRequiredDescription
alert_idstringYesAlert group ID to resolve (UUID)

Example prompt: "Resolve the HighCPU alert on web-01"


silence_alert​

Write operation

Modifies data (readOnlyHint: false, destructiveHint: false). Confirm with the user first.

Silence an alert group for a duration (e.g. during planned maintenance). The server computes the absolute end time from the duration you provide.

ParameterTypeRequiredDescription
alert_idstringYesAlert group ID to silence (UUID)
durationstringYesHow long to silence, as a Go duration (e.g. 30m, 2h, 1h30m)

Example prompt: "Silence the disk alert on db-01 for 2 hours"


unsilence_alert​

Write operation

Modifies data (readOnlyHint: false, idempotentHint: true, destructiveHint: false). Confirm with the user first.

Remove an active silence from an alert group so it can notify again.

ParameterTypeRequiredDescription
alert_idstringYesAlert group ID to unsilence (UUID)

Example prompt: "Unsilence the db-01 disk alert"


add_alert_note​

Write operation

Modifies data (readOnlyHint: false, destructiveHint: false). Confirm with the user first.

Append a note to an alert group's audit log (e.g. triage findings). Visible to anyone viewing the alert.

ParameterTypeRequiredDescription
alert_idstringYesAlert group ID to annotate (UUID)
textstringYesThe note text to append

Example prompt: "Add a note to the web-01 alert: investigated, caused by a deploy at 14:05"


Runbooks​

list_runbooks​

List available runbooks (operational procedures). Returns name, slug, risk tier, step count, version, and description.

ParameterTypeRequiredDescription
filterstringNoSearch by runbook name or slug
riskstringNoFilter by risk tier: read_only, operational, destructive

Example prompt: "What runbooks are available for service restarts?"


preview_runbook​

Preview a runbook's execution plan for a specific host. Shows resolved steps with parameter substitution. Does not execute anything.

ParameterTypeRequiredDescription
runbookstringYesRunbook slug or name
hostnamestringYesTarget hostname
paramsobjectNoParameter values to substitute into the runbook steps

Example prompt: "Preview what the restart-nginx runbook would do on web-01"


run_runbook​

Write operation

This tool triggers real operations on the host (readOnlyHint: false). LLM clients should confirm with the user and call preview_runbook first.

Execute a runbook on a target host. Use preview_runbook first to verify the execution plan.

ParameterTypeRequiredDescription
runbookstringYesRunbook slug or name
hostnamestringYesTarget hostname
paramsobjectNoParameter values for the runbook

Example prompt: "Run the restart-nginx runbook on web-01"


get_runbook_status​

Get the status of a runbook execution including per-step results, output, and errors.

ParameterTypeRequiredDescription
execution_idstringYesExecution UUID

Example prompt: "What's the status of my last runbook execution?"


list_runbook_executions​

List recent runbook executions (most recent first) so you can discover execution IDs and their status. Returns runbook, host, status, trigger, start time, and execution ID.

ParameterTypeRequiredDescription
statusstringNoFilter by status: pending, running, completed, failed, timed_out, cancelled, skipped
hostnamestringNoFilter to executions on this host
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Show me runbook executions that are still running"


cancel_runbook​

Write operation

Modifies state (readOnlyHint: false, idempotentHint: true, destructiveHint: false). Confirm with the user first.

Cancel a pending or running runbook execution. Idempotent. Steps already started on the host may still complete.

ParameterTypeRequiredDescription
execution_idstringYesExecution UUID to cancel

Example prompt: "Cancel that runbook execution"


Re-evaluation Triggers​

trigger_healthcheck​

Write operation

Triggers work on the agent (readOnlyHint: false, destructiveHint: false). Additive and safe — it only schedules a fresh evaluation.

Trigger an immediate healthcheck evaluation on a host instead of waiting for the next scheduled run. Read fresh results afterwards with the compliance tools.

ParameterTypeRequiredDescription
hostnamestringYesTarget hostname

Example prompt: "Re-run the healthcheck on web-01 and tell me what's failing now"


trigger_compliance_eval​

Write operation

Triggers work on the backend (readOnlyHint: false, destructiveHint: false). Additive and safe — it only schedules a fresh evaluation.

Trigger an immediate compliance re-evaluation for a host against its mapped frameworks. Read fresh results afterwards with get_compliance_score / get_compliance_evaluations.

ParameterTypeRequiredDescription
hostnamestringYesTarget hostname

Example prompt: "Re-evaluate compliance for db-01"


Fleet​

get_fleet_status​

Get the agent fleet's version posture: the recommended/minimum agent versions and each visible agent's running version + skew status (up_to_date / update_available / outdated / ahead_of_backend).

ParameterTypeRequiredDescription
skewstringNoFilter to agents with this skew: up_to_date, update_available, outdated, ahead_of_backend, unknown

Example prompt: "Which agents are outdated and need an update?"


list_rollouts​

List recent agent-update rollouts (newest first) visible to the caller. Returns each rollout's id, target version, status (running / paused / completed / aborted), canary/batch sizing, when it was created, and by whom. Use get_rollout with an id to drill into per-agent progress.

ParameterTypeRequiredDescription
limitintNoMaximum rollouts to return, newest first (default 20, max 100)

Example prompt: "Show me the recent agent rollouts and their status."


get_rollout​

Get a rollout's live progress: its status, an aggregate per-status agent breakdown (the "is the rollout done?" answer), and the per-agent update rows (failures listed first). Use list_rollouts to find an id.

ParameterTypeRequiredDescription
rollout_idstringYesThe rollout UUID (from list_rollouts)

Example prompt: "Is rollout 1111… finished, and did any agents fail?"


Terminal Sessions​

list_sessions​

List terminal sessions (interactive shells / native SSH) across hosts the caller can see. Returns who connected (actor), the login, host, status (active/ended), recording status, and start time.

ParameterTypeRequiredDescription
active_onlybooleanNoOnly show sessions that are still open
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Are there any active terminal sessions right now?"


search​

Cross-entity search using Proxima Query Language (PQL). One flexible query across hosts, alerts, changes, assets, runbooks, or compliance — the entity is auto-detected from the fields (or forced with entity). Returns structured results (entity + total + the matching objects). Prefer the entity-specific tools when they fit; use this for ad-hoc or cross-cutting queries.

ParameterTypeRequiredDescription
querystringYesA PQL expression, e.g. os="Ubuntu 22.04" AND status=online
entitystringNoForce the entity: hosts, alerts, changes, assets, runbooks, compliance
limitintNoMaximum results (default 20, max 100)
offsetintNoNumber of results to skip

Example prompt: "Find all online hosts running an agent version below v0.6.13"


Service Desk​

Tickets are backed by Jira Service Management; reads need servicedesk:read, writes need servicedesk:write (enforced by the backend).

list_tickets​

List service-desk tickets (key, summary, status, priority, type, assignee, updated). Params: status, limit, offset.

get_ticket​

Get a ticket's detail and its available transitions (so you can hand a transition id to transition_ticket). Param: issue_key (required).

comment_ticket​

Write operation

Adds a comment (destructiveHint: false).

Params: issue_key (required), body (required), public (bool, default false → internal note).

transition_ticket​

Write operation

Moves a ticket to a new status (destructiveHint: false).

Params: issue_key (required), transition_id (required — from get_ticket), comment (optional). Call get_ticket first to find the transition id.

create_ticket​

Write operation

Opens a new ticket (destructiveHint: false).

Params: service_desk_id (required), request_type_id (required) — both from the JSM project config — plus summary (required), description, and optional extra_fields for any other required JSM fields.


Prompts​

Beyond tools, the server exposes MCP prompts — reusable operational workflows a user can invoke directly (e.g. as slash-commands in Claude clients). Each is argument-templated and steers the model through the right sequence of tools; prompts only instruct, they don't call tools themselves.

PromptArgument(s)What it does
triage_alertalert (UUID or hostname)Loads get_alert_context, assesses correlation, then recommends/takes acknowledge / resolve / silence + note, optionally a runbook.
diagnose_hosthostnameGathers host details, metrics, compliance failures/findings, recent changes, and alerts into a health summary with next steps.
compliance_reviewscope (host/env/client)Summarizes the compliance score + worst-failing controls and prioritizes remediation.
fleet_check(none)Reports agent version posture and which hosts need an update.

Resources​

The server also exposes read-only MCP resources — browseable reference data a client can list/read or attach as context, fetched live and RBAC-scoped to your API key (returned as JSON):

URIContents
proxima://catalog/frameworksThe compliance frameworks configured for your tenant.
proxima://catalog/runbooksThe runbook catalog (name, slug, risk tier, description).
proxima://inventory/hostsThe hosts visible to your account.

Error Responses​

When a tool encounters an error, it returns an MCP error content block (not a Go error). Error messages are designed to be actionable for the LLM:

ScenarioMessage
Invalid API key"Invalid or expired API key. Check your Proxima service account credentials."
Forbidden"You don't have access to this resource. Check your service account's client scope and role."
Not found"No {entity} found with identifier '{id}'. Use query_hosts to search for available hosts."
Rate limited"Rate limit reached. Wait a moment before making more requests."
Server error"Proxima API is currently unavailable. Try again in a moment."

Pagination​

Tools that support pagination (query_hosts, get_changes, query_services, get_compliance_evaluations, list_webhook_sources, get_active_alerts, list_runbook_executions, list_sessions, query_products) accept limit and offset parameters. Responses include a pagination footer like:

Showing 20 of 142 results. Use `limit` and `offset` parameters for more.