MCP für Agenten

Richten Sie einen MCP-Client auf Perstat, beantwortet er aus Ihren Live-Daten, was ausgefallen ist und wer sich darum kümmert, und handelt innerhalb seiner Berechtigung. Der Katalog umfasst siebzehn Werkzeuge: sieben lesen, zwei handeln an einem Incident, acht verwalten Projekte und Monitore. Welche davon der Zugang vor Ihnen nutzen darf, zeigt tools/list des verbundenen Servers genau an. Jedes Werkzeug lässt Ihre Aufzeichnung unangetastet: Wer einen Dienst außer Betrieb nimmt, archiviert ihn.

Anschluss

Adresse	https://api.perstat.io/mcp
Transport	Streamable HTTP, zustandslos
Protokollfassungen	2025-06-18 (bevorzugt), 2025-03-26, 2024-11-05

Eine JSON-RPC-Nachricht per POST hinein, eine JSON-Antwort heraus. GET /mcp antwortet mit 405, denn der Server arbeitet Anfrage für Anfrage, ohne einen Ereignisstrom von sich aus zu öffnen. Sammelanfragen, die das Protokoll mit 2025-06-18 gestrichen hat, lehnt er mit einem klaren Hinweis ab.

In Claude Code:

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

Diese Form funktioniert in Clients, die einen eigenen HTTP-Autorisierungsheader annehmen. Der Schlüssel landet auf diesem Weg in Ihrer Shell-Historie, für die interaktive Arbeit ist die Browser-Anmeldung des Plugins daher der sauberere Weg.

Oder das Plugin installieren

Für Claude Code gibt es ein Plugin. Es hängt denselben Server ein und bringt vier Skills mit, die aus den Werkzeugen Abläufe machen: einen Incident bearbeiten, Monitore verwalten, die Lage berichten und alle Monitortypen nachschlagen.

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

Beim ersten Perstat-Werkzeugaufruf öffnet Claude die OAuth-Anmeldung im Browser. Wählen Sie die Organisation für die Verbindung, und Sie sind fertig: kein Schlüssel zu kopieren, kein Shell-Profil zu bearbeiten. Die Verbindung ist an diese Organisation und Ihre aktuelle Rolle gebunden. Mit claude mcp list prüfen Sie, dass Perstat Connected meldet.

Den API-Schlüssel-Einzeiler oben verwenden Sie für CI, Cron oder auf bestimmte Projekte begrenzte Zugänge. Das Plugin ist der interaktive Weg mit Browser-Anmeldung.

Anmeldung

Perstat akzeptiert einen mit Scopes begrenzten Organisations-API-Schlüssel als Bearer:

Authorization: Bearer pst_…

OAuth-fähige Clients können stattdessen den veröffentlichten Authorization-Code-Ablauf mit PKCE verwenden. Die Discovery-Dokumente liegen unter https://api.perstat.io/.well-known/oauth-protected-resource/mcp und https://api.perstat.io/.well-known/oauth-authorization-server, und dort stehen auch Refresh- und Widerrufs-Endpunkte. MCP meldet immer mit einem Bearer-Token an: Der OAuth-Ablauf endet in einem, ein Sitzungs-Cookie des Browsers allein genügt also nicht.

OAuth-Clients werden von Claude, Claude Code und ChatGPT angenommen, erkannt an ihren Client-Dokumenten unter https://claude.ai/oauth/ und https://chatgpt.com/oauth/. Der Zustimmungsbildschirm nennt den Host, von dem der Client kommt, zusätzlich zu dem Namen, den er sich selbst gibt, und ein Client erhält genau die Rechte, die seine Werkzeuge brauchen: monitors und incidents, jeweils lesend oder schreibend.

Ein Organisationsschlüssel hängt an genau einer Organisation und trägt Scopes. Dadurch kann er nie mehr, als im Schlüssel steht.

Schlüssel legen Eigentümer und Administratoren in der App unter Integrationen, dann API-Schlüssel an.

Die Werkzeuge

tools/list zeigt, was die aktuelle Berechtigung erlaubt. tools/call prüft denselben Scope noch einmal, denn eine Liste ist keine Absicherung.

Der Katalog umfasst siebzehn Werkzeuge. Browser-OAuth vergibt die Monitor- und Incident-Scopes, und ein API-Schlüssel mit status-pages:read ergänzt list_status_pages. Maßgeblich für den konkreten Zugang ist die Antwort des verbundenen Servers auf tools/list.

Werkzeug	Scope	Wirkung
get_organization_summary	monitors:read	Die Lage in einem Aufruf: Dienste je Zustand, offene Incidents
list_projects	monitors:read	Projekte samt Monitor-Zahl. Der Einstieg für create_monitor
list_monitors	monitors:read	Dienste mit zuletzt bestätigtem Zustand, filterbar. Mit archived: true das Archiv
get_monitor	monitors:read	Ein Dienst mit Konfiguration, Regionen und jüngsten Incidents. Werte eigener Request-Header kommen als [redacted] zurück
list_incidents	incidents:read	Offene und geschlossene Incidents, neueste zuerst
get_incident	incidents:read	Ein Incident im Detail
acknowledge_incident	incidents:write	Incident quittieren, das stoppt Alarm und Eskalation
resolve_incident	incidents:write	Einen offenen Incident von Hand schließen
list_status_pages	status-pages:read	Die Statusseiten der Organisation
create_project	monitors:write	Den Ordner anlegen, in dem Monitore liegen. Nur mit org-weiten Schlüsseln
create_monitor	monitors:write	Einen neuen Dienst überwachen. Nur mit org-weiten Schlüsseln
update_monitor	monitors:write	Name, Einstellungen, Prüfabstand oder Regionen ändern
set_monitor_enabled	monitors:write	Einen Monitor pausieren oder wieder in Betrieb nehmen
archive_monitor	monitors:write	Einen Dienst außer Betrieb nehmen und seinen Platz im Tarif freigeben
restore_monitor	monitors:write	Einen archivierten Dienst zurückholen. Er kommt pausiert zurück und braucht einen freien Platz im Tarif
get_heartbeat_endpoint	monitors:write	Die geheime Ping-URL eines Heartbeats, um seinen Job zu verdrahten. Jeder Abruf steht im Aktivitätsprotokoll
rotate_heartbeat_endpoint	monitors:write	Eine neue Ping-URL für einen Heartbeat ausgeben. Die alte hört sofort auf zu funktionieren

write schließt read derselben Ressource ein, nie über Ressourcen hinweg.

create_monitor und update_monitor nehmen jeden Prüfabstand vom Minimum Ihres Tarifs bis zu 24 Stunden an, also auch 15 s bei Command und 10 s bei Enterprise. Werte unter dem Minimum hebt Perstat auf das Minimum an.

Alles, was der Agent zu sehen bekommt, ist englisch: Werkzeugnamen, Beschreibungen, Schema-Texte und Fehlergründe. Das Aktivitätsprotokoll in der Anwendung bleibt in Ihrer Sprache, denn das lesen Menschen.

create_project und create_monitor sind die beiden Werkzeuge, die nicht idempotent sind, und melden das dem Client. Ein wiederholter Aufruf kann eine zweite Ressource anlegen oder am Namen scheitern. Sehen Sie vorher mit list_projects oder list_monitors nach.

Werkzeuge, die bestehenden Zustand ändern oder beenden (acknowledge_incident, resolve_incident, update_monitor, set_monitor_enabled, archive_monitor, rotate_heartbeat_endpoint), sind als destruktiv gekennzeichnet, damit ein Client vor dem Aufruf nachfragen kann. Anlegen und Wiederherstellen fügen nur hinzu.

Eigene Request-Header eines Monitors sind Zugangsdaten und werden über einen Schlüssel oder einen Agenten nie zurückgelesen: get_monitor zeigt ihre Namen mit dem Wert [redacted]. Schicken Sie eine Konfiguration mit dem Platzhalter über update_monitor zurück, bleibt der gespeicherte Wert erhalten, solange URL und Methode exakt gleich bleiben. Nach jeder Änderung an einer von beiden wird der Platzhalter abgewiesen, damit ein Zugangsdatum nie einer Anfrage folgt, die sein Urheber nicht eingerichtet hat. Angemeldete Mitglieder sehen die Werte in der Web-App weiterhin.

Auch die Ping-URL eines Heartbeats ist ein Zugangsdatum: Wer sie hat, kann für den Job Erfolg melden und damit einen Ausfall grün halten. Ein Agent braucht sie trotzdem, um die Einrichtung abzuschließen. Deshalb gibt create_monitor sie für einen neuen Heartbeat zurück, und get_heartbeat_endpoint liefert sie später erneut. Beide verlangen monitors:write und eine Person hinter dem Schlüssel, die Monitore noch verwalten darf, und jede Herausgabe steht im Aktivitätsprotokoll. get_heartbeat_endpoint trägt keine Kennzeichnung als nur lesend, damit ein Client nachfragt, bevor er ein Zugangsdatum abruft. Die URL steht danach im Verlauf des Agenten. Vertrauen Sie diesem Verlauf nicht, erneuern Sie die URL nach der Einrichtung in der Web-App, denn rotate_heartbeat_endpoint schriebe die neue in denselben Verlauf.

MCP archiviert und erhält die Aufzeichnung

Ein Agent nimmt einen Dienst außer Betrieb, indem er ihn archiviert, und die Historie bleibt dabei an ihrem Platz.

Mit archive_monitor nehmen Sie einen Dienst außer Betrieb und erhalten seine Incidents, Prüfhistorie, SLA-Rollups und Ausschlussfenster. Dieselbe Operation steht über die REST-API als POST /monitors/{monitor_id}/archive bereit. Zurück führt POST /monitors/{monitor_id}/restore. Archivieren schließt offene Incidents, beendet Eskalationen und schließt ihre externen Konnektor-Alarme. Endgültiges Löschen per API-Schlüssel ist seit dem 2. Oktober 2026 abgekündigt, mit Umstellung frühestens am 1. Januar 2027 um 00:00 UTC. Erfolgreiche DELETE-Antworten verlinken die Ankündigung.

archive_monitor stoppt die Prüfungen, nimmt den Dienst aus den aktiven Listen und gibt seinen Platz im Tarif frei, während die Ressource wiederherstellbar bleibt. Die Historie bleibt und folgt den normalen objektbezogenen Aufbewahrungsregeln. restore_monitor holt den Dienst pausiert zurück und belegt wieder einen Platz im Tarif: Ist der Tarif voll, wird das Zurückholen mit demselben Hinweis abgelehnt wie create_monitor, bis ein anderer Monitor archiviert oder der Tarif gewechselt ist. Der Name wird beim Archivieren frei, ein neuer Monitor kann ihn also tragen.

Für Ihr Kontingent zählt der Unterschied: Archivieren gibt den Platz frei, Pausieren behält ihn, denn ein pausierter Monitor ist weiter da und weiter gemeint.

Der Weg zurück ist immer sichtbar. list_monitors mit archived: true zeigt das Archiv, und get_monitor findet Archivierte ebenfalls, damit Sie vor dem Zurückholen nachsehen können, auch ohne die ID zur Hand. Um einen archivierten Monitor zu ändern oder anzuschalten, holen Sie ihn zuerst zurück: update_monitor und set_monitor_enabled antworten mit “is archived, call restore_monitor first” und sagen dem Agenten damit genau, was als Nächstes zu tun ist.

Schreibende MCP-Aufrufe konzentrieren sich auf Monitoring und Incidents. Statusseiten, Webhooks und Mitglieder verwalten Sie mit einem API-Schlüssel über die REST-API, API-Schlüssel und Abrechnung in der App. list_status_pages liest Statusseiten für API-Schlüssel mit status-pages:read.

Jede Handlung trägt einen Namen

Eine Handlung über MCP wird der menschlichen Identität des Zugangs zugeschrieben: dem Ersteller des API-Schlüssels oder dem OAuth-Subjekt. So hat die Quittung während eines Incidents einen Namen und ist nicht bloß ein Token. Im Verlauf des Incidents steht zusätzlich, dass sie über MCP kam. Monitore, die ein Agent anlegt oder ändert, erscheinen genauso im Aktivitätsprotokoll Ihrer Organisation, unter dem Namen dieser Identität.

Weil diese Identität für die Zuschreibung geborgt wird, entscheidet sie auch über die Berechtigung. Bei jedem einzelnen schreibenden Aufruf prüft der Server neu, dass die Identität noch Mitglied der Organisation ist und noch die Rolle trägt, die zur Handlung gehört. Die Schwelle entspricht der in der Anwendung: Incidents bearbeiten darf, wer reagieren darf, bis hinunter zum Responder. Monitore verwalten darf, wer Projekte verwalten darf, also Owner, Admin oder Developer. Wird diese Identität herabgestuft oder entfernt, schreibt ihr Zugang ab dem nächsten Aufruf nicht mehr. Lesen geht weiter und hängt an den Scopes des Zugangs. Ist das Konto dieser Person gelöscht, verweigert der Server das Schreiben ebenfalls und sagt, warum.

Verengte Schlüssel

Ein auf bestimmte Projekte oder Monitore verengter Schlüssel sieht in list_monitors und list_incidents seine eigenen Ressourcen. Alles andere ist für ihn unsichtbar, und er kann auch nicht herausfinden, ob es existiert. Beim Schreiben gilt dasselbe: update_monitor und set_monitor_enabled melden für einen fremden Monitor, dass es keinen Monitor mit dieser ID gibt, und nicht, dass es verboten wäre.

Org-weite Werkzeuge, get_organization_summary, list_status_pages, create_project und create_monitor, bleiben org-weiten Schlüsseln vorbehalten. Die beiden anlegenden Werkzeuge könnten sonst in Projekte schreiben, von denen ein verengter Schlüssel nichts weiß.

Fehler

Die Listen-Werkzeuge melden neben den Zeilen total_matching und truncated. Eine gekürzte Antwort ist damit als solche erkennbar, statt wie ein vollständiges Ergebnis auszusehen.

Ein Fehlschlag innerhalb eines Werkzeugs kommt als Ergebnis zurück, das als Fehler markiert ist und einen Grund im Klartext trägt. So sieht das Modell, was schiefging, und kann es anders versuchen. Protokollfehler bleiben Formfehlern in der Anfrage vorbehalten.

Nächste Schritte

• API: die vollständige REST-API mit API-Schlüsseln.
• Signierter Webhook: Incidents an Ihre eigenen Werkzeuge schicken.