Skip to content

Features

MCP server

SRE Orbit serves the Model Context Protocol at /api/v1/mcp on the Deck's own address. Claude Code, Claude Desktop, Cursor and any other MCP client can then query metrics, logs, traces and database statements, and create dashboards and alert rules, with your role's permissions. Each tool call goes through the same permission checks, feature switches and audit trail as a click in the Deck.

Create a token

  1. In the Deck, open Admin → Integrations (or Account if you are not an admin) and find MCP server.
  2. Name the token, pick a scope and an expiry (7, 30 or 90 days), type your password and a code from your authenticator app, and click Create token. An account that signs in through SSO signs in again at its provider first instead. For 5 minutes after either proof, the same session creates tokens without asking again.
  3. Copy the token (orbit_...). The Deck shows it once; orbit-api keeps only its id.
ScopeWhat the assistant can do
readEvery read tool your role allows. Write tools are hidden and refused.
writeReads, plus the write tools your role allows: dashboards need dashboards.write, alert rules settings.manage.

A token acts as you: disable the user and the token stops working; change the role and the token follows it. Revoke a token from the same table; the Deck asks before it revokes. On Admin → Integrations, a user with users.manage sees every user's tokens with their owner and can revoke any of them (GET /api/v1/auth/tokens?all=1; the audit event names the owner). A user holds at most 20 tokens. Demo accounts cannot create tokens.

A token lives 90 days at most (POST /api/v1/auth/tokens takes days from 1 to 90, and current and code as the proof; without them it answers 400). A token an earlier release made to never expire ends 90 days after the first start of this one. Changing your password, an admin resetting it, or your second factor turned off deletes every token of the account, so a token minted from a stolen session stops when you change the password.

Add it to Claude Code

bash
claude mcp add --transport http sreorbit https://orbit.example.com/api/v1/mcp \  --header "X-Orbit-Token: orbit_..."

Replace https://orbit.example.com with the address you open the Deck at; the MCP panel in the Deck prints the command with your address and token filled in. Authorization: Bearer orbit_... works too when web's basic auth is off. Behind basic auth (WEB_AUTH_MODE=basic), send both:

bash
claude mcp add --transport http sreorbit https://orbit.example.com/api/v1/mcp \  --header "Authorization: Basic $(printf '%s' 'user:password' | base64)" \  --header "X-Orbit-Token: orbit_..."

Check it with claude mcp list, then ask, for example: "build a dashboard with request rate, error rate, p95 latency and pod CPU for checkout".

Cursor, Claude Desktop and other clients

Cursor and most clients read an mcp.json:

json
{
  "mcpServers": {
    "sreorbit": {
      "url": "https://orbit.example.com/api/v1/mcp",
      "headers": { "X-Orbit-Token": "orbit_..." }
    }
  }
}

Claude Desktop runs local servers only, so bridge it with mcp-remote:

json
{
  "mcpServers": {
    "sreorbit": {
      "command": "npx",
      "args": ["mcp-remote", "https://orbit.example.com/api/v1/mcp", "--header", "X-Orbit-Token:orbit_..."]
    }
  }
}

Tools

ToolPermissionWhat it does
list_clustersestate.readThe clusters and their ids.
query_metricstelemetry.queryInstant PromQL.
query_metrics_rangetelemetry.queryPromQL over a window of up to 7 days, summarised per series: first, last, min, max, average, p50 and p95.
list_metric_namestelemetry.queryMetric names matching a substring.
list_label_valuestelemetry.queryValues of one label, optionally on the series a selector matches.
search_logslogs.readLog lines for a query in the log query language.
search_tracesapm.readTraces by service, operation, status, duration and attributes.
get_traceapm.readOne trace with every span.
list_servicesapm.readServices with rate, error rate and p50, p95, p99, the busiest or the most failing first, filtered by name.
list_service_operationsapm.readOne service's operations with the same figures.
list_databasesdatabases.queryMonitored databases.
top_sqldatabases.queryStatements ranked by average time, total time or calls, with their normalized text.
explain_sqldatabases.queryThe plan of one statement digest, read-only.
list_dashboards, get_dashboarddashboards.readDashboards and their JSON model.
create_dashboard, update_dashboarddashboards.writeCreate or replace a dashboard; the answer carries its Deck link.
delete_dashboarddashboards.writeDelete a dashboard and its versions; marked destructive, so the assistant asks first.
list_alertsestate.readAlerts on a cluster, the PromQL rules' included: firing, or pending while a rule's for runs.
list_alert_rulesestate.readThe PromQL alert rules, each with its last evaluation.
create_alert_rule, update_alert_rule, delete_alert_rulesettings.manageCreate, change or delete a PromQL alert rule.
list_saved_views, create_saved_viewlogs.readSaved views of the Logs and Traces explorers (saved views); creating one needs a write token.

Times take now, now-15m, -1h, 2d, Unix seconds or milliseconds; the default window is the last hour. An answer longer than 48 KiB is cut, and the assistant reads that it should narrow the query. The server also offers three resources: the query syntax, the dashboard JSON model and the alert rule fields.

Alert rules

A PromQL alert rule is {name, cluster, query, op, threshold, for, severity, summary, runbook, enabled}, with op one of >, >=, <, <=, ==, !=, for a duration up to 24h (5m, 1h; empty fires at once) and severity critical, warning or info.

The alerting loop evaluates every enabled rule on the engine each ORBIT_ALERTING_INTERVAL (30 s by default), 8 at a time, each with a 3 s limit. Each series where (query) op threshold holds is one alert named after the rule. It starts as pending, turns firing once the condition has held for for, and resolves on the first evaluation that answers without it. A rule alerts on 50 series at most. Past 50, status.matched counts every series that holds and the Deck shows "50 of 329": the series already alerting stay, and the largest new ones fill the free places, so the set changes only when a series stops holding. orbit-api reads the 1,000 largest series of each rule; an alerting series that falls below them reads as resolved. Past 1,000, a second query counts them; when it fails, matched keeps its last value and the alerts still follow the first answer. orbit-api keeps this state in the data directory, so since is when the alert fired and survives a restart. Firing alerts go to the notification channels like the built-in ones; pending ones show on Alerts and page nobody. Reading alerts evaluates nothing: the Deck and list_alerts read the state the loop left.

When an evaluation fails or times out, the rule's alerts stay as they were, so a slow engine neither resolves an alert nor pages it again; the rule's status.error says why. A series whose cluster label names another cluster of this console belongs to that cluster and does not fire here. An aggregate that drops the label sees every cluster, so keep cluster="<id>" in the selector when one engine serves several clusters.

The Deck lists the rules under the table on Alerts. Rules need the engine (ORBIT_STACK_URL); a save checks the query on it. The routes: GET /api/v1/alerting/rules (estate.read; each rule carries status: {evaluatedAt, error, pending, firing, matched}), PUT and DELETE /api/v1/alerting/rules/{id} (settings.manage, audited as alert-rule.create, alert-rule.update and alert-rule.delete).

Audit

Every tool call writes mcp.call to the audit trail: the tool, the status, its arguments (cut at 1,000 characters) and the outcome (success, denied or failure). The actor is the token's user, with session token:<id>:<scope>. A write also leaves the event its route writes, such as dashboard.create. Creating and revoking a token writes token.create and token.delete. No tool answers a token, a password or a database credential.

The protocol

Streamable HTTP, protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, JSON answers only: POST carries one JSON-RPC message and gets one JSON answer (a notification gets 202); GET answers 405, since the server keeps no session and pushes no stream. The token header counts on /api/v1/mcp and nowhere else: a token never opens a Deck page or another API route. A cross-site browser request is refused before orbit-api.