MCP-Werkzeuge gestalten, die Agenten sicher benutzen können

Ziel

Fähigkeiten so für Sprachmodell-Agenten bereitstellen, dass das Modell das richtige Werkzeug anhand der Beschreibung wählt, es anhand des Schemas korrekt aufruft und das Ergebnis ohne Raten deutet – und dass ein falsch instruiertes Modell keinen Schaden anrichten kann.

Voraussetzungen

Eine MCP-Server-Implementierung (die offiziellen SDKs) und eine klare Liste der Operationen, die Agenten legitimerweise brauchen. Die Spezifikation beschreibt ein Werkzeug mit name, description, inputSchema (JSON Schema der Parameter), optionalem outputSchema und annotations; das Schema definiert darin readOnlyHint, destructiveHint, idempotentHint und openWorldHint und hält ausdrücklich fest, dass alle Annotationen Hinweise sind, keine Zusicherung über das tatsächliche Verhalten. Clients müssen Annotationen als nicht vertrauenswürdig behandeln, sofern sie nicht von einem vertrauenswürdigen Server stammen, und es soll stets ein Mensch mit der Möglichkeit eingebunden sein, Aufrufe abzulehnen. Von Servern verlangt die Spezifikation, alle Eingaben zu prüfen, Zugriffskontrollen umzusetzen, Aufrufe zu drosseln und Ausgaben zu bereinigen.

Schritte

1. Ein Zweck je Werkzeug, mit Verb-Nomen-Namen (search, read_section); keine Sammelwerkzeuge mit Modus-Parameter.
2. Ein Eingabeschema mit begrenzten Typen (Längen, Seitengrössen) und ein Ausgabeschema deklarieren; strukturierte Ergebnisse (structuredContent) lassen Clients prüfen, was sie erhalten.
3. Annotationen wahrheitsgemäss setzen. Ein nur lesender Server stellt kein Werkzeug bereit, das schreibt – die Annotation beschreibt, sie schützt nicht.
4. Jedes Ergebnis begrenzen: Seitengrössen, Textlängen, Zeitlimits; für mehr einen Cursor zurückgeben.
5. Erwartbare Fehlschläge als Werkzeugfehler (isError) mit stabilem Code und Text zurückgeben (nicht gefunden, Kontingent erschöpft mit Wartehinweis), damit das Modell reagieren kann; Protokollfehler (JSON-RPC-Fehler) bleiben, wie die Spezifikation es trennt, unbekannten Werkzeugen, ungültigen Argumenten und Serverfehlern vorbehalten.
6. Werkzeugbeschreibungen im Anwendungscode halten und wie API-Dokumentation reviewen; nie aus Inhalten ableiten, die Nutzende oder Agenten bearbeiten können, sonst werden fremde Texte zu Anweisungen an das Modell.
7. Berechtigungen serverseitig an die Identität des Aufrufers binden, nicht an das, was das Modell behauptet, und Token-Scopes so eng wie möglich schneiden: Die Sicherheitshinweise der Spezifikation beschreiben unter «Scope Minimization», wie ein gestohlenes Token mit breiten Scopes den Schaden ausweitet und den Widerruf erschwert.

Erwartetes Ergebnis

Ein Agent liest tools/list, wählt das Werkzeug nach Beschreibung, sendet beim ersten Versuch gültige Argumente und erhält strukturierten Inhalt oder einen klaren Fehler.

Grenzen und Prüfbasis

Gute Schemata verhindern keinen Missbrauch durch ein schlecht instruiertes Modell; destruktive Operationen werden ausser Reichweite gehalten statt durch Beschreibungen abgesichert. Der Entwurf folgt der zitierten Spezifikation; eine Messung der Trefferquote bei der Werkzeugwahl wird nicht behauptet.

Zahl der Werkzeuge

Jede Werkzeugdefinition geht bei jedem Modellaufruf mit in den Kontext, und einige Client-APIs deckeln die Zahl der Werkzeuge je Anfrage. «Ein Zweck je Werkzeug» meint deshalb eine Entscheidung je Werkzeug, nicht eine Operation je Werkzeug: Mehrere Aktionen auf demselben Objekt mit denselben Annotationen (alle lesend, alle idempotent) dürfen ein Werkzeug mit einem action-Enum und einem oneOf-Schema je Aktion bilden; sobald sich die Annotationen unterscheiden würden, ist das der Grund für die Trennung. Für sehr grosse APIs bleibt das Muster aus einem Suchwerkzeug, das die passende Operation samt Schema findet, und einem generischen Aufrufwerkzeug. tools/list ist per Cursor paginierbar und notifications/tools/list_changed erlaubt, die Menge zur Laufzeit anzupassen.