6 Min. Lesezeit

MCP-Toolbeschreibungen, die Produktionsfehler verhindern

MCP-Toolbeschreibungen verhindern versehentliche Produktionsaktionen, wenn sie Ziel, Nebeneffekt und erforderliche Genehmigung in einfacher Sprache nennen.

MCP-Toolbeschreibungen, die Produktionsfehler verhindern

Eine MCP-Toolbeschreibung kann einen unsicheren Produktionsaufruf stoppen, bevor er beginnt, oder die Gefahr hinter einem freundlichen Verb verstecken. Die meisten versehentlichen Produktionsaktionen beginnen nicht damit, dass ein Agent bewusst Schaden anrichten will. Sie beginnen damit, dass eine vage Beschreibung ein destruktives Tool wie ein austauschbares Prüf-Tool aussehen lässt.

Formuliere die Beschreibung jedes zustandsverändernden Tools als kleinen operativen Vertrag: Nenne das Zielsystem, den Nebeneffekt und die erforderliche Genehmigung. Fehlt eine dieser Angaben, muss das Modell eine Sicherheitsgrenze ableiten, die dein Code ausdrücklich festlegen sollte.

Ich habe genug Aktionsschnittstellen geprüft, um Bezeichnungen wie „verwalten“, „synchronisieren“, „deployen“ und „aufräumen“ zu misstrauen. Für den Autor sind sie bequem, für die Person, die erklären muss, warum eine Testanfrage in einem Live-Konto gelandet ist, sind sie teuer. Eine gute Beschreibung macht die unangenehmen Details unübersehbar.

Eine Toolbeschreibung ist eine Ausführungswarnung, kein Produkttext

MCP-Toolbeschreibungen sollten einem Agenten und seinem menschlichen Bediener sagen, was nach einem erfolgreichen Aufruf passiert. Sie sollten die Fähigkeit nicht anpreisen, kein internes Subsystem zusammenfassen und den Toolnamen nicht in einem längeren Satz wiederholen.

Das Tool-Schema des Model Context Protocol enthält neben dem Toolnamen und inputSchema eine für Menschen lesbare description. Die MCP-Spezifikation erlaubt außerdem Tool-Annotationen wie readOnlyHint und destructiveHint. Diese Annotationen helfen einem Client bei der Darstellung von Tools, aber laut Spezifikation müssen Clients sie als Hinweise behandeln. Sie sind keine Berechtigungsprüfungen. Deshalb bleibt die Beschreibung der Ort, an dem der Bediener die tatsächliche Folge lesen kann, bevor der Aufruf deinen Dienst erreicht.

Betrachte diese beiden Definitionen:

{
  "name": "delete_backup",
  "description": "Deletes a backup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": { "type": "string" }
    },
    "required": ["backup_id"]
  }
}
{
  "name": "delete_production_backup",
  "description": "Permanently deletes one backup from the Production PostgreSQL backup store. This removes a recovery point and cannot be undone. Ask the user to confirm the backup ID and its timestamp before calling this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": {
        "type": "string",
        "description": "Immutable backup ID returned by list_production_backups."
      }
    },
    "required": ["backup_id"],
    "additionalProperties": false
  },
  "annotations": {
    "destructiveHint": true,
    "readOnlyHint": false
  }
}

Die zweite Definition klingt nicht nur vorsichtiger. Sie nennt ein Ziel, ein irreversibles Ergebnis, eine sichere Möglichkeit zur Identifizierung des Objekts und eine erforderliche Gesprächspause. Außerdem liefert sie einem Prüfer genug Informationen, um einen Aufruf abzulehnen, bevor er Implementierungsdetails untersucht.

Verlass dich dabei nicht auf ein kräftiges Verb. „Zerstören“ warnt besser als „löschen“, sagt aber immer noch nichts darüber, welches Konto oder welche Datenklasse betroffen ist und wie das Tool mit Genehmigungen umgeht. Diese Informationen gehören in die Beschreibung.

Setze das Zielsystem in den ersten Satz

Der erste Satz sollte das genau betroffene System einschließlich Umgebung oder Kontogrenze nennen. Eine Aktion gegen „die Datenbank“ kann einen wegwerfbaren lokalen Container, einen gemeinsam genutzten Testdienst, einen Staging-Mandanten oder das Kundenbuch der Produktion meinen. Das sind unterschiedliche Aktionen, selbst wenn der API-Endpunkt zufällig identisch ist.

Verwende Bezeichnungen, die ein Bediener aus seiner eigenen Arbeit kennt. Schreibe „Produktions-Zahlungskonto“, „Staging-Kubernetes-Cluster“, „Kundenmandant northwind“ oder „Release-Branch des Repositorys mobile-api“. Vermeide interne Spitznamen, außer jeder vorgesehene Bediener kennt sie und der Name erscheint in den Argumenten.

Diese Reihenfolge funktioniert, weil sie das Risiko vor die technischen Einzelheiten stellt:

[Zielsystem]. [Aktion und Ergebnis]. [Genehmigungsregel].

Zum Beispiel:

Produktionsverzeichnis für Identitäten. Deaktiviert das ausgewählte Benutzerkonto und beendet aktive Sitzungen. Bitte den Benutzer vor dem Aufruf um Bestätigung des Benutzernamens.

Das Ziel muss zum Handler passen, nicht zur Absicht des Autors. Wenn das Tool ein environment-Argument akzeptiert, wird eine Beschreibung wie „Aktualisiert Staging“ in dem Moment falsch, in dem ein Aufrufer production übergibt. Teile die Operation entweder in umgebungsspezifische Tools auf oder sage klar, was das Argument erlaubt.

Eine Aufteilung ist meist leichter zu bedienen:

list_staging_feature_flags
set_staging_feature_flag
list_production_feature_flags
request_production_feature_flag_change

Das Design mag repetitiv wirken. Wiederholung ist günstiger, als wenn ein Toolauswähler set_feature_flag für passend hält und erst später feststellt, dass ein optionales Argument auf die Produktion zeigte.

Für Namen gilt dieselbe Disziplin, aber Namen können die gesamte Warnung nicht tragen. Toollisten kürzen Namen. Agenten konzentrieren sich bei ähnlichen Namen manchmal auf die Beschreibung. Menschen überfliegen unter Druck beides. Setze das Ziel, soweit passend, an beide Stellen und mache die Beschreibung vollständig, falls der Name nicht sichtbar ist.

Eine Ausnahme ist ein Tool, das eine unveränderliche Ressourcen-URI erhält, deren Host die Umgebung bereits festlegt. Nenne trotzdem den Host oder die Kontoklasse in der Beschreibung. Eine UUID sagt einem Menschen nicht, ob sie einen Entwicklungsdatensatz oder einen echten Kunden bezeichnet.

Beschreibe den Nebeneffekt als abgeschlossenes Ergebnis

Eine sichere Beschreibung sagt dem Leser, wie die Welt nach einem erfolgreichen Aufruf aussieht. So muss der Autor zwischen einer Beobachtung und einer Änderung, einer umkehrbaren und einer dauerhaften Änderung sowie einer Anfrage und ihrer Ausführung unterscheiden.

Vergleiche das vage Verb „verwalten“:

Verwaltet Service-Deployments.

Es verbirgt mehrere sehr unterschiedliche Ergebnisse. Ein Deployment-Tool kann ein Release erstellen, ein vorhandenes Release aktivieren, Instanzen neu starten, die Verkehrsverteilung ändern, Code zurückrollen oder nur den Status abrufen. Jede Operation verdient ein eigenes Tool, wenn sie ein anderes Fehlerszenario oder eine andere Genehmigungsregel hat.

Verwende stattdessen ein ausdrückliches Ergebnis:

Erstellt eine Deployment-Anfrage für den Produktionskatalogdienst. Laufende Instanzen werden nicht geändert. Ein Release-Manager muss die Anfrage im Deployment-System genehmigen.

Oder:

Ändert den Produktionsverkehr des Katalogdienstes so, dass das angegebene Release 100 Prozent der Anfragen erhält. Bereits laufende Anfragen können auf dem vorherigen Release beendet werden. Bitte den Benutzer vor dem Aufruf um Bestätigung der Release-Version.

Der Unterschied zwischen dem Erstellen einer Anfrage und ihrer Ausführung ist wichtiger als der Unterschied zwischen HTTP POST und PATCH. Auch ein Anfrageobjekt kann Arbeit auslösen, ein Kontingent verbrauchen oder Personen benachrichtigen. Beschreibe diesen Nebeneffekt ebenfalls. Bezeichne es aber nicht als Live-Deployment, wenn es nur einen Genehmigungsvorgang eröffnet.

Vermeide Euphemismen. „Ausmustern“ kann Archivieren, Deaktivieren, Löschen oder das Beenden einer Abrechnung bedeuten. „Aufräumen“ kann temporäre Dateien entfernen oder die einzige aufbewahrte Kopie eines Kundenexports löschen. Schreibe das tatsächliche Verb und Objekt: löschen, deaktivieren, rotieren, aktivieren, übertragen, senden, berechnen oder veröffentlichen.

Bei Vorgängen mit verzögerten Folgen solltest du die Verzögerung nennen. Eine DNS-Änderung kann sich erst nach der Rückgabe der API verbreiten. Das Entfernen eines Benutzers kann den zukünftigen Zugriff stoppen und Audit-Datensätze trotzdem erhalten. Eine Zugangsdatenrotation kann Clients ungültig machen, die weiterhin das alte Secret verwenden. Der Agent braucht diesen Kontext, um zu entscheiden, ob er zuerst abhängige Systeme prüfen sollte.

Beschreibungen sollten außerdem den relevanten Umfang nennen, wenn ein einzelner Aufruf viele Objekte betrifft. „Löscht den ausgewählten Datensatz“ ist etwas anderes als „Löscht alle Datensätze, die der angegebenen Abfrage entsprechen“. Ein Batch-Endpunkt, der sich hinter einem Verb im Singular versteckt, führt vorhersehbar zu Problemen.

Die Sprache für Genehmigungen muss eine echte Kontrolle beschreiben

Ein Satz zur Genehmigung hilft nur, wenn Implementierung und Betriebsprozess ihn einhalten. „Erfordert Bestätigung“ auf ein Tool zu schreiben, dessen Handler sofort ausgeführt wird, ist Theater. Früher oder später werden Agenten das sichtbar machen.

Es gibt drei unterschiedliche Muster. Die Beschreibung sollte das tatsächlich verwendete Muster nennen.

  1. Der Agent fragt den Benutzer in seinem eigenen Gespräch und ruft danach die Aktion auf. Das hängt davon ab, dass der Agent der Beschreibung folgt, und stoppt keinen veränderten oder nachlässigen Client.
  2. Das Tool erstellt eine Anfrage, die eine andere Person oder ein anderes System genehmigen muss. Der Aufruf selbst hat einen Nebeneffekt, aber die beschriebene Produktionsänderung wartet.
  3. Ein Ausführungs-Gateway hält die Aktion an und verlangt eine menschliche Genehmigung, bevor es Zugangsdaten sendet oder das Zielsystem kontaktiert.

Fasse diese Muster nicht zu „Genehmigung erforderlich“ zusammen. Sie bieten unterschiedlichen Schutz und unterschiedliche Audit-Nachweise.

Verwende Verben, die Akteur und Zeitpunkt erkennen lassen:

Bitte den Benutzer vor dem Aufruf um Bestätigung des Repositorynamens und des Release-Tags.
Dieser Aufruf sendet eine Änderungsanfrage. Das Deployment-System verlangt die Genehmigung durch einen Release-Manager, bevor ein Produktions-Release beginnt.
Dieses Aktions-Gateway bittet einen Menschen, jeden Aufruf zu genehmigen, bevor es die Anfrage an die Produktions-Payments-API sendet.

Die letzte Formulierung beschreibt eine durchgesetzte Grenze. Die erste beschreibt eine Anweisung an den Agenten. Beide können angemessen sein, sind aber nicht gleichwertig.

Bitte den Agenten niemals um eine vage Bestätigung. Sage ihm, welche Fakten die Person genehmigen muss. Bei einer Löschung können das Ressourcenname, Konto und Aufbewahrungsstatus sein. Bei einer Übertragung Quelle, Ziel, Betrag und Währung. Bei einem Release Dienst, Version und Verkehrsbereich. Die Beschreibung sollte kein Ritual verlangen, sondern die Fakten abfragen, die ein falsches Ziel auffallen lassen.

Eine Genehmigungsregel braucht außerdem einen Geltungsbereich. „Vor Produktionsänderungen Genehmigung einholen“ ist schwach, wenn eine Sitzung nach einer einzigen Genehmigung zehn Aufrufe ausführen kann. Wenn die tatsächliche Kontrolle einen Prozess für seine gesamte Lebensdauer genehmigt, beschreibe das in der Produktdokumentation und behaupte nicht, jeder Aufruf werde einzeln angehalten.

Aussagen zu Schreibschutz scheitern bei versteckter Arbeit im Handler

Jeden Aufruf sichtbar halten
Das Aktivitätsprotokoll erfasst einzelne Aufrufe von Agenten über HTTP-APIs und SSH.

Bezeichne ein Tool nur dann als schreibgeschützt, wenn sein Handler das Zielsystem nicht absichtlich verändert. Das Wort beschreibt das Verhalten, nicht die HTTP-Methode, den Namen einer Datenbankberechtigung oder die Hoffnung des Autors.

Eine GET-Anfrage kann eine Sitzung erneuern, ein Feld für den letzten Zugriff aktualisieren, einen Export erzeugen, einen Berichtsjob starten oder das Befüllen eines Caches mit relevanten Kosten auslösen. Eine POST-Anfrage kann harmlos sein, wenn sie einen Testlauf auswertet und nichts dauerhaft speichert. Prüfe den Handler und seine nachgelagerten Aufrufe, bevor du die Bezeichnung wählst.

Die MCP-Annotation readOnlyHint ist für einen Client hilfreich, der die Nutzung von Prüf-Tools vereinfachen möchte. Sie bleibt ein Hinweis, daher muss der Server seine Grenze selbst durchsetzen. Noch wichtiger: Die Beschreibung sollte jede Ausnahme nennen, die einen Bediener überraschen könnte.

Diese Beschreibung ist irreführend:

Schreibgeschütztes Tool zur Prüfung des Rechnungsstatus.

Sie ist falsch, wenn der Endpunkt ein Dokumentansichtsereignis erstellt, ein Token eines Drittanbieters erneuert oder eine entfernte Berechnung startet. Ehrlicher wäre:

Ruft den aktuellen Status einer Produktionsrechnung ab. Die Rechnung wird nicht geändert und dem Kunden wird nichts berechnet. Der Zahlungsanbieter protokolliert diese Anfrage in seinem Zugriffsprotokoll.

Ein Zugriffsprotokoll ist für eine Prüfaktion normalerweise akzeptabel. Es wird relevant, wenn für das Ziel Compliance-Regeln, Kosten pro Abruf oder ein Workflow gelten, der auf Lesevorgänge reagiert. Nenne solche Folgen, ohne jede Beschreibung in einen Rechtshinweis zu verwandeln.

Halte Testläufe und Ausführung möglichst getrennt. Ein deploy-Tool mit einem booleschen dry_run-Wert vereint zwei Sicherheitsprofile in einer Definition. Agenten können einen Standardwert auslassen, missverstehen, ob der Server ihn berücksichtigt, oder eine Nutzlast wiederverwenden, ohne sie zu ändern. plan_production_deployment und execute_production_deployment machen den Unterschied bei Toolauswahl, Protokollen und Prüfungen sichtbar.

Dasselbe gilt für Validierungstools. „Konfiguration validieren“ klingt sicher, aber manche Anbieter reservieren dabei eine Ressource oder kontaktieren eine Live-Abhängigkeit. Wenn das geschieht, beschreibe es als Aktion und wende die passende Genehmigungsregel an.

Ein einziges breites Tool erzeugt Genehmigungsfehler

Tools sollten Operationen nach gemeinsamer Konsequenz und Genehmigungsgrenze gruppieren, nicht nach der Bequemlichkeit eines einzelnen API-Clients. Ein allgemeines Administrationstool macht aus Beschreibungen einen Katalog von Ausnahmen, den weder ein Modell noch ein Mensch zuverlässig lesen wird.

Dieses Muster solltest du vermeiden:

{
  "name": "admin",
  "description": "Administer users, deployments, secrets, and configuration across environments.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": { "type": "string" },
      "environment": { "type": "string" },
      "payload": { "type": "object" }
    },
    "required": ["operation", "environment", "payload"]
  }
}

Diese Definition zerstört die sinnvolle Einheit einer Prüfung. Anhand der Toolkarte kann ein Prüfer nicht erkennen, ob der Aufruf einen Status abruft, Zugangsdaten rotiert oder einen Benutzer löscht. Das Argument operation verschiebt die wichtige Bedeutung in ein spätes Feld, das leicht übersehen wird.

Teile stattdessen nach Absicht und Risiko auf:

get_production_deployment_status
plan_production_deployment
submit_production_deployment_request
rotate_production_service_credential
create_production_user_access_request

Du brauchst nicht für jeden Endpunkt ein eigenes Tool. Separate Tools sind dort nötig, wo sich Ziel, Nebeneffekt oder Genehmigung ändern. Ein Batch-Tool kann ein Batch-Tool bleiben, wenn es immer denselben begrenzten Ressourcentyp betrifft und immer dieselbe Genehmigung braucht. Seine Beschreibung muss sagen, dass mehrere Objekte betroffen sein können, und zeigen, wie der Aufrufer die Auswahl begrenzt.

Auch Argumente brauchen Beschreibungen. Die Toolbeschreibung erklärt, was die Operation tut; Argumentbeschreibungen begrenzen die gefährlichen Entscheidungen. Verwende, wenn möglich, Enums für Umgebungen und Aktionstypen. Lehne unbekannte Werte serverseitig ab. Schreibe „production“ nicht in einen frei formulierten String und vertraue darauf, dass die Beschreibung dich rettet.

Ein eng zugeschnittenes Tool erzeugt außerdem bessere Audit-Datensätze. Wenn im Journal rotate_production_service_credential steht, versteht ein Ermittler die Aktionsklasse, bevor er die Argumente öffnet. Bei admin muss er die Absicht aus einer Nutzlast rekonstruieren.

Schreibe die Beschreibung vor dem Handler

Das Gateway auf dem Mac ausführen
Sallyport läuft als signierte Mac-App in der Menüleiste, deren Tresorkern im Prozess arbeitet.

Wenn du den operativen Vertrag vor der Implementierung formulierst, werden vage Anforderungen sichtbar, solange Änderungen an der Schnittstelle noch günstig sind. Kannst du keinen einfachen Satz über das abgeschlossene Ergebnis schreiben, hast du noch keine stabile Toolgrenze.

Verwende für jedes Aktionstool diese Prüfreihenfolge:

  1. Schreibe das Ziel so auf, wie ein Bediener es identifizieren würde, einschließlich Umgebung, Konto oder Mandant.
  2. Schreibe das abgeschlossene Ergebnis mit einem wörtlichen Verb und gib an, ob die Änderung rückgängig gemacht werden kann.
  3. Nenne den genehmigenden Akteur, den Zeitpunkt der Genehmigung und ob sie pro Aufruf oder pro Sitzung gilt.
  4. Vergleiche den Satz mit dem Verhalten des Handlers, seinen Standardwerten, Wiederholungen und nachgelagerten APIs.
  5. Ergänze Argumentbeschreibungen für IDs, Bereichsbegrenzungen und jeden Wert, der das Ziel ändert.

Der vierte Punkt findet Fehler, die ausgefeilte Dokumentation übersieht. Wiederholungen können dazu führen, dass eine Zahlung oder Nachricht zweimal erfolgt, wenn die nachgelagerte Anfrage keine Idempotenzmechanik verwendet. Standardwerte können ein ausgelassenes environment in production verwandeln. Ein Handler kann einen verständlichen Namen mehreren Ressourcen zuordnen. Die Beschreibung kann diese Implementierungsfehler nicht beheben, aber ihr Schreiben zwingt sie ans Licht.

Ein nützlicher interner Test besteht darin, den Toolnamen zu entfernen und einem anderen Ingenieur nur Beschreibung und Eingabeschema zu zeigen. Bitte ihn vorherzusagen, was nach einem erfolgreichen Aufruf passiert und welche Genehmigung er erwartet. Weicht seine Antwort vom Handler ab, korrigiere den Vertrag oder den Code.

Teste außerdem Aufforderungen in Alltagssprache. „Lösch die alten Daten“, „mach die neue Version live“ und „repariere Jordans Konto“ sind genau die Anfragen, bei denen ein breites Tool verlockend wirkt. Ein sicherer Agent sollte zuerst ein Prüf-Tool verwenden, nach einer fehlenden ID fragen oder die konkrete Aktion zur Genehmigung vorlegen. Wenn er von dieser Aufforderung direkt zur Löschung in der Produktion springen kann, beginnt der Fehler in der Schnittstellengestaltung, lange bevor das Modellverhalten eine Rolle spielt.

Fehlermeldungen und Ergebnisse müssen die Sicherheitsgrenze erhalten

Zuerst den Prozess identifizieren
Genehmigungskarten zeigen zuerst die Codesignatur-Berechtigung des aufrufenden Prozesses, bevor dieser handeln darf.

Eine sorgfältige Beschreibung verliert viel von ihrem Wert, wenn das Tool-Ergebnis das ausgeführte Ziel verbirgt oder ein Fehler den Agenten zu einer umfassenderen Aktion einlädt. Gib Agent und Bediener genug Belege, um zu prüfen, was passiert ist.

Gib bei einer erfolgreichen Zustandsänderung die kanonische Ziel-ID, die ausgeführte Aktion und den resultierenden Zustand zurück. Antworte nicht nur mit ok.

{
  "status": "completed",
  "target": {
    "environment": "production",
    "service": "catalog",
    "release": "2025.06.14-3"
  },
  "action": "traffic_promoted",
  "traffic_percent": 100,
  "request_id": "relreq_8a2f"
}

Bei einer angehaltenen Genehmigung sollte klar sein, dass nichts das Ziel erreicht hat. Diese Unterscheidung verhindert, dass ein Agent einen Aufruf kompensiert, der lediglich auf eine Person wartet.

{
  "status": "approval_required",
  "action": "rotate_production_service_credential",
  "target": "production/catalog-api",
  "executed": false,
  "approval_scope": "this call"
}

Auch Fehler brauchen diese Sorgfalt. „Forbidden“ ist technisch korrekt und operativ nutzlos. Sage dem Aufrufer, ob das Ziel abgelehnt wurde, die Umgebung ungültig war, die Genehmigung fehlte oder die Anfrage nach dem Erreichen des entfernten Systems scheiterte. Gib dabei niemals ein Secret preis und rate dem Agenten niemals, eine zustandsverändernde Anfrage blind zu wiederholen.

Idempotenz braucht bei extern bedeutsamen Aktionen ein sichtbares Ergebnis. Wenn nach einem Netzwerk-Timeout ein entfernter Dienst die Übertragung akzeptiert oder ein Release erstellt hat, muss ein Agent den Status der Anfrage über eine stabile Anfrage-ID abfragen. Der Wiederholungsweg darf nicht raten. Beschreibungen können nicht jede Wiederholungsregel ausdrücken, aber ein Tool für irreversible Aufrufe sollte ein zugehöriges Status-Tool und eine Ergebnisstruktur besitzen, die eine Wiederherstellung unterstützt.

Beschreibungen brauchen Durchsetzung dahinter

Klartext verringert falsche Auswahlen, kann aber keinen Prozess stoppen, der bereits ein uneingeschränktes Produktionstoken besitzt. Lege Zugangsdaten und die endgültige Netzwerkaktion hinter eine Grenze, die den Aufruf ablehnen, genehmigen und protokollieren kann.

Sallyport verwendet diese Anordnung für MCP-verbundene Agenten: Der Agent nutzt den mitgelieferten sp mcp-Shim, während die Anwendung API- und SSH-Zugangsdaten in ihrem verschlüsselten Tresor aufbewahrt und genehmigte Aktionen selbst ausführt. Die sitzungsbezogene Autorisierung und die optionalen Genehmigungen pro Aufruf für ausgewählte Schlüssel machen die Genehmigungsformulierung zu einem durchsetzbaren Verhalten statt zu einer Bitte um gutes Benehmen.

Das entschuldigt kein schlechtes Tooldesign. Das Gateway sieht den Aufruf, der ankommt. Dein Toolschema entscheidet weiterhin, ob der Aufruf „dieses Produktions-Backup löschen“ sagt oder die Löschung hinter einer allgemeinen admin-Operation versteckt. Setze die Argumentvalidierung im Handler durch, begrenze Zugangsdaten auf das vorgesehene Ziel, sofern das entfernte System dies unterstützt, und bewahre einen Audit-Datensatz auf, der Prozess und Aktion identifiziert.

Die Autorisierungsleitlinien des Model Context Protocol machen dieselbe übergeordnete Aussage auf einer anderen Ebene: Autorisierung gehört in einen Protokollablauf mit ausdrücklichen Prüfungen, nicht in eine Modellanweisung. Behandle Beschreibungen als für Menschen lesbaren Vertrag. Behandle Serverautorisierung, Verwahrung der Zugangsdaten und Genehmigung als die Kontrollen, die diesen Vertrag wahr machen.

Nimm das gefährlichste Tool, das du heute anbietest, und schreibe seine Beschreibung neu, ohne auf den Namen zu schauen. Kannst du das Produktionsziel, den abgeschlossenen Nebeneffekt und den Genehmigungsumfang nicht in zwei oder drei direkten Sätzen nennen, solltest du dieses Tool einem autonomen Agenten noch nicht anbieten.

FAQ

Was sollte die Beschreibung eines MCP-Tools für eine Produktionsaktion enthalten?

Die Beschreibung eines Produktionstools sollte das genaue Ziel nennen, angeben, was sich ändert, und sagen, ob eine Person den Aufruf genehmigen muss. „Deploy service“ ist unzureichend, weil Umgebung, Aktion und Genehmigungsgrenze fehlen. Beschreibe die Folge so, dass ein müder Ingenieur sie beim ersten Lesen versteht.

Reichen MCP-Toolnamen aus, um versehentliche Änderungen in der Produktion zu verhindern?

Toolnamen helfen bei der Auswahl, sind aber oft abgekürzt und veralten, wenn ein Tool wächst. Die Sicherheitsbedeutung gehört in die Beschreibung, weil Agent und Bediener dort Ziel, Nebeneffekt und Genehmigungspflicht gemeinsam sehen. Halte auch den Namen präzise, verlasse dich aber nicht allein auf ihn.

Wie beschreibe ich das Zielsystem in einem MCP-Tool eindeutig?

Setze das Zielsystem an den Anfang: „Produktions-Billing-API“ ist besser als „API“. Nenne dann die Zustandsänderung, etwa das Deaktivieren eines Kunden oder das Erstellen eines Deployments. Lege abschließend die Genehmigungsregel in einfacher Sprache fest und erwähne, wenn das Tool nur eine Anfrage vorbereitet.

Wie formuliere ich einen irreversiblen Nebeneffekt?

Sag, was der Aufruf ändert, und, falls relevant, was sich nicht rückgängig machen lässt. „Löscht das ausgewählte Produktionsdatenbank-Backup dauerhaft“ ist eindeutig. „Verwaltet Backups“ überlässt es dem Agenten zu erraten, ob Daten aufgelistet, wiederhergestellt, kopiert oder zerstört werden.

Reicht „Genehmigung erforderlich“ in einer Toolbeschreibung aus?

Nein. Ein Satz wie „Genehmigung erforderlich“, der nicht sagt, wer wann genehmigt, erzeugt falsche Sicherheit. Gib an, ob der Benutzer jeden Aufruf genehmigt, ob ein externes Gateway nachfragt oder ob das Tool nur eine Anfrage für einen separaten Bediener eröffnet.

Sollten Genehmigungsanforderungen strukturierte Felder oder Klartext sein?

Ein Agent kann ein strukturiertes Genehmigungsfeld zuverlässiger auswerten, aber die Beschreibung braucht trotzdem eine verständliche Sicherheitsaussage für Menschen, die das Tool prüfen. Verwende beides, wenn möglich. Das strukturierte Feld ersetzt keine lesbare Beschreibung der Konsequenz.

Kann ich ein Tool als schreibgeschützt kennzeichnen, wenn es Zugriffe protokolliert oder ein Token erneuert?

Nur dann, wenn das Tool das Zielsystem nicht absichtlich verändert. Ressourcen aufzulisten, einen Status abzurufen oder eine Anfrage zu validieren gilt nur dann als schreibgeschützt, wenn die Implementierung keine Zugangsdaten erneuert, Datensätze erstellt oder Hintergrundarbeit auslöst. Prüfe den Handler, nicht das Verb im Namen.

Sollten Planung und Ausführung getrennte MCP-Tools verwenden?

Verwende getrennte Tools, wenn sich ihre Folgen unterscheiden. Ein einzelnes „deploy“-Tool, das planen, veröffentlichen, zurückrollen und umschalten kann, erhält irgendwann die falschen Parameter. Trenne Prüfung, Anfrageerstellung und Ausführung, damit jede Beschreibung ein eindeutiges Versprechen macht.

Wie dokumentiere ich ein Tool, das auf Staging oder Produktion zielen kann?

Wenn das Ziel aus einem Argument stammt, beschreibe die erlaubten Werte und nenne die Produktion ausdrücklich. Behaupte nicht, dass immer eine Genehmigung nötig ist, wenn Aufrufe in der Entwicklung daran vorbeigehen. Teile das Tool auf oder mache die Umgebungsregel im Toolvertrag sichtbar und setze sie im Code durch.

Wie kann ich testen, ob MCP-Beschreibungen eine unsichere Toolauswahl verhindern?

Teste mit Aufforderungen, die ungenaue Wörter verwenden, etwa „aufräumen“, „veröffentlichen“, „Zugriff reparieren“ oder „das alte entfernen“. Prüfe, ob der Agent das Tool auswählt, eine sinnvolle Rückfrage stellt und die Genehmigungsgrenze einhält. Ein Tool, das nur bei perfekten Prompts sicher funktioniert, ist für den alltäglichen Einsatz nicht sicher genug.

Sallyport

Sallyport führt API-Aufrufe und SSH-Befehle für Ihren KI-Agenten aus. Die Schlüssel bleiben in einem lokalen Tresor auf Ihrem Mac; Sie geben jeden Lauf frei, und jede Aktion landet in einem versiegelten Journal.

© 2026 Sallyport · Open Source unter Apache-2.0 · Oleg Sotnikov