MCP-Tool-Aufrufe schlagen fehl: Eingaben, Validierung und Fehler-Payloads debuggen

MCP-Tools werden angezeigt, aber Aufrufe schlagen fehl? Diese allgemeine Anleitung hilft beim Debuggen von Tool-Aufruf-Fehlern: ungültige Argumente, fehlende Pflichtfelder, falsche IDs und serverseitige Validierungsfehler. So grenzen Sie Probleme ein, indem Sie zuerst nur Lese-Aufrufe testen.

Tool-Aufruf-Fehler verstehen

Wenn ein Tool-Aufruf fehlschlägt, hat die Anfrage den Server erreicht und wurde verarbeitet, aber etwas an der Eingabe oder Operation war ungültig. Das unterscheidet sich von Verbindungs- oder Authentifizierungsfehlern.

Fehlerkategorien

Eingabefehler: Ungültige Argumente, falsche Typen, fehlende Pflichtfelder
ID-Fehler: Falsche Aufgaben-/Projekt-/Board-IDs, nicht existierende Ressourcen
Validierungsfehler: Serverseitige Validierungsfehler (Geschäftslogik)
Berechtigungsfehler: Gültige Eingabe, aber unzureichende Berechtigungen (siehe 403 Forbidden)

Debug-Strategie: Zuerst nur lesen

Beginnen Sie mit Lese-Operationen, um den Grundzugriff zu prüfen, bevor Sie Schreibzugriffe versuchen:

Empfohlener Debug-Ablauf

Lese-Operationen testen: list_tasks, list_projects, get_task (nur lesen)
IDs prüfen: IDs aus Lese-Operationen in nachfolgenden Aufrufen verwenden
Einfache Schreibzugriffe testen: add_task_comment (einfacher als create_task)
Komplexe Schreibzugriffe testen: Schließlich create_task, update_task (mehr Validierung)

Warum zuerst nur lesen?

Weniger Validierungsregeln: Lese-Operationen haben einfachere Anforderungen
Zugriff prüfen: Bestätigt, dass Sie die Ressource erreichen können
Korrekte IDs erhalten: Lese-Operationen liefern gültige IDs für Schreibzugriffe
Probleme eingrenzen: Wenn Lesen klappt, Schreiben aber nicht, ist es ein Schreib-spezifisches Problem

Fehlertyp 1: Ungültige Argumente

Argumente, die nicht zum erwarteten Typ oder Format passen:

Häufige Argumentfehler

Falscher Typ

Beispiel: String "123" statt Integer 123 für task_id übergeben
❌ { "task_id": "123" } // String
✅ { "task_id": 123 } // Integer

Ungültiger Enum-Wert

Beispiel: "active" statt "in_progress" für status
❌ { "status": "active" }
✅ { "status": "in_progress" } // Gültig: open, in_progress, done, blocked

Ungültiges Datumsformat

Beispiel: Falsches Datumsformat für due_date
❌ { "due_date": "2026/05/30" }
✅ { "due_date": "2026-05-30" } // ISO-8601-Format

Fehlertyp 2: Fehlende Pflichtfelder

Manche Tool-Aufrufe verlangen bestimmte Felder:

Pflichtfelder je Tool

get_task: Erfordert task_id
create_task: Erfordert title (und oft project_id)
update_task: Erfordert task_id
add_task_comment: Erfordert task_id und comment
start_time_tracking: Erfordert task_id

Beispiel: Fehlendes Pflichtfeld

Ungültig (title fehlt)

Fehlendes Pflichtfeld "title"

{
  "project_id": 123,
  "description": "Task description"
}

Gültig (title vorhanden)

Pflichtfeld "title" vorhanden

{
  "title": "Task title",
  "project_id": 123,
  "description": "Task description"
}

Fehlertyp 3: Falsche IDs

IDs, die nicht existieren oder zu anderen Ressourcen gehören:

Häufige ID-Fehler

Nicht existierende ID

Beispiel: task_id 99999, die nicht existiert
Lösung: Zuerst list_tasks nutzen, um gültige Aufgaben-IDs zu erhalten

Falscher Ressourcentyp

Beispiel: project_id, wo task_id erwartet wird
Lösung: Prüfen, dass der Parametername zum Ressourcentyp passt

ID aus anderem Arbeitsbereich

Beispiel: Aufgaben-ID aus Arbeitsbereich A in Arbeitsbereich B verwendet
Lösung: Sicherstellen, dass API-Schlüssel und Ressourcen-IDs aus demselben Arbeitsbereich stammen

So erhalten Sie korrekte IDs

Lese-Operationen für gültige IDs nutzen:

list_tasks aufrufen für verfügbare Aufgaben-IDs
list_projects aufrufen für verfügbare Projekt-IDs
list_boards aufrufen für verfügbare Board-IDs
Diese IDs in nachfolgenden Tool-Aufrufen verwenden

Fehlertyp 4: Serverseitige Validierung

Auch bei gültigen Argumenten kann der Server die Operation wegen der Geschäftslogik ablehnen:

Häufige Validierungsfehler

Verstöße gegen Geschäftsregeln

Aufgabe mit Abhängigkeiten kann nicht gelöscht werden
Bereits abgeschlossene Aufgabe kann nicht aktualisiert werden
Aufgabe kann nicht in einem geschlossenen Projekt erstellt werden
Datumsbedingungen (due_date vor start_date)

Zustandskonflikte

Zeiterfassung kann nicht gestartet werden, wenn bereits eine andere Aufgabe erfasst wird
Aufgabenstatus kann nicht auf ungültigen Übergang gesetzt werden
Kommentar kann nicht zu gelöschter Aufgabe hinzugefügt werden

Fehler-Payloads interpretieren

Fehlerantworten enthalten Details dazu, was schiefgelaufen ist:

Fehler-Antwort-Struktur

Typisches Fehler-Antwort-Format:

{
  "error": {
    "code": "validation_error",
    "message": "Task ID 99999 not found",
    "field": "task_id",
    "details": "The specified task does not exist"
  }
}

Häufige Fehlercodes

validation_error

Eingabevalidierung fehlgeschlagen (falscher Typ, fehlendes Feld, ungültiger Wert)

not_found

Ressource mit der angegebenen ID existiert nicht

forbidden

Gültige Eingabe, aber unzureichende Berechtigungen (siehe 403-Anleitung)

conflict

Operation kollidiert mit dem aktuellen Zustand (z. B. doppelte Aufgabe, ungültiger Zustandsübergang)

Schritt-für-Schritt-Debug-Prozess

Systematischer Debug-Ablauf

Fehlermeldung lesen: Fehlercode und Meldung nach Hinweisen prüfen
IDs prüfen: Mit List-Operationen bestätigen, dass Ressourcen-IDs gültig sind
Pflichtfelder prüfen: Tool-Dokumentation auf erforderliche Parameter prüfen
Mit Nur-Lesen testen: get_task oder list_tasks zum Prüfen des Grundzugriffs
Aufruf vereinfachen: Optionale Parameter entfernen und mit minimalen Pflichtfeldern testen
Feldtypen prüfen: Sicherstellen, dass Strings, Integer und Datumsangaben im richtigen Format sind
Fehlerdetails prüfen: "field" und "details" in der Fehlerantwort ansehen

Beispiel: Fehlgeschlagenen Tool-Aufruf debuggen

So debuggen Sie einen konkreten Fehler:

Fehlgeschlagener Aufruf

Tool: update_task
Argumente: { "task_id": "123", "status": "completed" }
Fehler: "Task ID 123 not found"

Debug-Schritte

Zuerst prüfen, ob die Aufgabe existiert: get_task(task_id: 123)
Wenn das fehlschlägt: list_tasks() für verfügbare IDs
Prüfen, ob task_id Integer sein muss, nicht String: { "task_id": 123 }
Prüfen, ob die Aufgabe im zugänglichen Arbeitsbereich ist

Lösung

Problem: task_id wurde als String "123" statt als Integer 123 übergeben
Lösung: Auf { "task_id": 123 } (Integer) geändert
Ergebnis: Tool-Aufruf erfolgreich

Schnell-Checkliste

Vor der Support-Anfrage

✅ Fehlermeldung genau gelesen – was steht dort?
✅ IDs mit List-Operationen auf Existenz geprüft
✅ Alle Pflichtfelder vorhanden
✅ Zuerst mit Lese-Operationen getestet
✅ Feldtypen geprüft (String vs. Integer, Datumsformat)
✅ Aufruf auf minimale Pflichtfelder reduziert
✅ Tool-Dokumentation zu Parameteranforderungen geprüft