MCP-Timeouts und langsame Antworten: Setup stabilisieren

Timeouts oder langsame MCP-Tool-Aufrufe? Diese Performance-Anleitung hilft, Timeout-Ursachen zu finden, lange laufende Operationen zu optimieren, Retry-Muster einzusetzen und Antwortzeiten durch Paginierung und Abfrage-Optimierung zu verbessern.

Timeouts und langsame Antworten verstehen

Timeouts treten auf, wenn ein Tool-Aufruf länger dauert als das Timeout-Limit des Clients. Langsame Antworten funktionieren, brauchen aber ungewöhnlich lange und deuten auf Performance-Probleme hin.

Häufige Ursachen

Große Ergebnismengen (zu viele Aufgaben/Projekte)
Komplexe Abfragen ohne Paginierung
Zu viele parallele Tool-Aufrufe
Netzwerk-Latenz oder Verbindungsprobleme
Serverseitige Verarbeitungsverzögerungen
Client-Timeout-Einstellungen zu niedrig

Schritt 1: Problem eingrenzen

Prüfen, ob es um Timeouts (Aufrufe schlagen fehl) oder langsame Antworten (Aufrufe gelingen, dauern aber lange) geht:

Timeout vs. langsame Antwort

Timeout-Symptome

Tool-Aufruf schlägt mit Timeout-Fehler fehl
Keine Antwort innerhalb des Timeout-Zeitraums
Verbindung bricht bei langen Operationen ab

Symptome langsamer Antworten

Tool-Aufruf gelingt, dauert aber 10+ Sekunden
Antwort kommt schließlich, aber sehr langsam
Oberfläche reagiert während der Aufrufe nicht

Schritt 2: Paginierung nutzen

Große Ergebnismengen sind eine häufige Timeout-Ursache. Paginierung nutzen, um die Anzahl der Ergebnisse zu begrenzen:

Best Practices für Paginierung

Limit-Parameter nutzen

// Statt alle Aufgaben zu holen
list_tasks()  // Kann 1000+ Aufgaben liefern, führt zu Timeout

// Paginierung nutzen
list_tasks(limit: 50, offset: 0)  // Erste 50
list_tasks(limit: 50, offset: 50)  // Nächste 50

Empfohlene Limits

list_tasks: limit: 50–100 (Standard oft 50)
list_task_comments: limit: 25–50
list_projects: Meist klein, bei Bedarf limit: 20
list_boards: Meist klein, Limit selten nötig

Prompt-Muster für Paginierung

Gut: Paginierte Anfrage

"List my tasks, but only show the first 50. If I need more, I'll ask for the next batch."

So nutzt die KI limit: 50

Schlecht: Unbegrenzte Anfrage

"Show me all my tasks"

Kann versuchen, alle Aufgaben zu holen und führt zu Timeout

Schritt 3: Parallele Tool-Aufrufe reduzieren

Zu viele gleichzeitige Tool-Aufrufe können die Verbindung überlasten und Timeouts verursachen:

Sequenziell vs. parallel

Probleme bei parallelen Aufrufen

Manche KI-Assistenten rufen mehrere Tools parallel auf, was:

die Verbindung überlasten kann
Rate-Limits überschreiten kann
Timeouts verursachen kann, wenn mehrere Aufrufe konkurrieren

Prompt-Muster für weniger parallele Aufrufe

Gut: Sequenzieller Ansatz

"First, list my projects. Then, for each project, list the tasks one at a time."

Fördert sequenzielle statt parallele Aufrufe

Schlecht: Paralleler Ansatz

"Get all my projects and all their tasks at once"

Kann parallele Aufrufe auslösen und zu Timeouts führen

Schritt 4: Abfragen optimieren

Filter nutzen, um Ergebnisse vor dem Abruf einzugrenzen:

Filter sinnvoll nutzen

Gefilterte Abfrage (schneller)

// Nur diese Woche fällige Aufgaben
list_tasks(due_date: "2026-06-02", status: "in_progress", limit: 50)

// Statt alle Aufgaben zu holen und clientseitig zu filtern
list_tasks()  // Liefert alles, dann Filter (langsam)

Verfügbare Filter

project_id: Nach bestimmten Projekt filtern
board_id: Nach bestimmten Board filtern
status: Nach Status filtern (open, in_progress, done, blocked)
due_date: Nach Fälligkeitsdatum filtern
keyword: Nach Stichwort suchen (serverseitige Filterung)

Schritt 5: Retry-Muster einsetzen

Bei vorübergehenden Timeouts Retry-Logik mit exponentiellem Backoff nutzen:

Retry-Strategie

Exponentielles Backoff

Erster Retry: 1 Sekunde warten, dann erneut versuchen
Zweiter Retry: 2 Sekunden warten, dann erneut versuchen
Dritter Retry: 4 Sekunden warten, dann erneut versuchen
Max. Retries: Insgesamt 3 Versuche

Wann retry

Retry bei:

Timeout-Fehlern (Verbindung kann vorübergehend langsam sein)
Netzwerkfehlern (kurzzeitige Verbindungsprobleme)
5xx-Serverfehlern (temporäre Serverprobleme)

Nicht retry bei:

401 Unauthorized (Auth-Problem, wird durch Retry nicht behoben)
403 Forbidden (Berechtigungsproblem, wird durch Retry nicht behoben)
400 Bad Request (ungültige Eingabe, wird durch Retry nicht behoben)
404 Not Found (Ressource existiert nicht)

Prompt-Muster für Retries

Explizite Retry-Anweisung

"If a tool call times out, wait 2 seconds and retry once. If it still fails, report the error."

So wird die KI angeleitet, Retry-Logik zu nutzen

Schritt 6: Große Operationen optimieren

Bei Operationen mit vielen Elementen in kleinere Batches aufteilen:

Batch-Verarbeitungsmuster

Batch-Verarbeitung

Elemente in Batches auflisten (limit: 50)
Jeden Batch getrennt verarbeiten
Auf Abschluss des Batches warten, bevor der nächste kommt
Nach jedem Batch Fortschritt melden

Beispiel: Batch-Update-Muster

Gut: Batch-Updates

"Update task titles in batches of 10:
1. Get first 10 tasks
2. Update each one
3. Wait for all 10 to complete
4. Then get next 10 tasks
5. Repeat until done"

Verhindert Überlastung der Verbindung

Schritt 7: Netzwerk und Server-Gesundheit prüfen

Manchmal liegt das Problem am Netzwerk oder am Server:

Netzwerk-Diagnose

Verbindungsgeschwindigkeit testen:

# Antwortzeit des Endpunkts testen
time curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.corcava.com/mcp

Wenn das länger als 2–3 Sekunden dauert, kann es Netzwerkprobleme geben.

Server-Gesundheitsprüfung

Serverseitige Verzögerungen

Bei hoher Serverlast:

Alle Operationen können langsamer als üblich sein
Timeouts können auch bei kleinen Abfragen auftreten
Corcava-Statusseite oder Support-Kanäle prüfen
In ruhigen Zeiten erneut versuchen

Schnell-Checkliste Optimierung

Vor der Meldung von Performance-Problemen

✅ Paginierung (limit-Parameter) für List-Operationen nutzen
✅ Filter nutzen, um Ergebnisse vor dem Abruf einzugrenzen
✅ Parallele Tool-Aufrufe vermeiden (stattdessen sequenziell)
✅ Große Operationen in Batches verarbeiten
✅ Netzwerk-Verbindungsgeschwindigkeit getestet
✅ Geprüft, dass der Server keine Probleme hat
✅ Retry-Logik für vorübergehende Fehler umgesetzt

Performance-Best-Practices

1. Immer paginieren

Nie alle Elemente auf einmal anfordern. Bei List-Operationen immer limit und offset nutzen.

2. Vor dem Abruf filtern

Serverseitige Filter nutzen (project_id, status, due_date), statt alles zu holen und clientseitig zu filtern.

3. Sequenziell statt parallel

Tool-Aufrufe wenn möglich sequenziell ausführen. Parallele Aufrufe nur für unabhängige, kleine Operationen.

4. Große Operationen in Batches

Große Operationen (z. B. 100 Aufgaben aktualisieren) in Batches von 10–20 aufteilen.

5. Cachen wo sinnvoll

Wenn Sie dieselben Daten mehrfach brauchen, die KI bitten, sie zu behalten, statt erneut abzurufen.