MCP para agentes

Un cliente MCP conectado a Perstat responde “¿qué está roto y quién se encarga?” a partir de tus datos y actúa dentro de su autorización. El catálogo fuente revisado el 26 de agosto de 2026 define quince herramientas: siete leen, dos actúan sobre un incidente y seis gestionan proyectos y monitores. En el servidor conectado manda tools/list; create_project no se ha verificado por separado en producción. Ninguna herramienta definida borra el registro.

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: este servidor no abre ningún stream de eventos por iniciativa propia. Los batches JSON-RPC desaparecieron en la 2025-06-18 y 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.

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 y leer el estado actual.

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: no hay 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; Perstat debe aparecer como Connected.

Usa la línea con clave de API anterior para CI, cron o credenciales limitadas expresamente a proyectos. 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; también publican endpoints de refresh y revocación. Una cookie de sesión del navegador por sí sola no autentica MCP: el flujo OAuth termina en un bearer token.

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, no solo el nombre que se da a sí mismo, y un cliente solo recibe 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, Claves de API.

Las herramientas

tools/list muestra solo 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 completo del código tiene quince herramientas. El OAuth del navegador concede hoy scopes de monitores e incidentes, por lo que los usuarios del plugin no reciben list_status_pages. Una clave de API con status-pages:read sí lo habilita. Para cada credencial, la respuesta tools/list del servidor conectado es la referencia práctica.

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

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

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 no cambia por ello, 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) 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.

Archivado mediante MCP, no borrado mediante MCP

Un agente puede archivar un servicio. Borrarlo, nunca, y el motivo no es la prudencia.

Borrar un monitor se propaga en cascada por once tablas y se lleva por delante el historial de incidentes, los rollups SLA diarios y las ventanas de exclusión. En un producto cuyo sentido entero es el registro, eso no puede quedar al alcance de la llamada de un agente. Así que la herramienta que lo haría, directamente, no existe.

archive_monitor detiene el servicio, lo saca de las listas activas y libera su plaza en el plan, manteniendo el recurso restaurable. Archivar no borra por sí mismo el historial, pero siguen vigentes las reglas normales de conservación por objeto; no es almacenamiento permanente. restore_monitor lo trae 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 el cupo del plan la diferencia importa, porque no son lo mismo: pausar no libera la plaza; el monitor sigue ahí y sigues contando con él. Archivar, sí. Si de verdad quieres que algo desaparezca del todo, bórralo en la app, donde una persona está mirando las consecuencias.

El camino de vuelta no puede depender de la memoria. list_monitors con archived: true muestra el archivo, y get_monitor encuentra también los servicios archivados, así que puedes mirar antes de restaurar. Sin eso, un monitor archivado sería inalcanzable a través de MCP en cuanto alguien perdiera el ID. Lo que no se puede hacer con un monitor archivado es cambiarlo o encenderlo: update_monitor y set_monitor_enabled lo rechazan con “is archived, call restore_monitor first” y no con “not found”, porque no es que falte.

También fuera del alcance de escritura de MCP: cambios en páginas de estado, conectores, claves de API, miembros y el plan. list_status_pages es una excepción de solo lectura para claves API con status-pages:read; el OAuth del navegador no recibe ese scope hoy. Las escrituras operativas se quedan en la monitorización y los incidentes.

Cada acción lleva un nombre

Una acción por MCP se atribuye a la identidad humana de la credencial: quien creó la clave 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 no se ve afectada y depende solo 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 solo ve sus propios recursos en list_monitors y list_incidents. Todo lo demás, para ella, simplemente no existe, 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, ni se ofrecen a una clave acotada. Las dos herramientas de creación le permitirían 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 no es un error de protocolo. 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 de verdad.