MCP-Tools rund um fachliche Aktionen entwerfen statt rund um Endpunkte

Was bei einem Tool pro Endpunkt schiefgeht

Server, die aus einer API-Beschreibung generiert werden, sind schnell gebaut und für ein Modell schwer gut zu nutzen. Anthropics Engineering-Beitrag über Tools für Agenten benennt das Muster: Tools, die nur bestehende Endpunkte kapseln, ob sie zu einem Agenten passen oder nicht, und überlappende Tools, die ihn von effizienten Lösungswegen ablenken. In der Praxis zeigen sich die Kosten an drei Stellen.

• Kontext: Listen-Endpunkte liefern alles, und das Modell liest jeden Datensatz, um einen zu finden
• Reihenfolge: Das Modell muss lernen, dass eine Bestellabfrage zuerst eine Kunden-ID aus einem anderen Aufruf braucht, und liegt dabei manchmal falsch
• Berechtigungen: Jeder angebotene Endpunkt kann vom Modell aufgerufen werden, auch solche, die niemand dafür vorgesehen hat

Bei echten Anfragen beginnen, nicht bei der API

Sammeln Sie zwanzig bis fünfzig echte Anfragen der künftigen Nutzer: Tickets, Chatnachrichten, Fragen an Kollegen. Gruppieren Sie sie nach der fachlichen Aktion dahinter. Jede Aktion wird zum Kandidaten für ein Tool, und für jeden halten Sie fest, wer es nutzen darf, was es liest, was es ändert und wie ein korrektes Ergebnis aussieht. Anfragen, die zu keiner Aktion passen, sind ein Grund, etwas wegzulassen, und kein Anlass für ein generisches Tool, das alles kann.

Durchgerechnetes Beispiel: eine hypothetische API für den Bestellsupport

Nehmen wir einen Bestellservice mit vierzehn Endpunkten für Kunden, Bestellungen, Positionen, Sendungen, Tracking, Retouren, Erstattungen und Notizen. Die Anfragen des Supportteams fallen in vier Aktionen, also bietet der Server vier Tools an.

• find_orders: nimmt eine Kunden-E-Mail oder Bestellnummer entgegen und liefert bis zu zehn Bestellungen mit Status, Summe und letztem Sendungsereignis
• get_order_details: eine Bestellung mit Positionen, Tracking und offenen Retouren, zusammengesetzt aus fünf Endpunkten
• prepare_return: prüft die Berechtigung nach der Retourenrichtlinie und liefert einen Vorschlag mit kurzlebigem Bestätigungs-Handle, ohne etwas zu ändern
• confirm_return: legt die Retoure anhand dieses Handles nur an, wenn der Server die Freigabe des Nutzers für genau diesen Vorschlag gespeichert hat; ein Aufruf ohne Freigabe oder für einen geänderten Vorschlag wird abgewiesen

Erstattungen, Adressänderungen und Stornierungen bleiben in der ersten Version draußen. Jede davon braucht eigene Regeln und einen Verantwortlichen, der das Tool abnimmt.

Was eine Tool-Definition zusagen sollte

In MCP deklariert jedes Tool einen Namen, eine Beschreibung und ein Eingabeschema, optional auch ein Ausgabeschema und Annotationen. Behandeln Sie die Definition als Vertrag, den Modell und Reviewer gleichermaßen lesen können. Begrenzen Sie Eingaben über Typen, Enums und Muster, und lehnen Sie unerwartete Felder ab. Wenn Sie ein Ausgabeschema angeben, verlangt die Spezifikation, dass der Server strukturierte Ergebnisse liefert, die ihm entsprechen.

{
  "name": "find_orders",
  "title": "Find orders",
  "description": "Find a customer's recent orders by email address or order number. Returns at most 10 orders, newest first.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_email": { "type": "string", "format": "email" },
      "order_number": { "type": "string", "pattern": "^SO-[0-9]{8}$" },
      "status": { "type": "string", "enum": ["open", "shipped", "delivered", "returned"] }
    },
    "additionalProperties": false
  },
  "annotations": { "readOnlyHint": true, "openWorldHint": false }
}

Die Annotationen beschreiben das Tool gegenüber dem Client als rein lesend. Es sind Hinweise, denen Clients bei unbekannten Servern nicht vertrauen dürfen. Der Server erzwingt das reine Lesen deshalb selbst und prüft, dass mindestens ein Suchfeld angegeben wurde.

Fehler und Schreibschritte, die das Modell vorhersehen kann

MCP unterscheidet zwei Arten von Fehlern. Protokollfehler betreffen unbekannte Tools und fehlerhafte Anfragen. Fehler bei der Tool-Ausführung, im Ergebnis mit isError auf true gekennzeichnet, betreffen API-Ausfälle, ungültige Werte und verletzte Geschäftsregeln, und die Spezifikation empfiehlt Clients, sie an das Modell weiterzugeben, damit es nachsteuern kann. Formulieren Sie diese Meldungen für das Modell: Die Nachricht, dass Bestellung SO-12345678 vor 41 Tagen zugestellt wurde und Retouren nach 30 Tagen enden, lässt es die Ablehnung erklären, ein HTTP 422 nicht.

Bei Änderungen trennen Sie wie im Beispiel Vorbereitung und Bestätigung, machen den bestätigenden Aufruf idempotent, damit eine Wiederholung keine zweite Retoure erzeugt, und binden jedes Handle an den Nutzer, der es angefordert hat. Die aktuelle Spezifikation kennt keine Protokoll-Sessions. Zustand über mehrere Aufrufe wandert als explizites Handle, und der Server muss bei jedem Aufruf prüfen, ob es zum Aufrufer gehört.

Wann ein dünner API-Wrapper die bessere Wahl ist

Tools für fachliche Aktionen sind teurer in der Entwicklung und müssen sich ändern, wenn sich der Prozess ändert. Ein dünner Wrapper kann passen für einen Entwickler-Assistenten, der eine interne API erkundet, für einen lesenden Reporting-Server über einer gut entworfenen Abfrage-API oder für einen Prototyp, den Sie wieder verwerfen. Überschneidungen wiegen schwerer als die Anzahl: Zwanzig klar getrennte Tools können besser funktionieren als acht, die sich fast doppeln.

Welche Form Sie auch wählen, messen Sie sie. Anthropics Beitrag empfiehlt, Tools an realistischen Aufgaben zu evaluieren und die Transkripte zu lesen. Ihre gesammelten Anfragen mit erwarteten Ergebnissen reichen, um zwei Entwürfe zu vergleichen, bevor Nutzer einen davon sehen.

MCP-Server-Entwicklung