Runframe

runframe-mcp-server

Runframe é a plataforma completa de ciclo de vida de incidentes para equipes de engenharia, cobrindo resposta a incidentes, plantão (on-call) e páginas de status. Este servidor MCP permite que você gerencie esses fluxos de trabalho diretamente do seu IDE ou agente de IA.

17 ferramentas cobrindo incidentes, plantão, serviços, postmortems, equipes e busca de pessoas. Requer Node.js 20+.

Por que Usar

• Fique no seu editor — reconheça incidentes, acione respondentes e escreva postmortems sem alternar para o navegador
• Deixe agentes cuidarem da rotina — agentes de IA podem triar, escalar e atualizar incidentes de forma autônoma usando chaves de API com escopo definido
• Zero infraestrutura — executa via npx, sem necessidade de servidor para uso local

Como Funciona

Your IDE / Agent
    ↓ (stdio or HTTP)
MCP Server (this package)
    ↓ (HTTPS, scoped API key)
Runframe API

O servidor não mantém estado. Ele traduz chamadas de ferramentas MCP em requisições à API do Runframe, limitadas pelas permissões da sua chave de API. Nenhum dado é armazenado localmente.

Exemplos

Pergunte ao seu agente:

• "Reconheça o incidente INC-2026-001" → chama runframe_acknowledge_incident
• "Quem está de plantão agora?" → chama runframe_get_current_oncall
• "Crie um postmortem para a indisponibilidade do banco de dados" → chama runframe_create_postmortem
• "Acione o líder do time de backend sobre o pico de latência da API" → chama runframe_page_someone
• "Liste todos os incidentes SEV1 abertos" → chama runframe_list_incidents com filtro de severidade
• "Encontre o Alex para eu verificar os incidentes abertos dele" → chama runframe_find_user

Instalação

Obtenha sua chave de API nas configurações do Runframe.io e adicione ao seu agente:

Claude Code:

claude mcp add runframe -e RUNFRAME_API_KEY=rf_your_key_here -- npx -y @runframe/mcp-server

Cursor (~/.cursor/mcp.json) · VS Code (.vscode/mcp.json) · Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "runframe": {
      "command": "npx",
      "args": ["-y", "@runframe/mcp-server"],
      "env": { "RUNFRAME_API_KEY": "rf_your_key_here" }
    }
  }
}

Outros clientes MCP: Adicione a configuração JSON acima ao arquivo de configuração MCP do seu cliente.

Assistente de configuração interativo:

npx @runframe/mcp-server --setup

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
RUNFRAME_API_KEY	Sim	—	Chave de API (começa com rf_)
RUNFRAME_API_URL	Não	https://runframe.io	URL base da API
MCP_ACCESS_TOKEN	Somente HTTP	—	Token Bearer para transporte HTTP. Separado por vírgulas para rotação (new_token,old_token).

Transportes

stdio (padrão) — usado por clientes MCP como Claude Code e Cursor. Sem exposição de rede. É o que os comandos de instalação acima configuram.

HTTP Streamable — para implantações conteinerizadas ou remotas. Requer MCP_ACCESS_TOKEN para autenticação bearer:

RUNFRAME_API_KEY=rf_... \
  MCP_ACCESS_TOKEN=your_token \
  npx @runframe/mcp-server --transport http --port 3100 --host 127.0.0.1

Modelo de Segurança

A responsabilidade é dividida em três camadas:

• API do Runframe lida com autorização e escopos via RUNFRAME_API_KEY.
• Este servidor MCP lida com isolamento de processo (stdio) e validação de token bearer (HTTP). Também aplica filtragem de métodos, verificações de Host/Origin em localhost, validação de Content-Length declarado (limite de 1 MB), limite de cabeçalho de 8 KB e timeout de upstream de 15s.
• Seu proxy reverso lida com TLS, limitação de taxa e aplicação de corpo transmitido em fluxo (streamed-body) se você expor o modo HTTP a uma rede.

O servidor não armazena nada. É um pass-through para a API do Runframe.

Ferramentas

Incidentes (9)

Ferramenta	Escopos	Descrição
runframe_list_incidents	incidents:read	Lista incidentes com filtros e paginação
runframe_get_incident	incidents:read	Obtém incidente por ID ou número
runframe_create_incident	incidents:write	Cria um incidente
runframe_update_incident	incidents:write	Atualiza título, descrição, severidade ou atribuição
runframe_change_incident_status	incidents:write	Move para um novo status (novo, investigando, corrigindo, monitorando, resolvido, fechado)
runframe_acknowledge_incident	incidents:write	Reconhece (atribui automaticamente, rastreia SLA)
runframe_add_incident_event	incidents:write	Adiciona uma entrada na linha do tempo
runframe_escalate_incident	incidents:write	Escala para o próximo nível da política
runframe_page_someone	incidents:write	Aciona um respondente via Slack ou e-mail

Plantão (1)

Ferramenta	Escopos	Descrição
runframe_get_current_oncall	oncall:read	Quem está de plantão agora

Serviços (2)

Ferramenta	Escopos	Descrição
runframe_list_services	services:read	Lista serviços
runframe_get_service	services:read	Obtém detalhes do serviço

Postmortems (2)

Ferramenta	Escopos	Descrição
runframe_create_postmortem	postmortems:write	Cria um postmortem
runframe_get_postmortem	postmortems:read	Obtém postmortem de um incidente

Equipes (2)

Ferramenta	Escopos	Descrição
runframe_list_teams	teams:read	Lista equipes
runframe_get_escalation_policy	oncall:read	Obtém política de escalonamento para um nível de severidade

Usuários (1)

Ferramenta	Escopos	Descrição
runframe_find_user	users:read	Busca usuários por nome ou e-mail, com suporte opcional a usuários inativos para consultas históricas

Alinhamento direto com a API

Este servidor MCP segue o contrato público da API direta do Runframe.

• A criação de incidentes requer service_ids contendo chaves públicas de serviço como svc_K7M4Q9TZ2H, não UUIDs internos.
• runframe_get_service agora busca serviços pela service_key pública, não por UUID.
• As ferramentas de incidentes agora seguem o contrato V1 mais recente: use números de incidente como INC-2026-001 em parâmetros de caminho.
• Atualização de incidentes e filtros de listagem agora usam os identificadores públicos mais recentes onde o V1 usa: e-mail do responsável/resolvedor e team_name.
• runframe_create_incident aceita um idempotency_key opcional, que é encaminhado como cabeçalho Idempotency-Key para criações seguras contra duplicação (retry-safe).
• runframe_create_incident define severity como padrão SEV2 quando omitido, alinhado à API V1.
• A criação de incidentes agora reflete os limites da API V1: title deve ter de 1 a 200 caracteres, description tem máximo de 10000 caracteres e service_ids permite no máximo 50 itens.
• A criação de incidentes depende de configuração válida de SLA para a severidade solicitada. Se os prazos de reconhecimento ou encerramento estiverem ausentes, a API rejeita a criação.
• Use runframe_list_services para descobrir valores válidos de service_key antes de criar incidentes.
• runframe_page_someone agora usa o contrato de entrega V1 mais recente: email, channels e message opcional.
• As ferramentas de postmortem agora seguem o contrato V1 mais recente: use incident_number e campos aninhados em snake_case como users_affected, owner_email e time_to_acknowledge.
• Use runframe_find_user para resolver um nome de pessoa para um endereço de e-mail antes de filtrar incidentes por assigned_to ou resolved_by.
• Defina include_inactive=true em runframe_find_user quando precisar resolver ex-funcionários em consultas históricas de incidentes.
• Defina is_active=true ou is_active=false em runframe_find_user quando precisar de um filtro explícito de estado ativo V1.
• Use runframe_list_teams com search para resolver o team_name exato antes de filtrar incidentes.

Docker

A imagem Docker executa transporte HTTP por padrão na porta 3100:

docker build -t runframe-mcp-server .
docker run -e RUNFRAME_API_KEY=rf_... -e MCP_ACCESS_TOKEN=your_token -p 3100:3100 runframe-mcp-server

Implantando o Modo HTTP

O modo HTTP é destinado a redes privadas. Se você o colocar na internet:

• Execute atrás de TLS (nginx, Caddy, balanceador de carga em nuvem). Este servidor não faz TLS.
• Use um proxy reverso para limitação de taxa e buffer de requisições.
• Prefira sub-redes privadas ou VPNs em vez de exposição pública.
• Rotacione MCP_ACCESS_TOKEN regularmente. Passe tokens antigos e novos separados por vírgulas para trocas sem interrupção.

Limitação de taxa

A API do Runframe aplica limites de taxa no lado do servidor. Se você atingir um limite, as ferramentas retornam um erro 429 com uma dica de nova tentativa. Para implantações com transporte HTTP, seu proxy reverso pode adicionar limitação adicional em nível de requisição.

Rotação de token

MCP_ACCESS_TOKEN aceita tokens separados por vírgulas:

1. Defina MCP_ACCESS_TOKEN=new_token,old_token
2. Atualize os clientes para new_token
3. Remova o antigo: MCP_ACCESS_TOKEN=new_token

Limitações

• Somente leitura para escalas — você pode consultar plantões e políticas de escalonamento, mas não modificá-los via MCP
• Requer uma conta Runframe e chave de API

Contribuindo

Issues e PRs são bem-vindos em github.com/runframe/runframe-mcp-server.

Licença

MIT — Runframe · npm