Model Context Protocol (MCP) Server

The CollectorCtrl MCP Server exposes your OpenTelemetry fleet to AI assistants (such as Claude Desktop, Cursor, and custom LLM agents) over the open-standard Model Context Protocol. AI agents can query live fleet health, analyze telemetry cardinality, inspect packages, and safely propose configuration changes using natural language.

1. Protocol Architecture & Endpoints

The MCP server is implemented natively in the Go backend (internal/collectorctrl/uisrv/mcp.go) and supports both Streamable HTTP and stdio transport modes:

AI Client (Claude Desktop / Cursor / Custom LLM)
      │
      │  MCP Protocol (JSON-RPC 2.0 over HTTPS POST or Stdio)
      ▼
CollectorCtrl Server (Port 4321)  ➔  https://<server>:4321/api/mcp
      │
      ├─ 1. Authentication: Bearer Token (SHA-256 hashed API token)
      ├─ 2. Authorization: Per-Tool RBAC Permission Check (requirePermission)
      ├─ 3. Rate Limiter: Per-Token Sliding Window (Read & Mutate budgets)
      ├─ 4. Guardrails: Blast-Radius Selector Cap & Two-Person Approval
      └─ 5. Audit Logging: Every call logged (actor: mcp:<username>)
            │
            ▼
CollectorCtrl Engine (Fleet State, Packages, Governor Analytics, OTel Sinks)

Protocol Specifications

2. API Token Setup & Role Scoping

Every MCP client authenticates with a CollectorCtrl API token. Tools automatically inherit the permissions granted to the token's role:

3. Comprehensive MCP Tools Reference

The tool surface is organized into three progressive security phases:

Phase 1: Read-Only Fleet Visibility (Active by Default)

Phase 1 tools are enabled out of the box and cannot alter system state:

Telemetry optimization tools

Read-only, also available to the in-app Copilot. They run the same generator as the Telemetry Insights optimizer, scoped to the token's environment. Examples and patterns pass through secret redaction; a pattern that contained a secret is returned with redacted: true.

Phase 2: Configuration Validation & Safe Proposals

Phase 2 introduces safe validation and mutating actions behind a mandatory Human-in-the-Loop approval workflow. Enable on the server with:

COLLECTORCTRL_MCP_PHASE2=true

Phase 3: Lifecycle Operations & Rollouts

Phase 3 introduces supervised process lifecycle operations, gated behind COLLECTORCTRL_MCP_PHASE3=true:

4. Connecting Client Applications

A. Claude Desktop (Stdio Adapter)

Use the lightweight collectorctrl-mcp bridge CLI to connect Claude Desktop to your server:

# Linux / macOS
$go build -o collectorctrl-mcp ./cmd/collectorctrl-mcp

# Windows (PowerShell)
$go build -o collectorctrl-mcp.exe ./cmd/collectorctrl-mcp

{
"mcpServers": {
  "collectorctrl": {
    "command": "/usr/local/bin/collectorctrl-mcp",
    "args": [
      "--server-url", "https://your-collectorctrl-server:4321",
      "--api-token", "cc_your_api_token_here"
    ]
  }
}
}

B. Cursor IDE Integration

Add CollectorCtrl as a project or global MCP server in Cursor:

1. Navigate to Cursor Settings → Features → MCP.
2. Click + Add New MCP Server.
3. Set Type: command.
4. Set Command: /path/to/collectorctrl-mcp --server-url https://your-server:4321 --api-token cc_your_token.

C. Direct JSON-RPC over HTTP

Any HTTP client can communicate directly with the /api/mcp endpoint:

$curl -sk -X POST https://your-server:4321/api/mcp -H "Authorization: Bearer cc_your_token" -H "Content-Type: application/json" -d '{
$  "jsonrpc": "2.0",
$  "id": 1,
$  "method": "tools/list"
$}'

$curl -sk -X POST https://your-server:4321/api/mcp -H "Authorization: Bearer cc_your_token" -H "Content-Type: application/json" -d '{
$  "jsonrpc": "2.0",
$  "id": 2,
$  "method": "tools/call",
$  "params": {
$    "name": "fleet_list_agents",
$    "arguments": {
$      "status": "unhealthy",
$      "environment": "production"
$    }
$  }
$}'

5. Enterprise Guardrails & Approval Workflow

CollectorCtrl enforces strict protocol-level safeguards to guarantee that autonomous AI agents cannot compromise production telemetry:

[ AI Agent ] ➔ fleet_push_config(selector, YAML)
                    │
                    ▼
[ Server ] ➔ 1. Validates YAML & OTTL syntax
           ➔ 2. Calculates blast radius (enforces SelectorCap <= 10)
           ➔ 3. Stages proposal with 15-minute TTL
           ➔ 4. Generates action_id: "act-8f902b1c"
                    │
                    ▼
[ Web Dashboard ] ➔ Settings ➔ Pending AI Actions
                    Operator inspects visual diff & blast radius
                    │
                    ├─ Option A: Human clicks "Approve" (requires mcp:approve)
                    └─ Option B: Human clicks "Reject" (proposal purged)

Safety Rules

1. Two-Person Security Rule: The human operator confirming an action must be distinct from the identity that created the proposal. A user cannot self-approve their own AI-generated changes.
2. Blast Radius Limits: The server rejects proposals targeting more than SelectorCap nodes (default: 10) in a single operation, preventing catastrophic fleet-wide misconfigurations.
3. Automatic Expiry: All pending action proposals expire automatically after 15 minutes if not approved.
4. Auto-Approve Guard: Unattended auto-approval is disabled for all roles including administrators. Enabling requires both COLLECTORCTRL_MCP_AUTO_APPROVE=true and explicit assignment of the mcp:auto-approve RBAC permission.

6. Example Prompts for AI Assistants

Here are practical prompts you can use with Claude Desktop or Cursor once connected:

• Incident Triaging: "Which collectors in the production cluster are currently degraded, and what are their error messages?"
• Recurring Pattern Review: "Which log patterns occur most often in the checkout service's sample over the last 24 hours, and which of them look like noise worth reviewing?"
• Compliance & Audit: "Show me the last 15 audit events. Were any configurations modified or collector binaries upgraded today?"
• Dry-Run What-If Simulation: "Simulate dropping logs where severity is INFO and body contains 'healthcheck'. What share of the sampled records would it remove?"
• Package Inspection: "List all available collector binary packages. Do we have an arm64 build for v0.108.0?"

7. Troubleshooting & Error Codes