MCP Tools for AI Chat
The Proxima MCP server exposes 6 runbook-related tools that allow LLM clients (Claude Desktop, Cursor, Claude Code) to discover, preview, execute, monitor, and cancel runbooks.
Tools Overview
| Tool | Read-Only | Description |
|---|---|---|
list_runbooks | Yes | Discover available runbooks |
preview_runbook | Yes | Dry-run preview with parameter substitution |
run_runbook | No | Trigger execution on a target host |
get_runbook_status | Yes | Check execution progress and step results |
list_runbook_executions | Yes | List recent executions to discover execution IDs |
cancel_runbook | No | Cancel a pending or running execution (idempotent) |
list_runbooks
Discover available runbooks. Returns a table with 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 restarting services?"
preview_runbook
Generate a dry-run preview of a runbook's execution plan for a specific host. Shows resolved steps with parameter substitution applied. 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 steps |
Example prompt: "Preview the restart-nginx runbook on web-01.prod"
The preview shows:
- Runbook name, slug, and risk tier
- Timeout setting
- Each step with its action, resolved parameters, conditions, and failure policy
run_runbook
Execute a runbook on a target host. This triggers real operations. Always preview first.
| Parameter | Type | Required | Description |
|---|---|---|---|
runbook | string | Yes | Runbook slug or name |
hostname | string | Yes | Target hostname |
params | object | No | Parameter values for the runbook |
The response includes the execution ID, which you can use with get_runbook_status to track progress.
All executions triggered via MCP tools are recorded with trigger_source: ai_chat.
Example prompt: "Run the restart-nginx runbook on web-01.prod"
get_runbook_status
Check the status of a runbook execution, including per-step results, output, and errors.
| Parameter | Type | Required | Description |
|---|---|---|---|
execution_id | string | Yes | Execution UUID (from run_runbook response) |
The response includes:
- Overall execution status
- Runbook name and target host
- Trigger source and timestamps
- Duration (if completed)
- Per-step results with status, output, and errors
Example prompt: "Check the status of execution abc123-..."
list_runbook_executions
List recent runbook executions (most recent first) so you can discover execution IDs and their status. Returns a table with runbook name, host, status, trigger source, start time, and execution ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: pending, running, completed, failed, timed_out, cancelled, or 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 for pagination |
Example prompt: "Show me the most recent runbook executions that failed."
cancel_runbook
Cancel a pending or running runbook execution by its execution ID. This is idempotent -- canceling an already-finished or already-canceled execution is a no-op. Steps already started on the host may still complete.
| Parameter | Type | Required | Description |
|---|---|---|---|
execution_id | string | Yes | Execution UUID to cancel |
Example prompt: "Cancel the restart-nginx execution abc123-..."
Example Conversation Flow
Here is a typical investigation and remediation flow using the MCP tools:
User: "Nginx is returning 502 errors on web-01.prod. Can you investigate?"
LLM: Uses list_runbooks to find relevant runbooks.
Found "investigate-service" (read_only) and "restart-nginx" (operational).
LLM: Uses preview_runbook to check the investigation plan.
Preview shows: read nginx error log, read syslog, run healthcheck.
User: "Go ahead and run the investigation."
LLM: Uses run_runbook with the investigate-service runbook.
Execution started. ID: a1b2c3...
LLM: Uses get_runbook_status to check progress.
Step 1 (read_file_tail) completed: Found "upstream timed out" errors. Step 2 (read_file_tail) completed: Syslog shows high memory usage. Step 3 (run_healthcheck) completed.
LLM: "The nginx upstream is timing out. I can restart nginx using the restart-nginx runbook. This is an operational action and needs your confirmation."
User: "Yes, restart it."
LLM: Uses preview_runbook for restart-nginx, then run_runbook.
Execution started. ID: d4e5f6...
LLM: Uses get_runbook_status to confirm.
Step 1 (restart_systemd_unit) completed. Status: active.
LLM: "Nginx has been restarted and is active. The 502 errors should resolve."
Authentication
MCP tools authenticate using the same API key mechanism as all other MCP tools. The service account's role and client scope determine which runbooks are visible and executable. See MCP Setup for configuration.
Risk Enforcement
MCP tools respect the same risk tier rules as the frontend:
- read_only runbooks execute without additional confirmation.
- operational runbooks require the calling user to have
runbooks:executepermission. - destructive runbooks require super admin.
The LLM should always preview before executing and explain the risk tier to the user.