MCP Server Overview

The Proxima MCP server is a standalone Go service that exposes infrastructure data to LLM clients via the Model Context Protocol. It acts as a stateless proxy between AI assistants (Claude Desktop, Cursor, Claude Code) and the Proxima Backend API, translating MCP tool calls into backend REST requests and formatting responses for LLM consumption.

Architecture

┌──────────────────────┐
│    LLM Client        │
│  (Claude / Cursor)   │
└──────────┬───────────┘
           │ MCP Protocol
           │ (Streamable HTTP or stdio)
           ▼
┌──────────────────────┐
│    Proxima MCP       │
│    Server            │
│                      │
│  ┌────────────────┐  │
│  │  Auth Cache    │  │
│  │  (TTL map)     │  │
│  └────────────────┘  │
│  ┌────────────────┐  │
│  │  41 Tools      │  │
│  │  (read + write)│  │
│  └────────────────┘  │
└──────────┬───────────┘
           │ REST API
           │ (X-API-Key forwarding)
           ▼
┌──────────────────────┐
│   Proxima Backend    │
│   API (port 8080)    │
└──────────────────────┘

Key Features

• 41 tools covering hosts, metrics, compliance, changes, logs, services, webhooks, alerts, runbooks, re-evaluation triggers, fleet, terminal sessions, cross-entity search, and service desk (29 read-only + 12 write operations)
• MCP prompts & resources: reusable operational workflows (triage_alert, diagnose_host, compliance_review, fleet_check) and browseable read-only resources (compliance frameworks, runbook catalog, host inventory)
• Structured output: data-returning tools emit machine-readable structuredContent (with an outputSchema) alongside the human markdown
• Two transports: Streamable HTTP (/mcp endpoint) for network clients, stdio for local CLI integration
• API key authentication: Proxima service account API keys forwarded to the backend, validated and cached with configurable TTL
• LLM-friendly output: Responses formatted as markdown tables, truncated to stay within token limits
• Full observability: OpenTelemetry tracing, Prometheus metrics at /metrics, structured JSON logging, MCP protocol-level progress notifications

How It Works

1. The LLM client connects to the MCP server (via HTTP or stdio)
2. The client sends an MCP tools/call request with a tool name and parameters
3. The MCP server authenticates the request using the API key from the Authorization header
4. The tool handler calls the Proxima Backend REST API, forwarding the API key via X-API-Key header
5. The response is formatted as LLM-friendly markdown (tables, summaries, trend analysis)
6. The formatted result is truncated to the configured token limit and returned to the client

Tools at a Glance

Tool	Category	Description
query_hosts	Hosts	Search and list infrastructure hosts with filters
get_host_details	Hosts	Detailed host info with optional sub-resources
compare_hosts	Hosts	Side-by-side host comparison
get_host_metrics	Metrics	Time-series data with statistics and trend detection
get_compliance_score	Compliance	Framework compliance scores for host/env/client
get_compliance_failures	Compliance	Failed compliance checks with remediation
get_findings	Compliance	Security scanner findings (CVEs)
list_frameworks	Compliance	List available compliance frameworks
get_top_failures	Compliance	Top failing controls by environment or client
get_compliance_evaluations	Compliance	Detailed per-control evaluations for a host
get_changes	Changes	Infrastructure change events
search_logs	Logs	LogsQL log search
query_services	Services	Services running across hosts
list_webhook_sources	Webhooks	List configured webhook sources
get_webhook_deliveries	Webhooks	Recent deliveries for a webhook source
list_host_metrics	Metrics	List available metric names for a host
get_active_alerts	Alerts	List active alert groups
get_alert_context	Alerts	Alert details with host/change correlation
acknowledge_alert	Alerts	Acknowledge an alert (write)
resolve_alert	Alerts	Resolve an alert (write)
silence_alert	Alerts	Silence an alert for a duration (write)
unsilence_alert	Alerts	Remove a silence from an alert (write)
add_alert_note	Alerts	Add a note to an alert (write)
list_runbooks	Runbooks	List available runbooks
preview_runbook	Runbooks	Preview execution plan before running
run_runbook	Runbooks	Execute a runbook on a host (write)
get_runbook_status	Runbooks	Check runbook execution status
list_runbook_executions	Runbooks	List recent runbook executions
cancel_runbook	Runbooks	Cancel a running runbook execution (write)
trigger_healthcheck	Triggers	Trigger an immediate healthcheck on a host (write)
trigger_compliance_eval	Triggers	Trigger an immediate compliance re-evaluation (write)
get_fleet_status	Fleet	Agent version posture and per-agent skew status
list_rollouts	Fleet	List recent agent-update rollouts
get_rollout	Fleet	Live progress of a specific rollout
list_sessions	Terminal Sessions	List terminal sessions across hosts
search	Search	Cross-entity PQL search (hosts, alerts, changes, …)
list_tickets	Service Desk	List service-desk tickets
get_ticket	Service Desk	Ticket detail with available transitions
comment_ticket	Service Desk	Add a comment to a ticket (write)
transition_ticket	Service Desk	Move a ticket to a new status (write)
create_ticket	Service Desk	Open a new ticket (write)

The server also exposes MCP prompts (triage_alert, diagnose_host, compliance_review, fleet_check) and read-only resources (proxima://catalog/frameworks, proxima://catalog/runbooks, proxima://inventory/hosts).

See Tools Reference for full parameter documentation, prompts, resources, and examples.

Endpoints

Path	Method	Description
/mcp	POST	MCP Streamable HTTP transport endpoint
/healthz	GET	Health check — returns {"status":"ok"}
/metrics	GET	Prometheus metrics in exposition format

Technology

• Language: Go 1.26+
• MCP SDK: github.com/modelcontextprotocol/go-sdk v1.4.1
• Logging: log/slog — structured JSON to stdout
• Tracing: OpenTelemetry with OTLP gRPC exporter
• Metrics: Prometheus via OTel exporter at /metrics

Next Steps

• Setup Guide — configure Claude Desktop, Cursor, or Claude Code
• Tools Reference — all 41 tools with parameters and examples
• Configuration — environment variables and deployment options
• Observability — metrics, traces, and troubleshooting