MCP Tools Reference
The MCP server exposes 41 tools. 29 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).
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 primary paginated list tools (query_hosts, get_active_alerts, get_changes, list_runbooks, list_rollouts) 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
client | string | No | Filter by client name |
environment | string | No | Filter by environment name |
os | string | No | Filter by operating system (e.g. Ubuntu 22.04) |
status | string | No | Filter by agent status: online or offline |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname of the server to inspect |
sections | string[] | No | Additional 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
host_a | string | Yes | Hostname of the first server |
host_b | string | Yes | Hostname of the second server |
full | boolean | No | Show 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname of the server |
metric | string | Yes | Metric name (e.g. cpu_usage_percent, memory_usage_percent, disk_usage_percent) |
range | string | No | Time 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | No* | Hostname to get compliance for |
environment | string | No* | Environment name to get compliance for |
client | string | No* | 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname of the server |
category | string | No | Filter by category (e.g. security, patch_and_vuln, networking) |
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname of the server |
severity | string | No | Filter by severity: critical, high, medium, low |
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
environment | string | No* | Environment name to get top failures for |
client | string | No* | Client name to get top failures for |
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname of the server |
status | string | No | Filter by status: pass, fail, warning, unknown, not_applicable, excepted |
framework_id | string | No | Filter by framework UUID |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | No | Filter by hostname |
environment | string | No | Filter by environment name |
client | string | No | Filter by client name |
event_type | string | No | Filter by type (e.g. package_installed, service_changed, file_modified) |
severity | string | No | Filter by severity: critical, high, medium, low, info |
range | string | No | Time range: 1h, 6h, 24h, 7d (default 24h) |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | LogsQL query expression (e.g. level:ERROR or _msg:timeout) |
hostname | string | No | Filter logs by hostname |
range | string | No | Time range: 1h, 6h, 24h (default 1h) |
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | Filter by service name (e.g. nginx, postgresql) |
client | string | No | Filter by client name |
environment | string | No | Filter by environment name |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number of results to skip |
Example prompt: "Which hosts are running nginx?"
Webhooks
list_webhook_sources
List configured webhook sources (GitLab, GitHub, ArgoCD). Shows source name, type, enabled status, and client.
| Parameter | Type | Required | Description |
|---|---|---|---|
client | string | No | Filter by client name |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
source_name | string | Yes | Name of the webhook source |
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
severity | string | No | Filter by severity: critical, warning, info |
status | string | No | Filter by status: firing, acknowledged, resolved, silenced (default firing) |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | No* | Alert group ID (UUID) |
hostname | string | No* | 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?"
acknowledge_alert
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert group ID to acknowledge (UUID) |
Example prompt: "Acknowledge the alert on db-01"
resolve_alert
Modifies data (readOnlyHint: false, idempotentHint: true, destructiveHint: false). Confirm with the user first.
Resolve (close) an alert group, marking the incident as handled. Idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert group ID to resolve (UUID) |
Example prompt: "Resolve the HighCPU alert on web-01"
silence_alert
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert group ID to silence (UUID) |
duration | string | Yes | How 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
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert group ID to unsilence (UUID) |
Example prompt: "Unsilence the db-01 disk alert"
add_alert_note
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert group ID to annotate (UUID) |
text | string | Yes | The 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | Search by runbook name or slug |
risk | string | No | Filter 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
runbook | string | Yes | Runbook slug or name |
hostname | string | Yes | Target hostname |
params | object | No | Parameter values to substitute into the runbook steps |
Example prompt: "Preview what the restart-nginx runbook would do on web-01"
run_runbook
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
runbook | string | Yes | Runbook slug or name |
hostname | string | Yes | Target hostname |
params | object | No | Parameter 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
execution_id | string | Yes | Execution 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: pending, running, completed, failed, timed_out, cancelled, skipped |
hostname | string | No | Filter to executions on this host |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number of results to skip |
Example prompt: "Show me runbook executions that are still running"
cancel_runbook
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
execution_id | string | Yes | Execution UUID to cancel |
Example prompt: "Cancel that runbook execution"
Re-evaluation Triggers
trigger_healthcheck
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Target hostname |
Example prompt: "Re-run the healthcheck on web-01 and tell me what's failing now"
trigger_compliance_eval
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Target 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
skew | string | No | Filter 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | int | No | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
rollout_id | string | Yes | The 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
active_only | boolean | No | Only show sessions that are still open |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number of results to skip |
Example prompt: "Are there any active terminal sessions right now?"
Search
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | A PQL expression, e.g. os="Ubuntu 22.04" AND status=online |
entity | string | No | Force the entity: hosts, alerts, changes, assets, runbooks, compliance |
limit | int | No | Maximum results (default 20, max 100) |
offset | int | No | Number 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
Adds a comment (destructiveHint: false).
Params: issue_key (required), body (required), public (bool, default false → internal note).
transition_ticket
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
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.
| Prompt | Argument(s) | What it does |
|---|---|---|
triage_alert | alert (UUID or hostname) | Loads get_alert_context, assesses correlation, then recommends/takes acknowledge / resolve / silence + note, optionally a runbook. |
diagnose_host | hostname | Gathers host details, metrics, compliance failures/findings, recent changes, and alerts into a health summary with next steps. |
compliance_review | scope (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):
| URI | Contents |
|---|---|
proxima://catalog/frameworks | The compliance frameworks configured for your tenant. |
proxima://catalog/runbooks | The runbook catalog (name, slug, risk tier, description). |
proxima://inventory/hosts | The 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:
| Scenario | Message |
|---|---|
| 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) accept limit and offset parameters. Responses include a pagination footer like:
Showing 20 of 142 results. Use `limit` and `offset` parameters for more.