MCP Server — AI Agent Access

The CollectorCtrl MCP Server allows AI assistants (such as Claude Desktop, Cursor, and custom LLM agents) to query your OpenTelemetry fleet using natural language over the Model Context Protocol (MCP standard).

Read-Only Security Model

Phase 1 MCP tools are strictly read-only by default. AI agents cannot modify fleet configuration, reboot daemons, or execute commands without an explicit human-in-the-loop approval workflow.

1. Protocol Architecture & Endpoint Specs

Endpoint: POST https://your-server:4321/api/mcp
Protocol: MCP (JSON-RPC 2.0 over HTTP POST)
Authentication: Authorization: Bearer <cc_token> (CollectorCtrl API token)
Audit Stream: Every MCP query is logged as actor mcp:<username> with parameters and execution duration.

2. API Token Generation

1. Open API Token Settings

Navigate to Settings → SSO & Tokens → API Tokens in the web dashboard.

2. Generate New Token

Click Generate Token, specify a name (e.g. claude-desktop), and assign an RBAC role.

3. Configure LLM Client

Copy the token string (cc_...) and configure your LLM client.

3. Available Tools Reference (Phase 1)

Tool Name	Scope & Description	Required Permission
`fleet_list_agents`	Filter connected agents by status, environment, and host OS	`fleet:view`
`fleet_get_agent`	Retrieve deep telemetry metadata for a specific agent ID	`fleet:view`
`fleet_get_samples`	Fetch live captured telemetry samples	`fleet:view`
`fleet_list_packages`	Query release binaries in the package repository	`packages:view`
`governor_volume`	Query real-time telemetry volume and ingestion rates	`governor:view`
`governor_cardinality`	Analyze distinct log severity levels, metric keys, and trace spans	`governor:view`
`audit_query`	Search system audit logs and action trails	`audit:view`
`discovery_reports`	View discovered services and ports per agent node	`discovery:analyze`

4. Connecting Claude Desktop & Cursor

claude_desktop_config.json

{
"mcpServers": {
  "collectorctrl": {
    "command": "/path/to/collectorctrl-mcp",
    "args": [
      "--server-url", "https://your-server:4321",
      "--api-token", "cc_your_token_here"
    ]
  }
}
}

5. Phase 2 — Human-in-the-Loop Approval Workflow

Phase 2 enables AI-proposed fleet modifications (e.g., config changes, OTTL filter generation) behind a mandatory human approval gate. Enable Phase 2 on the server with:

COLLECTORCTRL_MCP_PHASE2=true

Two-Person Security Rule

AI Proposes Action: The AI generates a change proposal and returns a pending action_id (expires in 15 minutes).
Human Reviews: An operator inspects the proposed diff under Settings → Pending AI Actions.
Approval / Rejection: The human approves or rejects the change. The proposer and approver identities must be distinct.