MCP para agentes

Un cliente MCP conectado a Perstat responde “¿qué está roto y quién se encarga?” a partir de tus datos en directo y actúa dentro de su autorización. El catálogo tiene diecisiete herramientas: siete leen, dos actúan sobre un incidente y ocho gestionan proyectos y monitores. El tools/list del servidor conectado muestra exactamente cuáles puede usar la credencial que tienes delante. Cada herramienta conserva tu registro: retirar un servicio es archivarlo.

Conexión

Endpoint	https://api.perstat.io/mcp
Transporte	Streamable HTTP, sin estado
Versiones del protocolo	2025-06-18 (preferida), 2025-03-26, 2024-11-05

Entra un mensaje JSON-RPC por POST, sale una respuesta JSON. GET /mcp responde 405, porque el servidor trabaja petición a petición, sin abrir un stream de eventos por iniciativa propia. Los batches JSON-RPC, retirados del protocolo en la 2025-06-18, se rechazan con un mensaje claro.

En Claude Code:

claude mcp add --transport http perstat https://api.perstat.io/mcp \
  --header "Authorization: Bearer pst_…"

Esta forma funciona en clientes que acepten un encabezado HTTP de autorización personalizado. La clave acaba así en el historial de la shell, y para el trabajo interactivo el acceso por navegador del plugin es el camino más limpio.

O instala el plugin

Para Claude Code hay un plugin. Conecta el mismo servidor y añade cuatro skills que convierten las herramientas en flujos de trabajo: ocuparse de un incidente, gestionar los monitores, informar del estado actual y consultar todos los tipos de monitor.

claude plugin marketplace add datargo/perstat-plugin
claude plugin install perstat@datargo

En la primera llamada a una herramienta de Perstat, Claude abre el acceso OAuth en el navegador. Elige la organización de la conexión, y listo: ninguna clave que copiar ni perfil de shell que editar. La conexión queda vinculada a esa organización y a tu rol actual. Compruébala con claude mcp list, donde Perstat debe aparecer como Connected.

Usa la línea con clave de API anterior para CI, cron o credenciales limitadas a proyectos concretos. El plugin es el camino interactivo, autenticado en el navegador.

Autenticación

Perstat acepta una clave de API de la organización limitada por scopes como bearer:

Authorization: Bearer pst_…

Un cliente compatible con OAuth puede usar el flujo Authorization Code publicado con PKCE. Los documentos de discovery están en https://api.perstat.io/.well-known/oauth-protected-resource/mcp y https://api.perstat.io/.well-known/oauth-authorization-server, que también publican los endpoints de refresh y revocación. MCP se autentica siempre con un bearer token: el flujo OAuth termina en uno, y una cookie de sesión del navegador por sí sola no basta.

Se aceptan clientes OAuth de Claude, Claude Code y ChatGPT, reconocidos por sus documentos de cliente bajo https://claude.ai/oauth/ y https://chatgpt.com/oauth/. La pantalla de consentimiento nombra el host del que viene el cliente, además del nombre que se da a sí mismo, y un cliente recibe exactamente los permisos que necesitan sus herramientas: monitors e incidents, cada uno de lectura o de escritura.

Una clave de organización pertenece a una sola organización y lleva scopes: no puede hacer más de lo que diga la clave.

Las claves las crean owners y admins en la app, en Integraciones, luego Claves de API.

Las herramientas

tools/list muestra lo que permite la autorización actual. tools/call comprueba el mismo scope otra vez, porque una lista no es una salvaguarda.

El catálogo tiene diecisiete herramientas. El OAuth del navegador concede los scopes de monitores e incidentes, y una clave de API con status-pages:read añade list_status_pages. Para cada credencial, la respuesta tools/list del servidor conectado es la referencia.

Herramienta	Scope	Qué hace
get_organization_summary	monitors:read	El cuadro completo en una llamada: servicios por estado, incidentes abiertos
list_projects	monitors:read	Los proyectos con su número de monitores. El punto de entrada para create_monitor
list_monitors	monitors:read	Los servicios con el último estado confirmado, con filtros. Con archived: true, también el archivo
get_monitor	monitors:read	Un servicio con su configuración, regiones e incidentes recientes. Los valores de las cabeceras de petición propias vuelven como [redacted]
list_incidents	incidents:read	Incidentes abiertos y resueltos, los más nuevos primero
get_incident	incidents:read	Un incidente al detalle
acknowledge_incident	incidents:write	Hacerse cargo del incidente, lo que detiene la alerta y el escalado
resolve_incident	incidents:write	Cerrar a mano un incidente abierto
list_status_pages	status-pages:read	Las páginas de estado de la organización
create_project	monitors:write	Crear la carpeta que contiene los monitores. Solo con claves de toda la organización
create_monitor	monitors:write	Empezar a monitorizar un servicio nuevo. Solo con claves de toda la organización
update_monitor	monitors:write	Cambiar el nombre, la configuración, el intervalo de check o las regiones
set_monitor_enabled	monitors:write	Pausar un monitor o devolverlo al servicio
archive_monitor	monitors:write	Retirar un servicio y liberar su plaza en el plan
restore_monitor	monitors:write	Recuperar un servicio archivado. Vuelve en pausa y necesita un hueco libre en el plan
get_heartbeat_endpoint	monitors:write	La URL secreta de ping de un heartbeat, para conectar su tarea. Cada llamada queda en el registro de actividad
rotate_heartbeat_endpoint	monitors:write	Emitir una nueva URL de ping para un heartbeat. La anterior deja de funcionar al instante

write implica read sobre el mismo recurso, nunca de un recurso a otro.

create_monitor y update_monitor aceptan cualquier intervalo de check entre el mínimo de tu plan y 24 horas, también 15 s en Command y 10 s en Enterprise. Un valor por debajo del mínimo sube al mínimo.

Todo lo que ve el agente está en inglés: nombres de herramientas, descripciones, textos de esquema y motivos de error. El registro de actividad de la app sigue en tu idioma, porque ese lo leen personas.

create_project y create_monitor son las dos herramientas no idempotentes, y se lo declaran al cliente. Repetir cualquiera de las dos llamadas puede crear un segundo recurso o fallar por el nombre. Mira primero con list_projects o list_monitors.

Las herramientas que cambian o terminan un estado existente (acknowledge_incident, resolve_incident, update_monitor, set_monitor_enabled, archive_monitor, rotate_heartbeat_endpoint) están marcadas como destructivas, para que un cliente pueda pedir confirmación antes de llamarlas. Crear y restaurar solo añaden.

Las cabeceras de petición propias de un monitor son credenciales y nunca se releen mediante una clave o un agente: get_monitor muestra sus nombres con el valor [redacted]. Si envías de vuelta una configuración con el marcador mediante update_monitor, se conserva el valor guardado mientras la URL y el método sigan exactamente iguales. Tras cualquier cambio en uno de los dos, el marcador se rechaza, para que una credencial nunca siga a una petición que su autor no configuró. La aplicación web sigue mostrando los valores a los miembros con sesión iniciada.

La URL de ping de un heartbeat también es una credencial: quien la tiene puede notificar éxito en nombre de la tarea y mantener así en verde una caída. Aun así, un agente la necesita para terminar la configuración, por eso create_monitor la devuelve para un heartbeat nuevo y get_heartbeat_endpoint la devuelve de nuevo más tarde. Ambas exigen monitors:write y una persona detrás de la clave que todavía pueda gestionar monitores, y cada entrega queda en el registro de actividad. get_heartbeat_endpoint no lleva la marca de solo lectura, para que un cliente pregunte antes de obtener una credencial. La URL queda después en la conversación del agente. Si no confías en esa conversación, rota la URL en la aplicación web tras la configuración, porque rotate_heartbeat_endpoint pondría la nueva en la misma conversación.

MCP archiva y conserva el registro

Un agente retira un servicio archivándolo, y su historial se queda en su sitio.

Usa archive_monitor para retirar un servicio y conservar sus incidentes, historial, rollups SLA y ventanas de exclusión. La misma operación está disponible en la API REST con POST /monitors/{monitor_id}/archive, y POST /monitors/{monitor_id}/restore para restaurarlo. Archivar cierra los incidentes abiertos, detiene las escalaciones y cierra sus alertas en los conectores externos. La eliminación definitiva mediante clave de API está deprecada desde el 2 de octubre de 2026, con cambio no antes del 1 de enero de 2027 a las 00:00 UTC. Las respuestas DELETE satisfactorias incluyen un enlace al aviso.

archive_monitor detiene los checks, saca el servicio de las listas activas y libera su plaza en el plan, manteniendo el recurso restaurable. El historial se queda y sigue las reglas normales de conservación por objeto. restore_monitor trae el servicio de vuelta en pausa y vuelve a ocupar un hueco del plan: si el plan está lleno, la restauración se rechaza con el mismo mensaje que create_monitor hasta que se archive otro monitor o se cambie de plan. El nombre queda libre al archivar, así que un monitor nuevo puede ocuparlo.

Para la cuota del plan, la diferencia importa: archivar libera la plaza, pausar la conserva, porque un monitor en pausa sigue ahí y sigues contando con él.

El camino de vuelta siempre está a la vista. list_monitors con archived: true muestra el archivo, y get_monitor encuentra también los servicios archivados, así que puedes mirar antes de restaurar, aunque no tengas el ID a mano. Para cambiar un monitor archivado o encenderlo, restáuralo primero: update_monitor y set_monitor_enabled responden “is archived, call restore_monitor first”, lo que indica al agente exactamente qué hacer.

Las escrituras por MCP se centran en la monitorización y los incidentes. Las páginas de estado, los webhooks y los miembros se gestionan con una clave mediante la API REST, y las claves de API y la facturación en la app. list_status_pages lee las páginas de estado para claves de API con status-pages:read.

Cada acción lleva un nombre

Una acción por MCP se atribuye a la identidad humana de la credencial: quien creó la clave de API o el sujeto OAuth. Así, hacerse cargo durante un incidente lleva un nombre, no solo un token. La cronología del incidente registra además que llegó por MCP. Los monitores que un agente crea o cambia aparecen de la misma forma en el registro de actividad, con el nombre de esa identidad.

Como esa identidad se toma prestada para la atribución, también manda sobre los permisos. En cada escritura, sin excepción, el servidor vuelve a comprobar que la identidad sigue siendo miembro de la organización y sigue teniendo el rol que la acción exige. El listón es el mismo que en la app: ocuparse de incidentes puede hacerlo quien tenga permiso para responder, hasta un responder. Gestionar monitores, quien pueda gestionar proyectos, así que un owner, admin o developer. Si esa identidad baja de rol o sale de la organización, su credencial deja de escribir a partir de la siguiente llamada. La lectura continúa y depende de los scopes de la credencial. Si la cuenta de esa persona se ha borrado, el servidor rechaza también la escritura, y dice por qué.

Claves acotadas

Una clave restringida a ciertos proyectos o monitores ve sus propios recursos en list_monitors y list_incidents. Todo lo demás le resulta invisible, y no hay forma de tantear si podría existir. Al escribir pasa lo mismo: update_monitor y set_monitor_enabled responden que no hay ningún monitor con ese ID, no que esté prohibido.

Las herramientas de toda la organización, get_organization_summary, list_status_pages, create_project y create_monitor, quedan reservadas a las claves de toda la organización. Las dos herramientas de creación permitirían si no a una clave acotada escribir en proyectos de los que no sabe nada.

Errores

Las herramientas de listado devuelven total_matching y truncated junto a las filas, así que una respuesta recortada se reconoce como tal en lugar de parecer un resultado completo.

Un fallo dentro de una herramienta vuelve como un resultado marcado como error, con el motivo en lenguaje llano, para que el modelo vea qué ha salido mal y pruebe otra cosa. Los errores de protocolo quedan reservados para las peticiones malformadas.

Siguientes pasos

• API: la API REST completa con claves de API.
• Webhook firmado: envía los incidentes a tus propias herramientas.