Runframe

runframe-mcp-server

Runframe es la plataforma completa de ciclo de vida de incidentes para equipos de ingeniería, que cubre respuesta a incidentes, guardias (on-call) y páginas de estado. Este servidor MCP te permite gestionar esos flujos de trabajo desde tu IDE o agente de IA.

17 herramientas que cubren incidentes, guardias, servicios, postmortems, equipos y búsqueda de personas. Requiere Node.js 20+.

Por Qué Usarlo

• Mantente en tu editor — reconoce incidentes, pagina a los responsables y escribe postmortems sin cambiar al navegador
• Deja que los agentes manejen lo rutinario — los agentes de IA pueden triage, escalar y actualizar incidentes de forma autónoma usando claves API con alcance limitado
• Cero infraestructura — se ejecuta mediante npx, sin servidor que desplegar para uso local

Cómo Funciona

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

El servidor no tiene estado. Traduce las llamadas de herramientas MCP en solicitudes a la API de Runframe, limitadas por los permisos de tu clave API. No se almacenan datos localmente.

Ejemplos

Pregunta a tu agente:

• "Reconoce el incidente INC-2026-001" → llama a runframe_acknowledge_incident
• "¿Quién está de guardia ahora mismo?" → llama a runframe_get_current_oncall
• "Crea un postmortem para la caída de la base de datos" → llama a runframe_create_postmortem
• "Página al líder del equipo de backend por el pico de latencia de la API" → llama a runframe_page_someone
• "Lista todos los incidentes SEV1 abiertos" → llama a runframe_list_incidents con filtro de severidad
• "Encuentra a Alex para revisar sus incidentes abiertos" → llama a runframe_find_user

Instalación

Obtén tu clave API desde la configuración en Runframe.io, luego añádela a tu 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" }
    }
  }
}

Otros clientes MCP: Añade la configuración JSON anterior al archivo de configuración MCP de tu cliente.

Asistente de configuración interactivo:

npx @runframe/mcp-server --setup

Variables de Entorno

Variable	Requerida	Predeterminado	Descripción
RUNFRAME_API_KEY	Sí	—	Clave API (comienza con rf_)
RUNFRAME_API_URL	No	https://runframe.io	URL base de la API
MCP_ACCESS_TOKEN	Solo HTTP	—	Token Bearer para transporte HTTP. Separado por comas para rotación (new_token,old_token).

Transportes

stdio (predeterminado) — utilizado por clientes MCP como Claude Code y Cursor. Sin exposición a la red. Esto es lo que configuran los comandos de instalación anteriores.

HTTP transmisible — para despliegues en contenedores o remotos. Requiere MCP_ACCESS_TOKEN para autenticación 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 Seguridad

La responsabilidad se divide en tres límites:

• La API de Runframe maneja la autorización y los alcances mediante RUNFRAME_API_KEY.
• Este servidor MCP maneja el aislamiento de procesos (stdio) y la validación de tokens bearer (HTTP). También aplica filtrado de métodos, comprobaciones de Host/Origin en localhost, validación de Content-Length declarado (límite de 1 MB), límite de cabecera de 8 KB y tiempo de espera ascendente de 15 s.
• Tu proxy inverso maneja TLS, limitación de velocidad y aplicación de cuerpo transmitido si expones el modo HTTP a una red.

El servidor no almacena nada. Es un paso directo a la API de Runframe.

Herramientas

Incidentes (9)

Herramienta	Alcances	Descripción
runframe_list_incidents	incidents:read	Lista incidentes con filtros y paginación
runframe_get_incident	incidents:read	Obtiene incidente por ID o número
runframe_create_incident	incidents:write	Crea un incidente
runframe_update_incident	incidents:write	Actualiza título, descripción, severidad o asignación
runframe_change_incident_status	incidents:write	Mueve a un nuevo estado (nuevo, investigando, corrigiendo, monitoreando, resuelto, cerrado)
runframe_acknowledge_incident	incidents:write	Reconoce (auto-asigna, rastrea SLA)
runframe_add_incident_event	incidents:write	Añade una entrada de cronología
runframe_escalate_incident	incidents:write	Escala al siguiente nivel de política
runframe_page_someone	incidents:write	Página a un responsable vía Slack o correo electrónico

Guardias (1)

Herramienta	Alcances	Descripción
runframe_get_current_oncall	oncall:read	Quién está de guardia ahora mismo

Servicios (2)

Herramienta	Alcances	Descripción
runframe_list_services	services:read	Lista servicios
runframe_get_service	services:read	Obtiene detalles del servicio

Postmortems (2)

Herramienta	Alcances	Descripción
runframe_create_postmortem	postmortems:write	Crea un postmortem
runframe_get_postmortem	postmortems:read	Obtiene postmortem para un incidente

Equipos (2)

Herramienta	Alcances	Descripción
runframe_list_teams	teams:read	Lista equipos
runframe_get_escalation_policy	oncall:read	Obtiene política de escalado para un nivel de severidad

Usuarios (1)

Herramienta	Alcances	Descripción
runframe_find_user	users:read	Busca usuarios por nombre o correo electrónico, con soporte opcional de usuarios inactivos para búsquedas históricas

Alineación directa con la API

Este servidor MCP sigue el contrato público de la API directa de Runframe.

• La creación de incidentes requiere service_ids que contenga claves de servicio públicas como svc_K7M4Q9TZ2H, no UUIDs internos.
• runframe_get_service ahora busca servicios por service_key público, no por UUID.
• Las herramientas de incidentes ahora siguen el contrato V1 más reciente: usa números de incidente como INC-2026-001 en parámetros de ruta.
• La actualización de incidentes y los filtros de lista ahora usan los identificadores públicos más recientes donde V1 lo hace: correo electrónico de asignado/resolvedor y team_name.
• runframe_create_incident acepta un idempotency_key opcional, que se reenvía como cabecera Idempotency-Key para creaciones seguras contra reintentos.
• runframe_create_incident establece severity por defecto a SEV2 cuando se omite, coincidiendo con la API V1.
• La creación de incidentes ahora refleja los límites de la API V1: title debe tener 1-200 caracteres, description tiene un máximo de 10000 caracteres, y service_ids permite como máximo 50 elementos.
• La creación de incidentes depende de una configuración SLA válida para la severidad solicitada. Si faltan plazos de reconocimiento o cierre, la API rechaza la creación.
• Usa runframe_list_services para descubrir valores válidos de service_key antes de crear incidentes.
• runframe_page_someone ahora usa el contrato de entrega V1 más reciente: email, channels y message opcional.
• Las herramientas de postmortem ahora siguen el contrato V1 más reciente: usa incident_number y campos anidados en snake_case como users_affected, owner_email y time_to_acknowledge.
• Usa runframe_find_user para resolver un nombre de persona a una dirección de correo electrónico antes de filtrar incidentes por assigned_to o resolved_by.
• Establece include_inactive=true en runframe_find_user cuando necesites resolver empleados anteriores en consultas históricas de incidentes.
• Establece is_active=true o is_active=false en runframe_find_user cuando necesites un filtro explícito de estado activo V1.
• Usa runframe_list_teams con search para resolver el team_name exacto antes de filtrar incidentes.

Docker

La imagen Docker ejecuta transporte HTTP por defecto en el puerto 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

Despliegue del Modo HTTP

El modo HTTP está pensado para redes privadas. Si lo pones en internet:

• Ejecuta detrás de TLS (nginx, Caddy, balanceador de carga en la nube). Este servidor no hace TLS.
• Usa un proxy inverso para limitación de velocidad y almacenamiento en búfer de solicitudes.
• Prefiere subredes privadas o VPNs sobre exposición pública.
• Rota MCP_ACCESS_TOKEN regularmente. Pasa tokens antiguos y nuevos separados por comas para cambios sin tiempo de inactividad.

Limitación de velocidad

La API de Runframe aplica límites de velocidad del lado del servidor. Si alcanzas un límite, las herramientas devuelven un error 429 con una sugerencia de reintento. Para despliegues con transporte HTTP, tu proxy inverso puede añadir limitación adicional a nivel de solicitud.

Rotación de tokens

MCP_ACCESS_TOKEN acepta tokens separados por comas:

1. Establece MCP_ACCESS_TOKEN=new_token,old_token
2. Actualiza los clientes a new_token
3. Elimina el antiguo: MCP_ACCESS_TOKEN=new_token

Limitaciones

• Solo lectura para horarios — puedes consultar guardias y políticas de escalado pero no modificarlas vía MCP
• Requiere una cuenta de Runframe y clave API

Contribuciones

Se aceptan issues y PRs en github.com/runframe/runframe-mcp-server.

Licencia

MIT — Runframe · npm