MCP-Tool-Annotationen und Genehmigungsgrenzen

MCP-Tool-Annotationen sind nützliche Dokumentation. Sie können aber auch dazu führen, dass ein unsicheres Genehmigungssystem ordentlich und vertrauenswürdig wirkt. Wenn ein Client readOnlyHint, destructiveHint oder idempotentHint als Autorisierung behandelt, hat der Serverautor praktisch die Genehmigungsrichtlinie des Nutzers festgelegt, ohne nachzuweisen, dass die Implementierung sie verdient.

Das ist der falsche Ansatz. Eine Annotation kann dabei helfen, einen Hinweis zu erklären, eine Tool-Liste zu sortieren oder einem Menschen, der eine Aktion prüft, einen sinnvollen Standard vorzuschlagen. Die Genehmigung muss sich nach der Anfrage richten, die der Server ausführt, nach den Zugangsdaten, die er verwendet, nach dem Ziel, das er erreicht, und nach den Nebenwirkungen, die er auslösen kann. Ich habe zu viele Integrationen gesehen, die einen Endpunkt namens get aufrufen, ein höfliches JSON-Objekt zurückgeben und trotzdem an anderer Stelle Arbeit anlegen.

Der Unterschied ist bei Agenten besonders wichtig, weil sie Aufrufe wiederholen, Tools kombinieren und in einem Tempo handeln, bei dem ein kleiner Klassifizierungsfehler teuer wird. Ein Tool, das einmal sicher ist, kann in einer Schleife unsicher werden. Ein Tool, das gegenüber einer API schreibgeschützt ist, kann gegenüber einer anderen als Exportmechanismus dienen. Ein Tool, das idempotent wirkt, kann doppelte Arbeit anlegen, wenn ein Timeout den ersten Erfolg verdeckt.

Die Annotationen beschreiben Verhalten, sie verleihen keine Autorität

Die Tool-Spezifikation des Model Context Protocol beschreibt Annotationen als Hinweise auf das Verhalten eines Tools. Diese Formulierung ist bewusst gewählt: Ein Client kann sie nutzen, um seine Oberfläche zu verbessern, aber er kann eine nicht verifizierte Erklärung nicht sicher als Sicherheitsentscheidung verwenden.

Die drei betroffenen Felder beschreiben unterschiedliche Behauptungen:

• readOnlyHint: true behauptet, dass das Tool seine Umgebung nicht verändert.
• destructiveHint: true behauptet, dass das Tool destruktive Aktualisierungen ausführen kann.
• idempotentHint: true behauptet, dass wiederholte Aufrufe mit denselben Argumenten keine zusätzliche Wirkung auf die Umgebung haben.

Diese Behauptungen decken nicht das gesamte Risiko eines Aufrufs ab. Ein Tool kann eine komplette Kundendatenbank lesen, das Ergebnis an den Agenten senden und sich zu Recht als schreibgeschützt kennzeichnen. Ein anderes Tool schreibt vielleicht nur einen Zugriffszeitpunkt. Das klingt unbedeutend, bis sich dadurch Aufbewahrung, Abrechnung oder ein Vorfallseintrag ändern. Idempotenz sagt nichts darüber aus, ob die erste Wirkung akzeptabel war.

Die Spezifikation verwendet für die Felder außerdem konservative Standardwerte. readOnlyHint steht standardmäßig auf false. idempotentHint steht standardmäßig auf false. destructiveHint steht standardmäßig auf true und hat nur dann eine sinnvolle Bedeutung, wenn das Tool nicht schreibgeschützt ist. Ersetze diese Standardwerte nicht durch eine selbst gebaute Regel wie „Fehlende Metadaten sind wohl sicher genug“. Fehlende Metadaten bedeuten oft, dass der Serverautor die Klassifizierung nicht ausreichend durchdacht hat.

Es gibt noch einen unangenehmen Punkt: Auch ein gutartiger Server kann falsch liegen. Ein Entwickler setzt readOnlyHint: true, weil der Handler ein SELECT ausführt. Danach aktualisiert eine Bibliothek ein Token, schreibt einen Cache-Eintrag oder ruft einen Request-Hook auf. Die Annotation bleibt wahr, obwohl sich das Verhalten längst geändert hat. Niemand wollte den Client täuschen, aber der Client traf trotzdem eine schlechte Entscheidung, wenn er die Aktion automatisch genehmigte.

Ein Lesevorgang bedeutet kein harmloses Ergebnis

Eine schreibgeschützte Operation kann Daten offenlegen, eine knappe Ressource verbrauchen oder Verhalten in einem entfernten Dienst aktivieren. „Schreibt nicht“ mit „braucht keine Genehmigung“ gleichzusetzen, verwechselt zwei verschiedene Risikokategorien.

Stell dir ein Tool namens get_build_log vor, das eine Job-ID akzeptiert. Der Server liest aus seinem Build-System und gibt die Ausgabe zurück. Er kann readOnlyHint: true korrekt angeben. Das Protokoll kann jedoch Quellcode, Umgebungsdetails, signierte Download-URLs oder Zugangsdaten enthalten, die ein anderes System versehentlich ausgegeben hat. Wenn diese Antwort an einen autonomen Agenten zurückgeht, ändert sich, wer die Informationen nutzen kann, auch wenn die Datenbank des Build-Systems unangetastet bleibt.

Dasselbe Problem tritt bei Verwaltungs-APIs auf. get_user kann Wiederherstellungscodes zurückgeben. list_invoices kann Bankdaten offenlegen. search_documents kann zur Massengewinnung von Daten werden, wenn ein Agent die Seitengröße erhöht oder jedes Präfix durchläuft. Die Nebenwirkung ist eine Offenlegung, und für deren Sensibilität gibt es in der Annotation kein eigenes Feld.

Auch Leseoperationen können den entfernten Dienst verändern. Manche APIs aktualisieren last_accessed_at, verbrauchen ein einmaliges Download-Token, registrieren eine Vorschau oder stellen eine kostenpflichtige Abfrage in Rechnung. Ein Cache-Miss kann einen teuren nachgelagerten Dienst aufwärmen. Diese Effekte machen nicht jeden Lesevorgang gefährlich, aber sie machen eine pauschale Genehmigungsregel für schreibgeschützte Aufrufe unvertretbar.

Klassifiziere den Aufruf entlang zweier getrennter Achsen: Verändert er ein System, und was kann er außerhalb dieses Systems offenlegen oder auslösen? Eine Statusabfrage mit geringem Risiko und ein Massenexport können beide nicht verändernd sein. Sie sollten trotzdem nicht gleich genehmigt werden.

Ein praxistauglicher Prüfvermerk sollte die Datengrenze in einfachen Worten benennen. „Liest den Bereitstellungsstatus für Projekt A“ lässt sich prüfen. „Ruft get_status auf“ reicht nicht. Die zweite Formulierung verbirgt Ziel, Umfang, Konto und die Tatsache, dass eine ähnlich benannte Methode auf einem anderen Server etwas anderes bedeuten kann.

Den Handler gegen ein entbehrliches Ziel testen

Die Sicherheit einer Annotation lässt sich nicht anhand eines Tool-Namens oder eines Eingabeschemas feststellen. Führe den Server dort aus, wo du seine Anfrage, seine Antwort und den Zustand vor und nach dem Aufruf beobachten kannst.

Beginne mit einem Testkonto, das Datensätze enthält, deren Verlust verkraftbar ist. Gib ihm eigene API-Zugangsdaten und leite Benachrichtigungs-Webhooks an einen Endpunkt zur Aufzeichnung weiter. Protokolliere die ausgehenden Serveranfragen, den Datenbankzustand, falls du ihn kontrollierst, Audit-Ereignisse, E-Mails, Warteschlangenaufträge sowie Abrechnungs- und Nutzungszähler. Der Antworttext ist ein Beleg, aber nicht die vollständige Aufzeichnung.

Verwende für jedes Tool, das Genehmigungen beeinflussen könnte, eine kleine Testmatrix:

1. Rufe es einmal mit gewöhnlichen gültigen Eingaben auf und speichere den vollständigen Zustand davor und danach.
2. Rufe es erneut mit bytegenau identischen Eingaben auf und vergleiche jede beobachtbare Wirkung.
3. Rufe es mit einer fehlenden Ressource, einer bereits abgeschlossenen Operation und einem ungültigen Feld auf.
4. Unterbrich den Client, nachdem der Server die Anfrage erhalten hat, und wiederhole anschließend denselben Aufruf.
5. Führe zwei identische Aufrufe gleichzeitig aus, wenn Agenten sie parallel auslösen können.

Der Timeout-Fall deckt einen häufigen Fehler auf. Angenommen, create_ticket sendet die Anfrage für ein Ticket, dann bricht die Verbindung ab, bevor der Server antwortet. Der Agent sieht einen Fehler und versucht es erneut. Wenn das Ticketsystem kein Idempotenz-Token besitzt, erstellt das Tool zwei Tickets. Den Handler als idempotent zu markieren, weil sein Code dieselbe Eingabe zweimal akzeptiert, ändert nichts am Ergebnis beim entfernten Dienst.

Halte das Ergebnis in einer Form fest, die Menschen zwingt, Wirkungen zu prüfen, statt einer erfolgreichen Antwort zu vertrauen:

case: retry after response timeout
request: {\"title\":\"rotate staging certificate\",\"request_id\":\"test-104\"}
first call: transport timeout after request received
second call: 201 {\"ticket\":\"842\"}
remote records: [\"841\", \"842\"]
result: not idempotent without a remote idempotency mechanism

Die request_id in diesem Beispiel hilft nur, wenn die entfernte API sie speichert und durchsetzt. Eine vom Client erzeugte Kennung, die der Server ignoriert, ist reine Dekoration. Teste diese Durchsetzung, indem du dieselbe Kennung erneut verwendest und prüfst, ob das entfernte System die ursprüngliche Operation zurückgibt, statt eine weitere anzulegen.

Bewahre die Tests zusammen mit dem Server auf. Abweichungen zwischen Annotation und Verhalten kommen meist mit einer Codeänderung, einem Update einer Abhängigkeit oder einem neuen Endpunkt. Ein bestandener Test, der den angegebenen Hinweis mit dem beobachtbaren Verhalten vergleicht, ist wertvoller als ein Kommentar neben der Tool-Definition.

Behauptungen zu Schreibschutz scheitern an den Grenzen

Der einfachste falsche readOnlyHint entsteht, wenn man nur die Hauptabfrage an die Datenbank betrachtet. Die relevante Grenze umfasst jeden vom Handler aufgerufenen Dienst und jede durch seine Antwort ausgelöste Aktion.

Nimm ein Server-Tool, das ein Dokument abruft. Seine primäre Anfrage lautet GET /documents/42, aber der Handler kann zuvor ein Refresh-Token austauschen, eine temporäre Download-URL ausstellen, einen lokalen Cache aktualisieren und ein Zugriffsereignis schreiben. Jede Operation kann auf andere Weise fehlschlagen. Für jede können andere Zugangsdaten und Audit-Anforderungen gelten.

Akzeptiere nicht das Argument, dass eine Änderung zu klein sei, um zu zählen. Kleine Schreibvorgänge bringen eigene Fehlerquellen mit sich. Eine Markierung für den letzten Zugriff kann die Aufbewahrung beeinflussen. Ein Cache kann Inhalte bewahren, obwohl der Zugriff bereits enden sollte. Ein Zugriffsereignis kann den Eigentümer benachrichtigen. Ein Nutzungszähler kann ein Konto in eine kostenpflichtige Stufe verschieben. Frage, ob die Änderung eine Tatsache verändert, die eine andere Person, ein Prozess oder eine Rechnung bemerken wird. Wenn ja, dokumentiere sie.

Auch durch Antworten ausgelöstes Verhalten verdient dieselbe Prüfung. Ein Tool, das einen signierten Link zurückgibt, kann den Agenten dazu bringen, ihn später abzurufen. Ein Tool, das einen ausführbaren Befehl zurückgibt, kann dazu führen, dass ein Agent ihn über einen anderen Kanal ausführt. Das erste Tool bleibt in einem engen Sinn schreibgeschützt, aber ein Genehmigungsbildschirm mit „sicherer Lesevorgang“ vermittelt dem Menschen ein falsches Bild von der nächsten Aktion, die der Agent ausführen kann.

Ein guter Server trennt Operationen, wenn sich ihre Risiken unterscheiden. get_document_metadata kann ein eng begrenzter Prüfaufruf bleiben. create_download_link sollte ein eigenes Tool sein, weil es eine Bearer-Fähigkeit erzeugt, auch wenn sich die zugrunde liegenden Dokumentbytes nicht ändern. Diese Trennung hilft Agenten bei der richtigen Auswahl und gibt Prüfern eine Aussage, die sie tatsächlich genehmigen können.

Destruktiv bedeutet Reversibilität, nicht eine Liste von Verben

destructiveHint sollte ausdrücken, ob ein Aufruf schädliche Änderungen verursachen kann, die sich nur schwer rückgängig machen lassen, und nicht, ob der Tool-Name delete enthält. Teams liegen dabei in beide Richtungen falsch.

Manche offensichtlichen Verben sind in einem System reversibel und in einem anderen endgültig. archive kann einen Datensatz lediglich ausblenden oder einen Lösch-Timer starten. disable_user kann alle Berechtigungen und Dateien erhalten oder den Zugriff so entziehen, dass ein automatisierter Prozess blockiert wird. replace_config kann einen Entwurf aktualisieren oder sofort ein Produktions-Deployment auslösen. Der Handler braucht Informationen zum konkreten Ziel, die ein einzelner boolescher Wert nicht ausdrücken kann.

Manche Tools mit harmlosen Namen sind eindeutig destruktiv. sync_members kann Konten entfernen, die in der übermittelten Liste fehlen. apply_labels kann eine sorgfältig gepflegte Taxonomie überschreiben. reconcile kann ein externes Hauptbuch mit Buchungen korrigieren, die niemand leichtfertig anlegen sollte. Ein Serverautor, der diese Tools als nicht destruktiv markiert, weil die API sie technisch rückgängig machen kann, verschleiert den betrieblichen Aufwand der Reparatur.

Behandle Reversibilität als Ablauf, nicht als Kontrollkästchen. Frage, wer das Ergebnis rückgängig machen kann, welche Nachweise dafür nötig sind, wie lange das Rückgängigmachen möglich bleibt und ob ein späterer Prozess die Änderung verarbeitet, bevor jemand sie umkehren kann. Wenn ein Mensch nach einer Massenänderung die Absicht aus Protokollen rekonstruieren muss, verdient die Aktion eine destruktive Klassifizierung, selbst wenn die API eine Gegenoperation anbietet.

Die verbreitete schlechte Empfehlung lautet, Genehmigungen nur für ausdrückliche Löschungen zu verlangen. Sie ist beliebt, weil Agenten dadurch weiterarbeiten und eine Demo reibungslos wirkt. In der Produktion scheitert sie, weil destruktive Änderungen meist als Ersetzungen, Widerrufe, Sendungen oder Abgleiche auftreten. Genehmige die relevante Zustandsänderung, nicht das Vokabular, mit dem sie beschrieben wird.

Bei einer Aktion, die eine Sammlung betrifft, sollte der Prüfvermerk die Auswahlregel und die Anzahl enthalten. „Benutzer synchronisieren“ ist zu vage. „14 inaktive Auftragnehmer entfernen, ausgewählt anhand der übermittelten IDs“ ermöglicht eine Einschätzung des Umfangs. Wenn der Server diesen Umfang vor der Ausführung nicht melden kann, liefert er dem Client nicht genug Informationen für eine ernsthafte Genehmigungsabfrage.

Idempotenz muss Wiederholungen und Parallelität überstehen

idempotentHint ist eine eng begrenzte Behauptung: Identische Argumente sollten nach dem ersten Aufruf keine zusätzliche Wirkung haben. Das bedeutet weder, dass ein Aufruf sicher, günstig oder reversibel ist, noch dass ein Agent ihn endlos wiederholen sollte.

Eine Statusaktualisierung kann idempotent sein, wenn das zweimalige Setzen von state=closed denselben geschlossenen Datensatz hinterlässt. Der Handler ist jedoch nicht mehr idempotent, wenn er jedes Mal eine E-Mail sendet, einen Audit-Kommentar anhängt oder einen Versionszähler erhöht. Menschen prüfen oft die Datenbankzeile und übersehen die sekundären Wirkungen, die Nutzer zuerst bemerken.

Auch die Gleichheit von Eingaben braucht eine genaue Definition. Die Reihenfolge von JSON-Objekteigenschaften sollte keine Rolle spielen. Ein Server, der ein fehlendes note anders behandelt als note: \"\", kann eine Anfrage erhalten, die der Agent für identisch hält, aber zwei unterschiedliche Änderungen ausführen. Zeitangaben, generierte Standardwerte und relative Ausdrücke wie tomorrow schwächen die Behauptung, weil sie den tatsächlichen Befehl verändern, während die sichtbaren Argumente stabil wirken.

Bei parallelen Aufrufen bricht eine beiläufig angenommene Idempotenz besonders leicht zusammen. Zwei Worker-Prozesse können beide prüfen, dass ein Objekt nicht existiert, und es dann beide anlegen. Eine Eindeutigkeitsbedingung, ein transaktionales Upsert oder eine Idempotenzfunktion des entfernten Dienstes kann das verhindern. Ein Speicher-Cache in einem einzelnen MCP-Server-Prozess schützt keine Bereitstellung, die mit mehreren Prozessen läuft.

Verwende einen Idempotenzdatensatz erst, nachdem du seinen Geltungsbereich festgelegt hast. Speichere ein vom Aufrufer geliefertes Token zusammen mit der authentifizierten Identität, dem normalisierten Anfragekörper, dem Ergebnis und einem für die Operation passenden Ablaufzeitpunkt. Lehne die erneute Verwendung eines Tokens mit einer anderen normalisierten Eingabe ab. Andernfalls kann ein Agent versehentlich ein altes Token an eine neue Anfrage hängen und das Ergebnis einer anderen Aktion erhalten.

Führe nicht automatisch Wiederholungen aus, nur weil der Hinweis true lautet. Wiederhole nur Fehler, bei denen du weißt, ob der Server den Aufruf erhalten hat. Wenn du das nicht wissen kannst, ist eine Idempotenzfunktion an der tatsächlichen Änderungsstelle die Lösung. Der clientseitige Hinweis ist es nicht.

Genehmigungen aus der ausgeführten Aktion ableiten

Ein Genehmigungssystem sollte beantworten: Welcher Prozess stellt die Anfrage, welche Zugangsdaten werden verwendet, welches externe Ziel erhält die Anfrage, welche Daten oder welcher Zustand ist betroffen und was passiert bei Erfolg? Tool-Annotationen können diese Erklärung kürzer machen. Sie können keine Fakten liefern, die der Server nicht offengelegt hat.

Halte die Genehmigung einer Sitzung und die Genehmigung einzelner Aufrufe getrennt. Eine Sitzungsgenehmigung passt zu einem bekannten Agent-Prozess, der einen begrenzten Lauf mit gewöhnlichen Berechtigungen ausführt. Eine Genehmigung pro Aufruf passt zu Zugangsdaten, mit denen Geld übertragen, Produktionszugriff geändert, Nachrichten versendet, sensible Datensätze offengelegt oder irreversible externe Verpflichtungen eingegangen werden können. Die Entscheidung gehört zu den Zugangsdaten und zum Kontext der Aktion, nicht zu einem optimistischen readOnlyHint.

Eine hilfreiche Abfrage benennt die konkrete Operation: „Ein von dieser Autorität signierter Agent verwendet die Deployment-Zugangsdaten, um Dienst X in Konto Y neu zu starten.“ Eine schwache Abfrage lautet: „Tool deploy erlauben?“ Die erste Formulierung gibt dem Prüfer etwas, das er bewerten kann. Die zweite fordert ihn auf, einem Implementierungsdetail zu vertrauen.

Sallyport setzt diese Trennung um, indem es API- und SSH-Zugangsdaten in seinem verschlüsselten Tresor aufbewahrt, die HTTP- oder SSH-Aktion selbst ausführt und dem Agenten das Ergebnis statt der Zugangsdaten zurückgibt. Die Sitzungsautorisierung identifiziert den anfragenden Prozess, während eine Einstellung pro Zugangsdaten-Secret für jede Nutzung eine Entscheidung verlangen kann. Das ist ein besserer Ort für menschliche Kontrolle als ein vom Server bereitgestellter boolescher Wert.

Auch mit einem Gate vor den Zugangsdaten solltest du ein Aktivitätsprotokoll führen, das das endgültige Anfrageziel und das Ergebnis erfasst. Eine Genehmigung beantwortet, ob die Aktion ausgeführt werden darf. Ein Audit-Eintrag beantwortet, was bei der Ausführung passiert ist. Vermische diese Fragen nicht in einem vagen Ereignis namens „Tool verwendet“.

Annotationen als Teil der Serverpflege prüfen

MCP-Tool-Annotationen sollten für eine ehrliche Kommunikation dienen, die durch Tests abgesichert ist. Ein Serverautor sollte sie konservativ setzen, Grenzfälle dokumentieren und sie ändern, sobald sich das Verhalten ändert. Ein Clientautor sollte sie als einen Bestandteil des Oberflächendesigns nutzen, niemals als alleinige Grundlage für Berechtigungen.

Füge Tests hinzu, die eine behauptete Eigenschaft absichtlich widerlegen. Bei einer Schreibschutzdeklaration sollte der Test fehlschlagen, sobald die Testumgebung eine Schreiboperation, eine ausgehende Benachrichtigung, eine Aktualisierung von Zugangsdaten oder eine für später erzeugte Fähigkeit feststellt. Bei einer destruktiven Deklaration solltest du den Fehler- und den Rückgängig-Pfad testen, einschließlich des Verhaltens, nachdem ein nachgelagerter Auftrag die Änderung verarbeitet hat. Für Idempotenz solltest du dieselbe normalisierte Anfrage nach einem simulierten Timeout und mit parallelen Aufrufern ausführen.

Verstecke eine Abweichung nicht, indem du das Testziel so lange änderst, bis der Test besteht. Begrenze entweder das Tool so, dass der Hinweis zutrifft, ändere die Annotation oder mache die Wirkung in den Genehmigungsdetails sichtbar. Jede dieser Optionen zeigt dem nächsten Maintainer, was der Code tatsächlich tut.

Führe sp audit verify bei der Untersuchung eines Vorfalls aus, wenn Sallyport als Aktions-Gateway dient. Der Befehl prüft die verschlüsselte Hash-Kette offline. So kannst du feststellen, ob die aufgezeichnete Aktionshistorie intakt geblieben ist, ohne den Tresor zu öffnen. Das beweist nicht, dass eine Server-Annotation ehrlich war, liefert dir aber einen manipulationssicheren Nachweis der Aufrufe, die ihr gefolgt sind.

Der praktische Maßstab ist einfach: Eine Annotation sollte einen feindseligen Test gegen die für den Nutzer relevante Wirkung bestehen. Wenn sie das nicht kann, bleibe bei einer konservativen Einstufung und belasse die Genehmigung dort, wo die Aktion ausgeführt wird.