Pular para o conteúdo

Recursos

Servidor MCP

O SRE Orbit serve o Model Context Protocol em /api/v1/mcp, no mesmo endereço do Deck. Com isso o Claude Code, o Claude Desktop, o Cursor e qualquer outro cliente MCP consultam métricas, logs, traces e instruções dos bancos, e criam dashboards e regras de alerta, com as permissões do seu papel. Cada chamada de ferramenta passa pelas mesmas checagens de permissão, chaves de recurso e trilha de auditoria de um clique no Deck.

Crie um token

  1. No Deck, abra Admin → Integrações (ou Conta, se você não for administrador) e procure Servidor MCP.
  2. Dê um nome ao token, escolha o escopo e a validade (7, 30 ou 90 dias), digite a sua senha e um código do app autenticador e clique em Criar token. Uma conta que entra pelo SSO faz um novo login no provedor antes, no lugar disso. Por 5 minutos depois de qualquer uma das duas provas, a mesma sessão cria tokens sem pedir de novo.
  3. Copie o token (orbit_...). O Deck mostra o valor uma única vez; o orbit-api guarda só o id.
EscopoO que o assistente pode fazer
readToda ferramenta de leitura que o seu papel permite. As de escrita somem da lista e são recusadas.
writeAs leituras e as ferramentas de escrita que o seu papel permite: dashboards pedem dashboards.write, regras de alerta pedem settings.manage.

O token age como você: desative o usuário e o token para de funcionar; troque o papel e o token acompanha. Revogue um token na mesma tabela; o Deck pergunta antes de revogar. Em Admin → Integrações, quem tem users.manage vê os tokens de todos os usuários, com o dono de cada um, e revoga qualquer um deles (GET /api/v1/auth/tokens?all=1; o evento de auditoria registra o dono). Cada usuário tem no máximo 20 tokens. Contas de demonstração não criam tokens.

Um token vale no máximo 90 dias (POST /api/v1/auth/tokens aceita days de 1 a 90, e current e code como prova; sem eles, responde 400). Um token que uma versão anterior criou sem validade termina 90 dias depois do primeiro início desta. Trocar a sua senha, um administrador redefini-la ou o seu segundo fator desligado apaga todos os tokens da conta, então um token criado a partir de uma sessão roubada para quando você troca a senha.

Adicione ao Claude Code

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

Troque https://orbit.example.com pelo endereço em que você abre o Deck; o painel MCP do Deck imprime o comando já com o seu endereço e o seu token. Authorization: Bearer orbit_... também serve quando a autenticação básica do web está desligada. Atrás dela (WEB_AUTH_MODE=basic), envie os dois cabeçalhos:

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_..."

Confira com claude mcp list e peça, por exemplo: "monte um dashboard com taxa de requisições, taxa de erro, latência p95 e CPU dos pods do checkout".

Cursor, Claude Desktop e outros clientes

O Cursor e a maioria dos clientes leem um mcp.json:

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

O Claude Desktop só roda servidores locais; ligue-o pelo mcp-remote:

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

Ferramentas

FerramentaPermissãoO que faz
list_clustersestate.readOs clusters e seus ids.
query_metricstelemetry.queryPromQL instantâneo.
query_metrics_rangetelemetry.queryPromQL numa janela de até 7 dias, resumido por série: primeiro, último, mínimo, máximo, média, p50 e p95.
list_metric_namestelemetry.queryNomes de métricas que contêm um trecho.
list_label_valuestelemetry.queryValores de um label, se quiser só nas séries que um seletor casa.
search_logslogs.readLinhas de log para uma consulta na linguagem de busca de logs.
search_tracesapm.readTraces por serviço, operação, status, duração e atributos.
get_traceapm.readUm trace com todos os spans.
list_servicesapm.readServiços com taxa, taxa de erro e p50, p95, p99, os mais movimentados ou os que mais falham primeiro, filtrados pelo nome.
list_service_operationsapm.readAs operações de um serviço com os mesmos números.
list_databasesdatabases.queryBancos monitorados.
top_sqldatabases.queryInstruções ordenadas por tempo médio, tempo total ou chamadas, com o texto normalizado.
explain_sqldatabases.queryO plano de um digest, somente leitura.
list_dashboards, get_dashboarddashboards.readDashboards e o modelo JSON de cada um.
create_dashboard, update_dashboarddashboards.writeCria ou substitui um dashboard; a resposta traz o link no Deck.
delete_dashboarddashboards.writeApaga um dashboard e as versões dele; marcada como destrutiva, então o assistente pergunta antes.
list_alertsestate.readAlertas de um cluster, inclusive os das regras PromQL: disparados, ou pendentes enquanto corre o for da regra.
list_alert_rulesestate.readAs regras de alerta PromQL, cada uma com a última avaliação.
create_alert_rule, update_alert_rule, delete_alert_rulesettings.manageCria, altera ou apaga uma regra de alerta PromQL.
list_saved_views, create_saved_viewlogs.readVisões salvas dos exploradores de Logs e Traces (visões salvas); criar uma pede um token write.

Os horários aceitam now, now-15m, -1h, 2d, segundos ou milissegundos Unix; a janela padrão é a última hora. Uma resposta acima de 48 KiB é cortada, e o assistente lê que precisa estreitar a consulta. O servidor também oferece três recursos: a sintaxe das consultas, o modelo JSON de dashboard e os campos de uma regra de alerta.

Regras de alerta

Uma regra de alerta PromQL tem os campos {name, cluster, query, op, threshold, for, severity, summary, runbook, enabled}, com op entre >, >=, <, <=, ==, !=, for uma duração de até 24h (5m, 1h; vazio dispara na hora) e severity igual a critical, warning ou info.

O loop de alertas avalia cada regra ligada no motor a cada ORBIT_ALERTING_INTERVAL (30 s por padrão), 8 por vez, cada uma com limite de 3 s. Cada série em que (query) op threshold vale vira um alerta com o nome da regra. Ele começa pending, passa a firing quando a condição já durou o for e se resolve na primeira avaliação que responde sem ela. Uma regra alerta em no máximo 50 séries. Acima de 50, o status.matched conta todas as séries em que a condição vale e o Deck mostra "50 de 329": as séries que já alertam ficam, e as maiores entre as novas ocupam as vagas livres, então o conjunto só muda quando uma série deixa de valer. O orbit-api lê as 1.000 maiores séries de cada regra; uma série alertando que cai abaixo delas conta como resolvida. Acima de 1.000, uma segunda consulta as conta; se ela falha, o matched mantém o último valor e os alertas seguem a primeira resposta. O orbit-api guarda esse estado no diretório de dados, então since é a hora em que o alerta disparou e sobrevive a um reinício. Os alertas disparados vão para os canais de notificação como os embutidos; os pendentes aparecem em Alertas e não avisam ninguém. Ler alertas não avalia nada: o Deck e o list_alerts leem o estado que o loop deixou.

Quando uma avaliação falha ou estoura o tempo, os alertas da regra ficam como estavam: um motor lento não resolve o alerta nem avisa de novo, e o status.error da regra diz o motivo. Uma série cujo label cluster nomeia outro cluster deste console pertence a esse cluster e não dispara aqui. Uma agregação que descarta o label enxerga todos os clusters; mantenha cluster="<id>" no seletor quando um mesmo motor atende vários clusters.

O Deck lista as regras abaixo da tabela em Alertas. As regras precisam do motor (ORBIT_STACK_URL); ao salvar, o orbit-api testa a consulta nele. As rotas: GET /api/v1/alerting/rules (estate.read; cada regra traz status: {evaluatedAt, error, pending, firing, matched}), PUT e DELETE /api/v1/alerting/rules/{id} (settings.manage, auditadas como alert-rule.create, alert-rule.update e alert-rule.delete).

Auditoria

Cada chamada de ferramenta grava mcp.call na trilha de auditoria: a ferramenta, o status, os argumentos (cortados em 1.000 caracteres) e o resultado (success, denied ou failure). O ator é o dono do token, com a sessão token:<id>:<scope>. Uma escrita também deixa o evento da própria rota, como dashboard.create. Criar e revogar um token grava token.create e token.delete. Nenhuma ferramenta devolve token, senha ou credencial de banco.

O protocolo

Streamable HTTP, versões 2025-06-18, 2025-03-26 e 2024-11-05, só respostas JSON: cada POST leva uma mensagem JSON-RPC e recebe uma resposta JSON (uma notificação recebe 202); GET recebe 405, porque o servidor não guarda sessão nem empurra fluxo. O cabeçalho do token vale em /api/v1/mcp e em nenhum outro lugar: um token nunca abre uma página do Deck nem outra rota da API. O web recusa uma requisição de navegador vinda de outro site antes do orbit-api.