Das MCP-Handbuch

Kapitel 4: Tools – Die Hände des Modells

Während Resources (Daten) dem Modell "Wissen" geben, sind Tools die Werkzeuge, mit denen das Modell aktiv werden kann. In diesem Kapitel lernen wir, wie man Tools definiert, implementiert und testet – basierend auf der MCP-Spezifikation vom 2025-11-25 (inkl. SEP-1303 und SEP-973).

Was ist ein MCP Tool?

Ein Tool ist eine ausführbare Funktion, die der Server dem Client zur Verfügung stellt. Jedes Tool besteht aus:

  1. Name: Eine eindeutige ID (z. B. calculate_sum).
  2. Beschreibung: Ein Text, der dem LLM erklärt, wann und warum es dieses Tool nutzen sollte.
  3. Input Schema: Ein JSON-Schema (Standard: JSON Schema 2020-12), das die Argumente definiert.
  4. Icons (Neu 2025-11): Optionale visuelle Metadaten für Clients.

Metadaten und Icons (SEP-973)

Seit November 2025 können Tools (sowie Ressourcen und Prompts) visuelle Metadaten enthalten. Dies ermöglicht es Clients, eine ansprechende Benutzeroberfläche mit Icons zu gestalten.

Ein Icon besteht aus:

  • src: Eine URL (HTTP/HTTPS) oder ein Data-URI (Base64 – eine Methode, um Bilder direkt als Text-String einzubetten).
  • mimeType: Optionaler Medientyp (z. B. image/png).
  • sizes: Optionale Angabe der Dimensionen (z. B. 48x48).

Implementierung in Go

mcp.AddTool(s, &mcp.Tool{
    Name:        "add",
    Description: "Addiert zwei ganze Zahlen",
    InputSchema: map[string]any{
        "type": "object",
        "properties": map[string]any{
            "a": map[string]any{"type": "integer"},
            "b": map[string]any{"type": "integer"},
        },
        "required": []string{"a", "b"},
    },
    // Icons können nun als Metadaten hinterlegt werden (SEP-973)
}, func(ctx context.Context, request *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
    a, _ := args["a"].(float64)
    b, _ := args["b"].(float64)
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: fmt.Sprintf("Ergebnis: %d", int(a)+int(b))},
        },
    }, nil, nil
})

Entwurfsmuster: „Rechnen statt Denken“ (z. B. `wollmilchsau`)

Das obige add-Beispiel verdeutlicht ein fundamentales Prinzip für eigene MCP-Tools: LLMs sind probabilistische Text-Generatoren, keine Rechenmaschinen.

Wenn Sie ein LLM bitten, 17-stellige Zahlen zu multiplizieren, Datumsdifferenzen zu berechnen oder komplexe Tabellen zu aggregieren, neigen selbst modernste Modelle zu Halluzinationen. Über ein Tool lagern wir die Berechnung jedoch an die CPU aus:

  • Das Modell erkennt die Absicht: „Ich muss zwei Zahlen addieren.“
  • Es ruft das Tool add auf.
  • Die CPU liefert in Mikrosekunden ein mathematisch 100 % deterministisches Ergebnis zurück.

Dieses Muster lässt sich noch viel weiter treiben: Unser Open-Source-Server wollmilchsau (github.com/hmsoft0815/wollmilchsau · mlcgo.eu/products/wollmilchsau) stellt dem LLM eine komplette V8-JavaScript/TypeScript-Sandbox als Tool bereit. Anstatt komplexe Filter, Regex oder mathematische Gleichungen durch teures "Chain-of-Thought"-Reasoning im Prompt zu lösen, schreibt das Modell einen kleinen Code-Schnipsel, führt ihn in der Sandbox aus und erhält sofort das exakte Ergebnis.

Entwurfsmuster: Der sichere Datenbank-Gatekeeper

Ein weiteres Paradebeispiel für eigene Tools ist der kontrollierte Zugriff auf lokale Datenbanken: Geben Sie einem LLM niemals ein generisches Tool wie execute_sql_query("...") mit Schreibrechten auf eine Produktionsdatenbank. Das Risiko von SQL-Injections, versehentlichem Datenverlust oder der Offenlegung interner Tabellen-Schemata ist immens.

Stattdessen definiert ein guter MCP-Server fachlich gekapselte Werkzeuge:

  • get_customer_balance(customer_id)
  • list_open_invoices(limit)

Der MCP-Server führt intern das vorbereitete SQL-Statement (Prepared Statement) aus, filtert sensible Spalten (wie Passwörter oder interne IDs) heraus und liefert nur das bereinigte Ergebnis zurück. So bleibt Ihre lokale Datenbank nach außen vollständig abgeschirmt, während die KI produktiv mit den Daten arbeiten kann.

Strategische Fehlerbehandlung (SEP-1303)

Eine wichtige Änderung in der Spezifikation vom November 2025 betrifft die Validierung. Wenn ein Modell ungültige Argumente sendet, sollte der Server keinen JSON-RPC Fehler (Protokoll-Ebene) zurückgeben.

Stattdessen sollte der Fehler als reguläres Tool-Ergebnis mit IsError: true gesendet werden. Warum? Nur wenn der Fehler im Inhalts-Array landet, kann das LLM die Fehlermeldung "lesen", den Fehler verstehen und einen korrigierten Aufruf starten (Self-Correction).

if b == 0 {
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Fehler: Division durch Null ist nicht erlaubt."}},
        IsError: true,
    }, nil, nil
}

Tool Annotations: Absichtsbewusste Werkzeuge (readOnlyHint & Co.)

Autonome Agenten und Clients müssen oft entscheiden: Darf dieses Tool automatisch im Hintergrund ausgeführt werden, oder muss der Benutzer vorher explizit zustimmen?

Früher mussten Clients Heuristiken über den Tool-Namen (delete_*, remove_*) anwenden. Seit der Spezifikation 2025-03-26 definiert MCP offizielle Tool Annotations im Tool-Objekt:

{
  "name": "delete_customer",
  "description": "Löscht einen Kunden unwiderruflich aus der Datenbank",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string" }
    },
    "required": ["customer_id"]
  }
}

Die drei Kern-Annotationen:

  1. readOnlyHint (boolean): Garantiert, dass der Aufruf keine Daten oder Zustände verändert (reines Lesen/Berechnen). Clients können solche Tools ohne Bestätigungsdialog automatisch ausführen.
  2. destructiveHint (boolean): Kennzeichnet Werkzeuge, die Daten löschen, überschreiben oder irreversible Änderungen auslösen. Clients sollten dem Benutzer ein Warnmodal mit den Parametern anzeigen ("Möchten Sie Kunde 4711 wirklich löschen?").
  3. idempotentHint (boolean): Zeigt an, dass mehrfache Aufrufe mit identischen Parametern denselben Zustand erzeugen. Wichtig für automatische Retry-Strategien bei Netzwerkabbrüchen.

In Go deklarieren Sie Annotations direkt bei der Tool-Registrierung:

s.AddTool(&mcp.Tool{
    Name:        "get_customer_balance",
    Description: "Liest den aktuellen Kontostand eines Kunden aus.",
    Annotations: &mcp.ToolAnnotations{
        ReadOnlyHint:   true,
        DestructiveHint: false,
        IdempotentHint:  true,
    },
    // ...
}, handler)

[!TIP] Die Verknüpfung von Tool Annotations mit Sicherheits-Scopes (OAuth 2.1) wird ausführlich in Kapitel 17 behandelt.

Tools testen mit `mcp-tester`

Der mcp-tester unterstützt die neuesten Standards und erlaubt es, Tool-Aufrufe präzise zu simulieren:

./bin/mcp-tester tools call add --args '{"a": 10, "b": 5}' --profile local

Prüfen Sie in der Ausgabe besonders das IsError Flag, um sicherzustellen, dass Ihr Server die neue Fehlerstrategie (SEP-1303) korrekt umsetzt.

Ausblick: Tools in Agent Skills organisieren

Wenn Ihr Server sehr viele Tools anbietet, riskieren Sie eine Überlastung des Modells. Eine moderne Lösung für dieses Problem ist die Gruppierung von Tools in Agent Skills. Dabei werden Tools nicht alle gleichzeitig, sondern bedarfsorientiert geladen. Mehr dazu erfahren Sie in Kapitel 23.

← Kapitel 3: Minimal MCP | Inhaltsverzeichnis | Nächstes Kapitel: Resources →

Copyright Michael Lechner - 2026-04-26

Lizenz: CC BY-NC 4.0