MCP pour les agents

Un client MCP relié à Perstat répond à « qu’est-ce qui est tombé et qui s’en occupe » à partir de vos données en direct, puis agit dans les limites de son autorisation. Le catalogue compte dix-sept outils : sept lisent, deux agissent sur un incident et huit gèrent projets et monitors. Le tools/list du serveur connecté indique exactement lesquels l’accès dont vous disposez peut utiliser. Chaque outil préserve votre registre : retirer un service, c’est l’archiver.

Connexion

Endpoint	https://api.perstat.io/mcp
Transport	Streamable HTTP, sans état
Versions du protocole	2025-06-18 (préférée), 2025-03-26, 2024-11-05

Un message JSON-RPC entre par POST, une réponse JSON ressort. GET /mcp répond 405, car le serveur travaille requête par réponse, sans flux d’événements ouvert de sa propre initiative. Les lots JSON-RPC, retirés du protocole avec 2025-06-18, sont rejetés avec un message clair.

Dans Claude Code :

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

Cette forme fonctionne avec les clients qui acceptent un en-tête HTTP d’autorisation personnalisé. La clé finit alors dans l’historique de votre shell, et pour le travail interactif la connexion par navigateur du plugin est la voie la plus propre.

Ou installer le plugin

Pour Claude Code, il existe un plugin. Il se branche sur le même serveur et ajoute quatre skills qui transforment les outils en workflows : traiter un incident, gérer les monitors, rendre compte de l’état actuel et consulter tous les types de monitors.

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

Au premier appel d’un outil Perstat, Claude ouvre l’authentification OAuth dans votre navigateur. Choisissez l’organisation de la connexion, et c’est prêt : aucune clé à copier ni profil shell à modifier. La connexion reste liée à cette organisation et à votre rôle actuel. Vérifiez-la avec claude mcp list, où Perstat doit indiquer Connected.

Gardez la commande avec clé API ci-dessus pour la CI, cron ou un accès limité à certains projets. Le plugin est la voie interactive, authentifiée par navigateur.

Authentification

Perstat accepte une clé API d’organisation limitée par scopes comme bearer :

Authorization: Bearer pst_…

Un client compatible OAuth peut utiliser le flux Authorization Code publié avec PKCE. Les documents de découverte sont https://api.perstat.io/.well-known/oauth-protected-resource/mcp et https://api.perstat.io/.well-known/oauth-authorization-server, qui publient aussi les endpoints de refresh et de révocation. MCP s’authentifie toujours avec un bearer token : le flux OAuth se termine par l’un d’eux, et un cookie de session navigateur seul ne suffit pas.

Les clients OAuth sont acceptés depuis Claude, Claude Code et ChatGPT, reconnus à leurs documents client sous https://claude.ai/oauth/ et https://chatgpt.com/oauth/. L’écran de consentement nomme l’hôte d’où vient le client, en plus du nom qu’il se donne, et un client reçoit exactement les droits dont ses outils ont besoin : monitors et incidents, chacun en lecture ou en écriture.

Une clé d’organisation appartient à une seule organisation et porte des scopes : elle ne peut jamais faire plus que ce que dit la clé.

Les owners et les admins créent les clés dans l’application, sous Intégrations, puis Clés API.

Les outils

tools/list montre ce que l’autorisation actuelle permet. tools/call revérifie le même scope, parce qu’une liste n’est pas une protection.

Le catalogue compte dix-sept outils. L’OAuth navigateur accorde les scopes monitors et incidents, et une clé API avec status-pages:read ajoute list_status_pages. Pour l’accès concret, la réponse tools/list du serveur connecté fait référence.

Outil	Scope	Effet
get_organization_summary	monitors:read	Toute la situation en un appel : les services par état, les incidents ouverts
list_projects	monitors:read	Les projets avec leur nombre de monitors. Le point d’entrée pour create_monitor
list_monitors	monitors:read	Les services avec leur dernier état confirmé, filtrables. Passez archived: true pour l’archive
get_monitor	monitors:read	Un service avec configuration, régions et incidents récents. Les valeurs des en-têtes de requête personnalisés reviennent en [redacted]
list_incidents	incidents:read	Incidents ouverts et résolus, les plus récents d’abord
get_incident	incidents:read	Un incident en détail
acknowledge_incident	incidents:write	Prendre l’incident, ce qui arrête l’alerte et l’escalade
resolve_incident	incidents:write	Fermer un incident ouvert à la main
list_status_pages	status-pages:read	Les pages de statut de l’organisation
create_project	monitors:write	Créer le dossier qui contient les monitors. Clés à l’échelle de l’organisation uniquement
create_monitor	monitors:write	Mettre un nouveau service sous monitoring. Clés à l’échelle de l’organisation uniquement
update_monitor	monitors:write	Changer le nom, les réglages, l’intervalle de check ou les régions
set_monitor_enabled	monitors:write	Mettre un monitor en pause ou le remettre en service
archive_monitor	monitors:write	Retirer un service de l’exploitation et libérer sa place dans votre formule
restore_monitor	monitors:write	Ramener un service archivé. Il revient en pause et a besoin d’une place libre dans la formule
get_heartbeat_endpoint	monitors:write	L’URL secrète de ping d’un heartbeat, pour câbler sa tâche. Chaque appel figure dans le journal d’activité
rotate_heartbeat_endpoint	monitors:write	Émettre une nouvelle URL de ping pour un heartbeat. L’ancienne cesse de fonctionner aussitôt

write implique read sur la même ressource, jamais d’une ressource à l’autre.

create_monitor et update_monitor acceptent tout intervalle de check entre le plancher de votre formule et 24 heures, y compris 15 s avec Command et 10 s avec Enterprise. Une valeur sous le plancher est relevée au plancher.

Tout ce que l’agent voit est en anglais : noms d’outils, descriptions, textes de schéma, motifs d’erreur. Le journal d’activité dans l’application reste dans votre langue, car ce sont des humains qui le lisent.

create_project et create_monitor sont les deux outils non idempotents, et ils le déclarent au client. Répéter l’un ou l’autre appel peut créer une seconde ressource ou échouer sur le nom. Regardez d’abord avec list_projects ou list_monitors.

Les outils qui modifient ou terminent un état existant (acknowledge_incident, resolve_incident, update_monitor, set_monitor_enabled, archive_monitor, rotate_heartbeat_endpoint) sont marqués comme destructifs, afin qu’un client puisse demander confirmation avant de les appeler. Créer et restaurer ne font qu’ajouter.

Les en-têtes de requête personnalisés d’un monitor sont des identifiants et ne sont jamais relus par une clé ou un agent : get_monitor montre leurs noms avec la valeur [redacted]. Renvoyez une configuration avec le marqueur via update_monitor, et la valeur enregistrée est conservée, tant que l’URL et la méthode restent exactement identiques. Après toute modification de l’une ou de l’autre, le marqueur est refusé, pour qu’un identifiant ne suive jamais une requête que son auteur n’a pas configurée. L’application web continue d’afficher les valeurs aux membres connectés.

L’URL de ping d’un heartbeat est elle aussi un identifiant : qui la détient peut signaler un succès au nom de la tâche et maintenir ainsi une panne au vert. Un agent en a pourtant besoin pour terminer la mise en place, c’est pourquoi create_monitor la renvoie pour un nouveau heartbeat et get_heartbeat_endpoint la renvoie à nouveau plus tard. Les deux exigent monitors:write et une personne derrière la clé qui peut encore gérer les monitors, et chaque remise est consignée dans le journal d’activité. get_heartbeat_endpoint ne porte pas la marque lecture seule, afin qu’un client demande avant de récupérer un identifiant. L’URL figure ensuite dans la conversation de l’agent. Si vous ne faites pas confiance à cette conversation, renouvelez l’URL dans l’application web après la mise en place, car rotate_heartbeat_endpoint placerait la nouvelle dans la même conversation.

MCP archive et conserve le registre

Un agent retire un service en l’archivant, et son historique reste en place.

Utilisez archive_monitor pour retirer un service et conserver ses incidents, son historique, ses agrégats SLA et ses fenêtres d’exclusion. La même opération est disponible sur l’API REST avec POST /monitors/{monitor_id}/archive, puis POST /monitors/{monitor_id}/restore pour le retour. L’archivage clôt les incidents ouverts, arrête les escalades et clôt leurs alertes chez les connecteurs externes. La suppression définitive par clé API est dépréciée depuis le 2 octobre 2026, avec changement au plus tôt le 1er janvier 2027 à 00:00 UTC. Les réponses DELETE réussies renvoient à l’annonce.

archive_monitor arrête les checks, retire le service des listes actives et libère sa place dans votre formule, tout en gardant la ressource restaurable. L’historique reste et suit les règles normales de rétention par objet. restore_monitor ramène le service en pause et occupe de nouveau une place de la formule : si la formule est pleine, la restauration est refusée avec le même message que create_monitor, jusqu’à ce qu’un autre monitor soit archivé ou que la formule change. Le nom est libéré à l’archivage, un nouveau monitor peut donc le reprendre.

Pour votre quota, la différence compte : archiver libère une place, mettre en pause la garde, car un monitor en pause est toujours là et toujours voulu.

Le chemin du retour est toujours visible. list_monitors avec archived: true montre l’archive, et get_monitor trouve aussi les services archivés : vous pouvez regarder avant de restaurer, même sans l’ID sous la main. Pour modifier un monitor archivé ou le rallumer, restaurez-le d’abord : update_monitor et set_monitor_enabled répondent « is archived, call restore_monitor first », ce qui indique à l’agent exactement quoi faire.

Les écritures MCP se concentrent sur le monitoring et les incidents. Les pages de statut, les webhooks et les membres se gèrent avec une clé via l’API REST, les clés API et la facturation dans l’application. list_status_pages lit les pages de statut pour les clés API avec status-pages:read.

Chaque action porte un nom

Une action par MCP est attribuée à l’identité humaine de l’accès : créateur de la clé API ou sujet OAuth. La prise d’un incident porte ainsi un nom, pas seulement un token. La chronologie de l’incident note en plus que l’action est passée par MCP. Les monitors qu’un agent crée ou modifie apparaissent de la même façon dans le journal d’activité de votre organisation, sous le nom de cette identité.

Parce que cette identité est empruntée pour l’attribution, elle décide aussi des droits. À chaque écriture, le serveur revérifie que l’identité est encore membre de l’organisation et porte encore le rôle que l’action exige. Le seuil est celui de l’application : traiter un incident demande le droit de répondre, jusqu’au rôle responder. Gérer des monitors demande le droit de gérer des projets, donc owner, admin ou developer. Rétrogradez ou retirez cette identité, et son accès cesse d’écrire dès l’appel suivant. La lecture continue et dépend des scopes de l’accès. Si le compte de cette personne a été supprimé, le serveur refuse aussi l’écriture, et dit pourquoi.

Clés restreintes

Une clé limitée à certains projets ou monitors voit ses propres ressources dans list_monitors et list_incidents. Le reste lui est invisible, et rien ne lui permet de vérifier si quelque chose existe ailleurs. À l’écriture, même chose : update_monitor et set_monitor_enabled répondent qu’aucun monitor ne porte cet ID, et non que c’est interdit.

Les outils à l’échelle de l’organisation, get_organization_summary, list_status_pages, create_project et create_monitor, restent réservés aux clés à l’échelle de l’organisation. Les deux outils de création permettraient sinon à une clé restreinte d’écrire dans des projets dont elle ignore tout.

Erreurs

Les outils de liste renvoient total_matching et truncated à côté des lignes : une réponse tronquée se reconnaît comme telle au lieu de ressembler à un résultat complet.

Un échec à l’intérieur d’un outil revient comme un résultat marqué en erreur, avec un motif en clair : le modèle voit ce qui a raté et peut essayer autre chose. Les erreurs de protocole sont réservées aux requêtes malformées.

Pour aller plus loin

• API : l’API REST complète avec des clés API.
• Webhook signé : envoyer les incidents vers vos propres outils.