· reAPI Team
MCP-Tool-Aufrufe: Warum sie nach einem API-Wechsel fehlschlagen
Verfolge MCP-Tool-Aufrufe von der Erkennung über die Modellunterstützung und Ausführung bis zu den zurückgegebenen Ergebnissen. Finde Fehler bei der API-Migration, bevor du es erneut versuchst oder kostenpflichtige Aufgaben einreichst.

Der MCP-Server zeigt „Verbunden“ an. Trotzdem antwortet der Assistent weiterhin mit gewöhnlichem Text oder behauptet, eine Aufgabe geprüft zu haben, ohne ein Ergebnis anzuzeigen. Wenn das nach einem Wechsel der Modell-APIs angefangen hat, prüfe zuerst, was über die neue Verbindung übertragen wurde, bevor du den Prompt erneut änderst.
Ein verbundener Tool-Server und ein Modell, das Tools anfordern kann, sind getrennte Bestandteile der Anwendung. MCP legt die Erkennung und den Aufruf von Tools fest. Der Host muss dem Modell anschließend die passenden Tools bereitstellen, jeden angeforderten und zulässigen Aufruf ausführen und das Ergebnis zurücksenden.[1][2] Ein Erfolg beim ersten Schritt belegt nicht, dass auch der letzte erfolgreich war.
Finde das Tool in der Liste, die der Client erhalten hat
Beginne mit einem Tool. Lies das tatsächliche Ergebnis von tools/list, das der betroffene Client erhalten hat, einschließlich weiterer Seiten, falls vorhanden. Halte Name, Beschreibung und Eingabeschema fest. Eine Verbindungsanzeige zeigt nicht, ob genau dieses Tool erkannt wurde.
Fehlt es, prüfe den ausgewählten Server, den unterstützten Transport und die Authentifizierung im Prozess, der den Client ausführt. Die aktuelle MCP-Spezifikation erlaubt, dass verfügbare Tools je nach bereitgestellter Autorisierung variieren.[1] Dass ein Tool sichtbar ist, beweist daher nicht, dass derselbe Aufrufer alle vom Server angebotenen Tools sehen kann.
Bei einer reAPI-Verbindung verwendet der dokumentierte Server Remote Streamable HTTP mit einem benutzerdefinierten Bearer-Autorisierungsheader. Ein Client, der nur OAuth-Anmeldung ohne benutzerdefinierte Header anbietet, kann sich mit dieser Konfiguration nicht verbinden.[3] Wiederholte Anweisungen an das Modell können keinen Transport und keinen Anmeldemechanismus bereitstellen, den der Client nicht unterstützt.
Unterscheide bei der Untersuchung die Zugangsdaten des Modellanbieters von denen des Tool-Servers. Sie können zu verschiedenen Verbindungen gehören. Ein neuer Modell-API-Schlüssel behebt keine fehlenden Zugangsdaten für die MCP-Verbindung; neue MCP-Zugangsdaten fügen einem ausgehenden Modellaufruf auch keine Tools hinzu. Notiere sichere Konfigurationskennungen statt der Geheimnisse.
Vergleiche das erkannte Schema mit dem, was das Modell sieht
Nimm dieses fiktive schreibgeschützte Tool als Beispiel. Es sucht anhand einer ID eine vorhandene Aufgabe. Das Fragment veranschaulicht einen Erkennungseintrag; es ist weder eine vollständige Protokollantwort noch ein von uns bereitgestelltes Tool:
{
"name": "inspect_task_example",
"description": "Look up the status of an existing task.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": { "type": "string" }
},
"required": ["task_id"]
}
}Prüfe nun die serialisierte Anfrage, die an das Modell gesendet wurde. Das Tool-Format kann sich vom MCP-Format inputSchema unterscheiden, aber Name, Eigenschaft und Bedeutung der Pflichtfelder müssen die Umwandlung überstehen. Sendet der Host den Tool-Namen ohne die Eigenschaft task_id oder die Liste der Pflichtfelder, hat das Modell einen anderen Vertrag erhalten.
Das ist eine konkrete Stelle, an der du den Adapter korrigieren kannst. Ein längerer Prompt mit der Aufforderung, das Tool „korrekt zu verwenden“, stellt das fehlende Schema nicht wieder her. Vergleiche die beiden Objekte, bevor du weitere Anweisungen hinzufügst oder erneut den Anbieter wechselst.
Vergleiche in diesem Beispiel task_id an drei Stellen: in der erkannten Eigenschaft, in der Eigenschaft für das Modell und in den Argumenten, die der Host später weiterleitet. Überall muss derselbe erforderliche Zeichenfolgenwert gemeint sein. Benennt ein Konverter das Feld an einer Stelle in id um, lässt es an einer anderen aber als task_id stehen, ist eine Abweichung entstanden. Verwende den vom Modell-API unterstützten Wrapper für die Definition und erhalte dabei Name, Typ und Pflichtstatus des Feldes.
Prüfe auch veraltete Definitionen. Ein auf dem Server umbenanntes Tool kann in einer zwischengespeicherten Client-Liste weiterhin unter seinem alten Namen stehen. Speichere die Definition, die in der fehlgeschlagenen Anfrage verwendet wurde. So vergleichst du, was das Modell tatsächlich erhalten hat, und nicht das neueste Schema auf einer separaten Dokumentationsseite.
Hat das Modell ein Tool angefordert oder nur beschrieben, dass es eines verwendet?
Lies die Struktur der Modellantwort. Der gewöhnliche Satz „Ich prüfe die Aufgabe“ ist kein strukturierter Tool-Aufruf. Eine Ablehnung, eine normale Antwort, ein fehlerhafter Aufruf und ein gültiger Aufruf erfordern unterschiedliche nächste Schritte, selbst wenn alle über erfolgreiche HTTP-Antworten eingetroffen sind.
Wenn die Anfrage das richtige Schema enthielt, aber kein Aufruf zurückkam, prüfe die Modellunterstützung, die Einstellungen zur Tool-Auswahl und die verwendete Route. Eine automatische Tool-Auswahl kann eine gewöhnliche Antwort erzeugen; eine Einstellung, die Tools deaktiviert, kann die Auswahl verhindern. Auch die Unterstützung strengerer Werte für die Tool-Auswahl unterscheidet sich je nach Modell.[2] Behandle nicht jedes Ausbleiben eines Aufrufs als fehlerhafte Argumente.
Das Routing ist relevant, wenn ein Vermittler einen Anbieter auswählt. OpenRouter dokumentiert require_parameters, um Routen auf Anbieter zu beschränken, die alle angeforderten Parameter unterstützen. Die standardmäßigen Parameterpräferenzen, auch für Tools, sind nicht dasselbe wie eine strenge Filterung.[4] Prüfe Fallback-Modelle und die Route, über die die Anfrage bedient wurde. Übernimm diese anbieterspezifische Option nicht in eine andere API und gehe von einem gleichwertigen Verhalten aus.
Wenn ein strukturierter Aufruf eingetroffen ist, beende die Fehlersuche bei der Auswahl und verfolge diesen Aufruf weiter. Das Modell hat eine Aktion angefordert; die Anwendung muss sie noch ausführen. Das Tool-Calling-Tutorial von OpenRouter weist die Ausführung ausdrücklich dem Aufrufer zu, nicht dem Modell.[2]
Verfolge dieselbe Aufruf-ID durch Ausführung und Rückgabe
Hier folgt der nächste Teil des fiktiven Beispiels im Nachrichtenformat von Chat Completions. IDs und Ergebnis sind erfunden. Es handelt sich um Nachrichtenfragmente zur Prüfung, nicht um ein Skript, das eine Anfrage sendet:
[
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_example_1",
"type": "function",
"function": {
"name": "inspect_task_example",
"arguments": "{\"task_id\":\"example_task_7\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_example_1",
"content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
}
]Zwischen diesen beiden Nachrichten muss der Host den zulässigen Aufruf an das Tool weiterleiten und dessen Ergebnis erhalten. Eine Modellantwort mit call_example_1 beweist nicht, dass die Weiterleitung stattgefunden hat. Suche nach dem passenden Ausführungsprotokoll und dem Serverergebnis.
Wartet die Ausführung auf eine Genehmigung, behalte diesen Zustand bei. Hat der Nutzer abgelehnt, ist die abgelehnte Operation das Ergebnis; ein anderes Tool oder ein erneuter Versuch ist keine Erlaubnis, die Entscheidung zu umgehen. Wurde die Genehmigung erteilt, aber der Aufruf nie weitergeleitet, untersuche die Ausführungslogik des Hosts.
Vergleiche auch den weitergeleiteten Tool-Namen und die Argumente mit dem angeforderten Aufruf. In diesem Beispiel muss die Suche example_task_7 erhalten. Verwendet der Host versehentlich erneut die vorherige Aufgaben-ID, wurde eine andere Suche ausgeführt, selbst wenn der Server ein gültiges Ergebnis zurückgibt. Speichere die Zuordnung zwischen Modell-Aufruf-ID, Tool-Aufruf und zurückgegebenem Inhalt. So wird ein Ergebnis zur falschen Aufgabe sichtbar, bevor das Modell es in eine selbstsichere Antwort einbaut. Korrigiere diese lokale Zuordnung, ohne das Schema des Quell-Tools zu ändern oder seinen Zugriff auszuweiten.
Warte bei gestreamten Aufrufen, bis die Argumente vollständig sind. OpenRouter beschreibt, Deltas nach Aufrufindex zu sammeln und erst zu parsen, wenn die Argumentzeichenfolge vollständig ist.[2] Ein frühes Fragment, das mitten in task_id endet, ist noch kein gültiges JSON. Unterscheide das von einer vollständigen Argumentzeichenfolge, die weiterhin ungültig ist.
Die zweite Nachricht oben enthält dieselbe Aufruf-ID wie die erste. In der dokumentierten Chat-Completions-Schleife folgt auf den Tool-Aufruf des Assistenten für jeden angeforderten Aufruf eine Ergebnismeldung.[2] Wenn mehrere Aufrufe zurückgegeben wurden, erhalte jede Identität und jedes Ergebnis. Wird unter jeder ID dasselbe Ergebnis gesendet, kann das Gespräch vollständig wirken, während den angeforderten Aktionen falsche Daten zugeordnet werden.
Angenommen, das Tool hat tatsächlich processing zurückgegeben, aber die nächste Modellanfrage ließ die Tool-Nachricht aus. Die Ausführung war erfolgreich; das Modell hat das Ergebnis nie erhalten. Oder der Host hat das Ergebnis bei der Umwandlung durch eine leere Zeichenfolge ersetzt. Ein Modellwechsel würde dieselbe fehlende Information im Gespräch belassen.
Vergleiche das tatsächliche Serverergebnis mit der ausgehenden Fortsetzung. Bewahre relevante Inhalte und Fehler auf, nicht nur ein Erfolgskennzeichen im Client-Protokoll. Beurteile die endgültige Formulierung des Modells anhand des Ergebnisses, das es erhalten hat; die Behauptung, es habe die Aufgabe geprüft, ersetzt diesen Nachweis nicht.
Tool-Fehler sichtbar halten
MCP unterscheidet zwischen Protokollproblemen und Fehlern bei der Tool-Ausführung. Ein unbekanntes Tool oder eine fehlerhafte Protokollanfrage kann einen JSON-RPC-Fehler erzeugen. Ein Fehler bei der Tool-Ausführung kann stattdessen mit isError: true zurückgegeben werden.[1] Bewahre diesen Unterschied und die zugehörige Meldung bei der Umwandlung des Ergebnisses für das Modell.
Bei der Beispielsuche darf ein Fehler, dass nicht auf die Aufgabe zugegriffen werden kann, nicht zu einem leeren Erfolgsstatus werden. Erhält das Modell nur eine leere Zeichenfolge, fehlen ihm die Informationen, um den Fehler zu erklären oder einen passenden nächsten Schritt zu wählen. Prüfe die Umwandlung, bevor du die endgültige Antwort verantwortlich machst.
Eine nützliche lokale Prüfung besteht darin, gespeicherte oder synthetische Nachrichten durch den Adapter zu schicken: ein normales Ergebnis, einen Ausführungsfehler und zwei Aufrufe mit unterschiedlichen IDs. Prüfe, ob Inhalt, Fehlerbedeutung und Identität erhalten bleiben. Damit testest du, wie der Adapter diese Testfälle verarbeitet; du belegst nicht, dass ein entferntes Modell das Tool korrekt auswählt. Eine Live-Modellbewertung kann weiterhin Inferenzkosten verursachen, auch wenn das ausgewählte Tool nur lesend arbeitet.
Gestalte die beiden synthetischen Ergebnisse sichtbar unterschiedlich und gib sie dann in umgekehrter Reihenfolge zu den Anfragen zurück. Der Host sollte sie anhand ihrer Aufruf-IDs zuordnen, nicht anhand der Reihenfolge ihres Eingangs. Identische Testergebnisse können diesen Fehler verbergen, weil ihr Austausch im nächsten Modelleingang keinen sichtbaren Unterschied hinterlässt.
Schließe die Verbindungsprüfung ab, bevor du eine Generierung einreichst
Beginne bei reAPI mit den für das Problem relevanten Tools, die nichts einreichen. Die MCP-Referenz führt Modellermittlung, Schemaabruf, Schätzung, Aufgabenstatus und Kontostandsabfragen als Vorgänge auf, die keine Credits kosten. submit_task ist davon getrennt: Ein Aufruf, der eine Aufgabe erstellt, wird für diese Aufgabe berechnet.[3]
Der dokumentierte Server ist zustandslos und akzeptiert eine JSON-RPC-Nachricht pro HTTP-Anfrage, keine Batch-Arrays. Medieneingaben benötigen öffentliche HTTP- oder HTTPS-URLs statt Base64 oder Data-URIs.[3] Prüfe diese tatsächlichen Schnittstellenanforderungen, wenn der Ausführungsschritt fehlschlägt; reiche nicht wiederholt Generierungen als Verbindungstest ein.
Bewahre eine zurückgegebene Aufgaben-ID auf und frage diese bestehende Aufgabe ab. Laut reAPI-Dokumentation ist das Einreichen einer Aufgabe nicht idempotent: Eine wiederholte Erstellungsanfrage kann eine weitere kostenpflichtige Aufgabe erzeugen.[3] Bei einer verlorenen Antwort auf die Einreichung brauchst du eine Annahmeprüfung, statt anzunehmen, dass nichts geschehen ist.
Beim fiktiven Suchlauf ist der Migrationsvergleich abgeschlossen, wenn du zeigen kannst, an welcher Stelle die Nachrichten erstmals voneinander abweichen: bei der Erkennung, der modellseitigen Definition, dem strukturierten Aufruf, der Ausführung oder dem zurückgegebenen Ergebnis. Behebe genau diese Abweichung und wiederhole dieselbe harmlose Prüfung. Halte Server, Modell, Client-Version und protokollierten Aufruf zusammen fest, damit die nächste Person nachvollziehen kann, was geprüft wurde, ohne sich auf eine Verbindungsanzeige zu verlassen.
Quellen
- Model Context Protocol, Tools specification, revision 2026-07-28. Gelesen am 16. November 2026. Protokollversionen und Serverimplementierungen können abweichen.
- OpenRouter, „Tool Calling Across Any Model: Write the Loop Once, Swap the Model String“, offizielles Tutorial, aktualisiert am 24. September 2026. Gelesen am 16. November 2026.
- reAPI, MCP Server documentation. Geprüft am 16. November 2026. Für diesen Leitfaden wurden keine Live-Generierung und kein Client-Kompatibilitätstest durchgeführt.
- OpenRouter, „Provider Routing“, offizielle Dokumentation, Abschnitte „Requiring Providers to Support All Parameters“ und „Default parameter preferences“. Gelesen am 16. November 2026.