MCP-Server lokal testen: Fehler vor dem KI-Client finden

Wie teste ich einen MCP-Server lokal, ohne ihn sofort an einen KI-Client anzuschließen? Nutze zuerst einen neutralen MCP-Prüfclient, kontrolliere die Verbindung und rufe anschließend jedes bereitgestellte Tool mit festgelegten Eingaben auf. Erst wenn dieser technische Vertrag funktioniert, lohnt sich der Test mit einem Sprachmodell.

Diese Reihenfolge trennt zwei Fehlerquellen, die im normalen KI-Client gern ineinanderlaufen. Der MCP-Server kann ein falsches Eingabeschema liefern. Das Modell kann aber ebenso ein korrektes Tool ignorieren oder unpassende Argumente erzeugen. Wenn du beides gleichzeitig testest, wird aus einer kleinen Schemaabweichung schnell eine längere Unterhaltung mit mehreren Logdateien und wenig Erkenntnis.

Ein Inspector ersetzt beim ersten Test das Sprachmodell

Als Prüfclient eignet sich der MCP Inspector. Du verbindest ihn direkt mit deinem Server und kannst dessen angebotene Funktionen untersuchen, ohne darauf zu warten, dass ein Modell das richtige Tool auswählt.

Der Inspector übernimmt dabei die Rolle eines kontrollierbaren MCP-Clients. Er stellt die Verbindung her, führt die Initialisierung durch und zeigt die vom Server gemeldeten Fähigkeiten. Tools lassen sich mit selbst gewählten Argumenten aufrufen. Je nach Server kannst du außerdem bereitgestellte Ressourcen oder Prompts prüfen.

Das ist keine vollständige Ende-zu-Ende-Prüfung. Es ist ein Smoke-Test: ein kurzer, gezielter Test, ob die wichtigsten Funktionen grundsätzlich erreichbar und ausführbar sind. Genau diese Begrenzung macht ihn für die Fehlersuche nützlich.

Definiere vor dem Start den erwarteten Vertrag

Ein erfolgreicher Verbindungsaufbau sagt wenig darüber aus, ob dein Server fachlich korrekt arbeitet. Lege deshalb vor dem Test fest, was er sichtbar machen und zurückgeben soll. Dafür genügt eine kleine Tabelle oder eine Textdatei im Projekt.

Für ein beispielhaftes Tool namens find_customer könnte der erwartete Vertrag so aussehen:

• Das Tool erscheint unter dem Namen find_customer in der Tool-Liste.
• Der Parameter query ist eine erforderliche Zeichenkette.
• Der optionale Parameter limit akzeptiert nur einen festgelegten Zahlenbereich.
• Die Rückgabe enthält stabile Felder wie ID, Anzeigename und Status.
• Eine leere Suche oder ein ungültiges Limit erzeugt einen kontrollierten Fehler.
• Ein technischer Fehler gibt keine Zugangsdaten, SQL-Abfragen oder internen Dateipfade aus.

Diese Erwartungen bilden deine Prüfbasis. Ohne sie kannst du zwar beobachten, dass „irgendetwas zurückkommt“, aber nicht entscheiden, ob das Ergebnis korrekt ist.

Prüfe zuerst Start und Transport

Starte den Server mit derselben Konfiguration, die später auch der eigentliche Client verwenden soll. Dazu gehören insbesondere der Transport, das Arbeitsverzeichnis und notwendige Umgebungsvariablen. Produktionszugänge gehören nicht in diesen Test. Verwende lokale oder ausdrücklich dafür vorgesehene Konten mit möglichst geringen Berechtigungen.

Bei einem Server über Standard-Ein- und -Ausgabe, kurz stdio, ist die Trennung der Ausgabekanäle wichtig. Die Standardausgabe ist für die Protokollkommunikation vorgesehen. Debugmeldungen, Startbanner oder ein freundliches „Server läuft“ können dort die Kommunikation beschädigen. Schreibe solche Meldungen auf die Standardfehlerausgabe oder in eine separate Logdatei. Freundlichkeit ist gut, ein gültiger Nachrichtenstrom ist besser.

Bei einem HTTP-basierten Transport kontrollierst du stattdessen, ob der konfigurierte Endpunkt erreichbar ist und der Server Protokollanfragen verarbeitet. Ein erfolgreicher gewöhnlicher Browseraufruf ist dafür kein ausreichender Nachweis. Browser und MCP-Client senden unterschiedliche Anfragen.

Bricht bereits der Verbindungsaufbau ab, bleib auf dieser Ebene. Tool-Schemas oder fachliche Datenbankabfragen spielen dann noch keine Rolle. Prüfe Prozessstart, Befehl, Pfad, Umgebungsvariablen, Port und Transportkonfiguration.

Kontrolliere die ausgehandelten Fähigkeiten

Nach dem Verbindungsaufbau folgt die Initialisierung. Dabei tauschen Client und Server Informationen über ihre unterstützten Fähigkeiten aus. Im Inspector sollte danach sichtbar sein, was dein Server tatsächlich bereitstellt.

Vergleiche die angezeigte Liste mit deinem zuvor definierten Vertrag:

• Sind alle erwarteten Tools vorhanden?
• Stimmen Namen und Beschreibungen?
• Sind Pflichtfelder tatsächlich als erforderlich markiert?
• Haben Zahlen, Zeichenketten, Listen und Objekte den richtigen Typ?
• Werden nur Funktionen veröffentlicht, die der Client verwenden darf?

Fehlt ein Tool vollständig, liegt das Problem gewöhnlich vor seiner Ausführung. Mögliche Ursachen sind eine nicht geladene Registrierung, eine bedingte Freigabe oder eine Serverkonfiguration, die eine andere Funktionsmenge bereitstellt. Eine Datenbankabfrage innerhalb des Tools musst du an dieser Stelle noch nicht untersuchen – sie wurde schließlich nie erreicht.

Rufe jedes Tool mit einer kleinen Testmatrix auf

Ein einzelner erfolgreicher Aufruf deckt nur den freundlichen Normalfall ab. Verwende für jedes Tool einige bewusst ausgewählte Eingaben. Die Testmatrix darf klein bleiben, sollte aber die Stellen berühren, an denen sich Schema, Validierung und Fachlogik unterscheiden.

1. Minimal gültige Eingabe: Sende nur die erforderlichen Argumente. Dadurch erkennst du, ob optionale Werte und Standardwerte korrekt behandelt werden.
2. Typischer Anwendungsfall: Verwende eine realistische Eingabe, wie sie später aus einem Client kommen könnte.
3. Grenzwert: Prüfe etwa die kleinste oder größte erlaubte Zahl, eine leere Ergebnismenge oder einen sehr kurzen Suchbegriff.
4. Ungültiger Typ: Übergib beispielsweise Text anstelle einer Zahl. Der Server sollte den Fehler kontrolliert melden.
5. Fehlendes Pflichtfeld: Lass ein erforderliches Argument weg und prüfe, ob die Fehlermeldung das Problem verständlich benennt.
6. Fachlich unbekannter Wert: Suche nach einer nicht vorhandenen ID. Das ist kein Protokollfehler, sondern ein erwartbarer fachlicher Fall.

Speichere die verwendeten Eingaben als reproduzierbare Testfälle. Ein Satz wie „Mit meiner Eingabe ging es gestern“ hilft bei einer späteren Änderung kaum. Ein konkretes JSON-Argument, das du erneut senden kannst, schon.

Trenne Fehler nach ihrer Schicht

Beim lokalen Test geht es nicht nur um Erfolg oder Misserfolg. Entscheidend ist, den Fehler der richtigen Schicht zuzuordnen. Die sichtbaren Symptome liefern dafür meist eine brauchbare Richtung.

• Der Server startet nicht: Untersuche Startbefehl, Laufzeitumgebung, Pfade und Konfiguration.
• Der Server startet, aber der Inspector verbindet sich nicht: Prüfe Transport, Protokollausgabe und gegebenenfalls den Endpunkt.
• Die Verbindung steht, aber ein Tool fehlt: Prüfe Registrierung, Fähigkeiten und Freigabebedingungen.
• Das Tool ist sichtbar, lehnt aber gültige Eingaben ab: Vergleiche veröffentlichtes Schema und serverseitige Validierung.
• Der Aufruf wird angenommen, liefert aber falsche Daten: Untersuche Fachlogik, Berechtigungen und angebundene Systeme.
• Im Inspector funktioniert alles, im KI-Client nicht: Prüfe die Client-Konfiguration, die Tool-Beschreibung, das Auswahlverhalten des Modells und clientseitige Freigaben.

Diese Einteilung verhindert, dass du beispielsweise die Tool-Beschreibung umformulierst, obwohl der Server ungültige Protokollausgaben erzeugt. Beide Probleme können denselben sichtbaren Effekt haben: Das Tool wird nicht benutzt. Ihre Lösungen haben ansonsten wenig miteinander zu tun.

Behandle schreibende Tools vorsichtiger

Ein lesendes Such-Tool lässt sich meist gefahrlos mit Testdaten aufrufen. Bei Funktionen, die E-Mails senden, Rechnungen erzeugen, Bestände verändern oder Datensätze löschen, reicht ein neugieriger Klick für unerwünschte Nebenwirkungen.

Teste solche Tools in einer getrennten Umgebung mit dafür vorgesehenen Daten. Falls die Fachlogik es sinnvoll zulässt, kannst du einen Vorschau- oder Bestätigungsablauf vorsehen. Ein pauschaler Parameter wie dry_run ist jedoch kein Ersatz für eine saubere Testumgebung: Er muss in jeder beteiligten Schicht korrekt umgesetzt sein, sonst beruhigt er nur optisch.

Kontrolliere bei schreibenden Tools nicht allein die MCP-Rückgabe. Prüfe auch den tatsächlichen Zustand des Zielsystems. Eine Meldung wie „Datensatz gespeichert“ ist erst belastbar, wenn der Datensatz mit den richtigen Werten vorhanden ist und ein wiederholter Aufruf keine unbeabsichtigten Duplikate produziert.

Automatisiere die stabilen Prüfungen nach dem manuellen Test

Der Inspector ist gut, um einen Server zu erkunden und Fehler sichtbar zu machen. Wiederkehrende Prüfungen solltest du anschließend automatisieren. Verwende dafür möglichst einen MCP-Client aus dem passenden SDK, statt Protokollnachrichten von Hand zusammenzubauen. So testest du den Server über dieselbe Protokollabstraktion, die auch andere Clients verwenden.

Ein kleiner Integrationstest kann den Server starten, die Verbindung initialisieren, die Tool-Liste abrufen und einen bekannten Tool-Aufruf ausführen. Sinnvolle Assertions sind:

• Das erwartete Tool ist registriert.
• Sein Eingabeschema enthält die vereinbarten Pflichtfelder.
• Eine feste Testeingabe liefert die erwartete fachliche Struktur.
• Eine ungültige Eingabe erzeugt einen kontrollierten Fehler.
• Der Aufruf überschreitet kein von dir festgelegtes Zeitlimit.

Vergleiche bei dynamischen Rückgaben nicht blind den gesamten Inhalt. Zeitstempel, zufällige IDs oder eine nicht garantierte Sortierung machen solche Tests unnötig empfindlich. Prüfe stabile Eigenschaften: Feldtypen, fachlich relevante Werte, Fehlercodes und zugesicherte Reihenfolgen.

Der abschließende KI-Test beantwortet eine andere Frage

Wenn alle technischen Prüfungen bestehen, schließt du den vorgesehenen Chat- oder Agenten-Client an. Jetzt untersuchst du nicht mehr primär, ob das Tool aufrufbar ist. Du prüfst, ob der Client und das Modell es in einer realistischen Situation sinnvoll verwenden.

Dabei zählen andere Kriterien: Erkennt das Modell anhand des Namens und der Beschreibung den richtigen Einsatzzweck? Befüllt es die Argumente passend? Fragt es bei fehlenden Angaben nach? Respektiert der Client Bestätigungs- und Berechtigungsregeln? Kann ein Mensch das Ergebnis nachvollziehen?

Ein erfolgreicher Inspector-Test garantiert diese Qualität nicht. Er schafft aber eine belastbare Ausgangslage. Wenn das Tool technisch korrekt reagiert, kannst du Beschreibungen, Prompts und Client-Verhalten gezielt untersuchen, statt gleichzeitig einen möglichen Transportfehler mitzudenken.

Ein kurzer Ablauf für den nächsten MCP-Server

1. Notiere erwartete Tools, Argumente, Rückgaben und Fehlerfälle.
2. Starte den Server mit lokaler, eingeschränkt berechtigter Konfiguration.
3. Verbinde einen MCP-Inspector und kontrolliere die Initialisierung.
4. Vergleiche die angebotenen Fähigkeiten mit deinem Vertrag.
5. Rufe jedes Tool mit gültigen, grenzwertigen und ungültigen Eingaben auf.
6. Prüfe bei schreibenden Funktionen zusätzlich den Zustand des Zielsystems.
7. Ordne Fehler der Transport-, Protokoll-, Schema- oder Fachlogik zu.
8. Überführe stabile Fälle in automatisierte Integrationstests.
9. Teste danach Auswahl und Bedienung im eigentlichen KI-Client.

Die Ausgangsfrage lässt sich damit klar beantworten: Du kannst einen MCP-Server ohne Sprachmodell testen, indem du ihn zunächst mit einem kontrollierbaren Prüfclient verbindest und seinen technischen Vertrag systematisch abarbeitest. Der KI-Client kommt erst danach hinzu. So bleibt ein kaputtes Schema ein Schemafehler – und wird nicht versehentlich zum philosophischen Problem mit dem Modell.