AI agents (MCP)

The AI agents your team already uses can look things up in Ultraviolet while they work. In the middle of a change, ask “did checkout get slower after the 2pm deploy?” or “what errors is the cart service logging?”. The agent reads the answer from your own telemetry. It works with Claude Code, Cursor, GitHub Copilot in VS Code, and any agent that speaks the Model Context Protocol (MCP), including ones you host yourself.

Agents can only read. They can’t change alerts, monitors or anything else. The one exception is starting an investigation, which saves its report so your team can open it too.

Turning it on

It’s off by default. Whatever an agent looks up is sent to the model the agent uses, which may be a hosted model outside your network. Turning it on is a deliberate step for that reason. Set this in your Helm values and upgrade:

queryApi:
  mcp:
    enabled: true

To keep log lines out of what agents see, also set queryApi.ai.redactLogs: true. Agents then get log patterns and how often each occurs, never a line.

Connecting an agent

Each agent connects with an API token. A viewer token is enough. Give each agent or person its own token, so you can see who looked up what and revoke one without affecting the others.

An admin finds the ready-to-paste setup for each client under Access → AI agents (MCP). The address is your portal’s, followed by /api/v1/mcp. For example, with the token in the ULTRAVIOLET_TOKEN environment variable:

Claude Code

claude mcp add --transport http ultraviolet https://ultraviolet.example.com/api/v1/mcp \
  --header "Authorization: Bearer $ULTRAVIOLET_TOKEN"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "ultraviolet": {
      "url": "https://ultraviolet.example.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:ULTRAVIOLET_TOKEN}" }
    }
  }
}

VS Code (.vscode/mcp.json). VS Code asks for the token once and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "ultraviolet-token", "description": "Ultraviolet API token", "password": true }
  ],
  "servers": {
    "ultraviolet": {
      "type": "http",
      "url": "https://ultraviolet.example.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:ultraviolet-token}" }
    }
  }
}

Other clients: point any client that supports MCP’s Streamable HTTP transport at the address above, with the header Authorization: Bearer <token>.

The endpoint accepts API tokens only, not a portal sign-in.

What agents can look up

Tool	What it answers
active_alerts	Alerts firing and SLOs burning their error budget now, and any silence covering them.
investigate	Investigates a service, a firing alert or SLO, or a failing monitor: what degraded, what changed around it, likely causes first. Saved under Investigations.
get_investigation	A saved investigation’s findings, and its AI summary if there is one.
list_services	Every service, with its request rate, error rate and latency.
service_health	One service’s requests, errors and latency (p50, p95, p99).
service_endpoints	A service’s busiest endpoints, with error rate and latency.
service_dependencies	What a service calls and what calls it, including databases and caches, with requests, errors and latency, or connections and bytes where traffic isn’t parsed.
outbound_dependencies	The hosts and DNS names services call, such as third-party APIs, with external ones flagged.
error_log_patterns	A service’s error logs, grouped into patterns, with counts.
deploys	When a service last rolled out, with which images and what changed.
kubernetes_workloads	Replicas, restarts, CPU and memory, highlighting workloads in trouble.
list_metrics, metric	Any metric you collect, as a series of points.
search_traces	Requests by service, route, errors or duration, newest or slowest first.
get_trace	One trace, span by span, with the call tree.
search_logs	Log lines by service, severity, text or trace.
cpu_profile	Where a service spends CPU: its busiest functions and code paths.
synthetic_monitors	Your synthetic checks: status, uptime and latency per location, certificate expiry and recent failures.

Each tool looks at the last hour unless the agent asks for another window, up to 7 days, or a window in the past. Most tools also return the window of the same length before it, so the agent can see what changed without asking twice. Results are kept short, summarized rather than raw rows, so they fit comfortably in an agent’s context.

Keeping track

Every lookup is recorded in the audit trail as data leaving Ultraviolet: which token made it, which tool, with what arguments, and how much was returned. Revoke a token under Access → API tokens to cut an agent off within 30 seconds.

Troubleshooting

• The client offers to sign in through a browser. The token is missing, mistyped, expired or revoked. MCP clients take a refusal as a cue to start a browser sign-in, which Ultraviolet doesn’t use. Check the token under Access → API tokens, and check the variable it’s read from is set where the client runs.
• “The MCP server is turned off on this core”. Set queryApi.mcp.enabled (see above).
• “Takes an API token”. The request carried a portal sign-in rather than a token. Agents need a token.