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
- No Deck, abra Admin → Integrações (ou Conta, se você não for administrador) e procure Servidor MCP.
- 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.
- Copie o token (
orbit_...). O Deck mostra o valor uma única vez; o orbit-api guarda só o id.
| Escopo | O que o assistente pode fazer |
|---|---|
read | Toda ferramenta de leitura que o seu papel permite. As de escrita somem da lista e são recusadas. |
write | As 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
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:
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:
{
"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:
{
"mcpServers": {
"sreorbit": {
"command": "npx",
"args": ["mcp-remote", "https://orbit.example.com/api/v1/mcp", "--header", "X-Orbit-Token:orbit_..."]
}
}
}Ferramentas
| Ferramenta | Permissão | O que faz |
|---|---|---|
list_clusters | estate.read | Os clusters e seus ids. |
query_metrics | telemetry.query | PromQL instantâneo. |
query_metrics_range | telemetry.query | PromQL numa janela de até 7 dias, resumido por série: primeiro, último, mínimo, máximo, média, p50 e p95. |
list_metric_names | telemetry.query | Nomes de métricas que contêm um trecho. |
list_label_values | telemetry.query | Valores de um label, se quiser só nas séries que um seletor casa. |
search_logs | logs.read | Linhas de log para uma consulta na linguagem de busca de logs. |
search_traces | apm.read | Traces por serviço, operação, status, duração e atributos. |
get_trace | apm.read | Um trace com todos os spans. |
list_services | apm.read | Serviços com taxa, taxa de erro e p50, p95, p99, os mais movimentados ou os que mais falham primeiro, filtrados pelo nome. |
list_service_operations | apm.read | As operações de um serviço com os mesmos números. |
list_databases | databases.query | Bancos monitorados. |
top_sql | databases.query | Instruções ordenadas por tempo médio, tempo total ou chamadas, com o texto normalizado. |
explain_sql | databases.query | O plano de um digest, somente leitura. |
list_dashboards, get_dashboard | dashboards.read | Dashboards e o modelo JSON de cada um. |
create_dashboard, update_dashboard | dashboards.write | Cria ou substitui um dashboard; a resposta traz o link no Deck. |
delete_dashboard | dashboards.write | Apaga um dashboard e as versões dele; marcada como destrutiva, então o assistente pergunta antes. |
list_alerts | estate.read | Alertas de um cluster, inclusive os das regras PromQL: disparados, ou pendentes enquanto corre o for da regra. |
list_alert_rules | estate.read | As regras de alerta PromQL, cada uma com a última avaliação. |
create_alert_rule, update_alert_rule, delete_alert_rule | settings.manage | Cria, altera ou apaga uma regra de alerta PromQL. |
list_saved_views, create_saved_view | logs.read | Visõ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.