Den Server testen und diagnostizieren

Den Server testen und diagnostizieren

0:00 Ein Server, der nur im Gespräch mit einem Sprachmodell funktioniert, ist nicht getestet — er hatte Glück. Das klingt streng, beschreibt aber eine verbreitete Situation: Der Server läuft im eigenen Client, es sieht gut aus, und niemand weiß, was bei einer ungültigen Eingabe passiert. Dieses Modul zeigt den Weg zurück zu normalem Handwerk.

0:20 Denn in dem Teil, auf den es ankommt, ist ein MCP-Server gewöhnliche Software — und für gewöhnliche Software haben wir seit dreißig Jahren ordentliche Werkzeuge.

Den Server testen und diagnostizieren

0:30 Vier Themen: der Start über stdio und die typischen Stolperfallen dabei, der Inspector als Referenzwerkzeug, automatisierte Tests ohne Modell und — das unterschätzteste Thema des Moduls — Fehlermeldungen, mit denen ein Agent tatsächlich etwas anfangen kann. Nehmen Sie vor allem den letzten Punkt mit. Er kostet wenig und verändert das Verhalten eines Agenten deutlicher als fast alles andere.

Start über stdio und Verbindung mit dem Agenten

0:53 Fangen wir beim Start an. Der ist bei stdio ungewöhnlich, weil nicht Sie den Server starten, sondern der Client — und daraus folgen ein paar Eigenheiten. Der Client startet den Server als Unterprozess und schickt zeilengetrennte Nachrichten über die Standardstreams. Das ist so einfach, wie es klingt. Eine Sache ist dabei ungewohnt und wichtig: Dieser Prozess ist keine Sitzung.

1:15 Die Spezifikation ist da ausdrücklich — ein Client darf unabhängige Anfragen über denselben Transport mischen, und der Server darf aus der Prozessidentität keinen Zusammenhang ableiten. Wer sich beim Start etwas merkt und später darauf baut, baut auf Sand. Vier Zeilen Konfiguration, und die Fußzeile enthält den Rat, der die meiste Zeit spart: immer absolute Pfade.

1:36 Der Grund ist unangenehm und schwer zu erraten — das Arbeitsverzeichnis eines vom Client gestarteten Servers ist undefiniert. Auf dem Mac kann das der Wurzelpfad sein, weil der Client von irgendwo gestartet wurde. Ein relativer Pfad funktioniert dann beim Entwickler und bei niemandem sonst, und die Fehlermeldung hilft nicht weiter.

1:56 Diese drei Zeilen decken die überwiegende Mehrheit der Fälle ab, in denen ein Server sich nicht meldet. Besonders die dritte lohnt das Merken, weil sie so unschuldig aussieht: Die Verbindung steht, aber es passiert nichts — Ursache sind Ausgaben auf stdout. Und dann die Fußzeile, die ebenfalls überrascht: Über stdio gestartete Server erben nur einen begrenzten, plattformabhängigen Teil der Umgebungsvariablen.

2:19 Was in Ihrer Shell funktioniert, funktioniert deshalb nicht zwangsläufig, wenn der Client den Prozess startet. Der zweite Punkt kostet reihenweise Nerven: Nach einer Codeänderung wird der Client nicht vollständig neu gestartet. Bei manchen Anwendungen genügt das Schließen des Fensters nicht — der Prozess läuft weiter, und Sie testen gegen einen alten Stand.

2:40 Der dritte Punkt ist der, den man aus Bequemlichkeit macht und später bereut: Zugangsdaten im Klartext in der Client-Konfiguration. Diese Dateien werden kopiert, geteilt und gelegentlich in ein Repository eingecheckt.

Diagnose mit Inspector, Logs und Test-Client

2:53 Kommen wir zum Werkzeug, das Ihnen das Leben am meisten erleichtert — und das die meisten erst benutzen, wenn nichts mehr geht. Der MCP Inspector ist das Referenzwerkzeug zum Testen und Debuggen. Er kommt als ein Paket mit drei Gesichtern hinter einem Befehl: eine Weboberfläche als Standard, eine skriptfähige Kommandozeile und eine Terminaloberfläche.

3:14 Alle drei teilen sich denselben Kern — dieselben Transports, dieselben Konfigurationsdateien, derselbe Anmeldestand. Sie wechseln also je nach Situation, ohne etwas neu einrichten zu müssen. Die Kommandozeilenvariante ist dabei die, die viele übersehen und die am nützlichsten ist. Drei Aufrufe, und der Unterschied zwischen dem ersten und den beiden anderen ist entscheidend. Der erste öffnet die Oberfläche im Browser — gut zum Erkunden.

3:41 Die beiden anderen laufen ohne Browser, liefern maschinenlesbare Ausgabe und lassen sich in ein Skript oder in die Pipeline stecken. Das ist die Brücke zwischen manuellem Ausprobieren und automatisiertem Testen: Sie können damit prüfen, dass Ihr Server nach einem Deployment noch dieselben Werkzeuge anbietet — ohne dass ein Sprachmodell beteiligt wäre.

4:00 Hier ist die Regel, die Ihnen den Nachmittag rettet. Bei stdio fängt die Hostanwendung den Fehlerkanal automatisch mit — dorthin gehören also Ihre Ausgaben. Auf den Standardausgabekanal gehört ausschließlich das Protokoll. Und für den HTTP-Betrieb gilt etwas anderes: Dort liest niemand den Fehlerkanal mit, da brauchen Sie eigene Aggregation.

4:21 Wichtig ist der letzte Punkt: Das Logging über das Protokoll selbst ist mit der aktuellen Version abgekündigt. Wer heute neu baut, schreibt bei stdio auf stderr und nutzt sonst OpenTelemetry. Der erste Punkt ist derselbe wie vorhin, und ich wiederhole ihn absichtlich, weil er so oft passiert: Eine einzige Ausgabezeile auf dem falschen Kanal macht den Server unbrauchbar.

4:44 Der dritte ist eine Arbeitsgewohnheit — der Inspector wird erst genutzt, wenn nichts mehr geht. Umgekehrt herum ist es besser: Er ist ein Entwicklungswerkzeug, kein Notfallwerkzeug. Und der vierte ist ein Datenschutzthema, das man im Eifer der Fehlersuche gern vergisst: Logs mit Anfragetexten enthalten am Ende personenbezogene Daten.

Automatisierte Tests ohne Sprachmodell

5:04 Jetzt zur Kernaussage des Moduls. Sie ist unspektakulär und wird trotzdem selten befolgt. In dem Teil, auf den es ankommt, ist ein MCP-Server normaler Code: Er nimmt geprüfte Eingaben entgegen, ruft Fachlogik auf und formt ein Ergebnis. Genau dieser Teil lässt sich ohne Modell und ohne Protokoll testen — mit den Werkzeugen, die Sie ohnehin benutzen.

5:26 Das setzt allerdings voraus, dass Sie die Trennung aus Modul 5 eingehalten haben. Wer die Fachlogik in die Werkzeugfunktion geschrieben hat, kommt hier nicht mehr heran. Deshalb war das die wichtigste fünf Minuten Arbeit des vorigen Moduls. Vier Fälle je Werkzeug, und nur der erste ist der, den man von selbst schreibt. Gültige Eingabe — klar. Verletztes Schema, also Ablehnung mit dem richtigen Code.

5:51 Leere Ergebnismenge, die eine Aussage treffen muss und nicht mehrdeutig sein darf. Und der Ausfall der Quelle: Was antwortet Ihr Werkzeug, wenn die Anforderungsablage nicht erreichbar ist? Diese vier Fälle decken erfahrungsgemäß neunzig Prozent dessen ab, was im Betrieb schiefgeht. Und wenn ein Ausgabeschema gesetzt ist, gehört dessen Einhaltung ebenfalls in den Test.

6:14 Der erste Satz ist der wichtigste: Ein Modelldurchlauf ist nicht wiederholbar und damit kein Test. Er kann funktionieren und beim nächsten Mal nicht — ohne dass sich etwas geändert hätte. Dazu kommt, dass er langsam und teuer ist und Grenzfälle schlecht abdeckt, weil das Modell gar nicht auf die Idee kommt, einen ungültigen Wert zu schicken.

6:32 Die Lücke zwischen Ihren Unit-Tests und dem echten Client schließt die Kommandozeilenvariante des Inspectors — dort prüfen Sie das Protokoll, ohne ein Modell zu bemühen. Der erste Punkt ist menschlich und universell: Getestet wird der Erfolgsfall, weil er sich leicht schreiben lässt. Der zweite ist spezifisch für MCP und wird gern übersehen — die Schemaprüfung wird dem Client überlassen.

6:55 Das ist eine Annahme über fremde Software, und sie ist unbegründet: Der Server muss selbst prüfen. Der vierte ist ein Klassiker der Teamorganisation: Tests laufen lokal, aber nicht in der Pipeline. Dann laufen sie nach drei Wochen gar nicht mehr, und niemand merkt es.

Verwertbare Fehlermeldungen entwerfen

7:12 Und jetzt zu dem Thema, bei dem sich mit dem geringsten Aufwand am meisten gewinnen lässt. MCP kennt zwei Fehlerwege, und der Unterschied hat praktische Folgen. Protokollfehler betreffen die Anfrage selbst — unbekanntes Werkzeug, fehlerhafter Aufbau — und kommen als klassischer Fehler zurück. Ausführungsfehler des Werkzeugs stehen dagegen im Ergebnis, markiert mit einem eigenen Feld.

7:35 Der Grund für diese Zweiteilung steht in der Spezifikation: Clients sollen Ausführungsfehler an das Modell weitergeben, damit es sich selbst korrigieren kann. Protokollfehler dagegen kann ein Modell meist nicht reparieren. Achten Sie auf den Text, nicht auf die Struktur. Er nennt das Problem, und er nennt den nächsten Schritt: welches Werkzeug die gültigen Werte liefert. Das ist der ganze Trick.

7:59 Ein Agent, der diese Meldung liest, weiß sofort, was zu tun ist — er ruft das genannte Werkzeug auf und versucht es erneut. Ein Agent, der „ungültiger Wert" liest, beginnt zu raten. Der Unterschied im Aufwand beträgt eine Zeile; der Unterschied im Verhalten beträgt mehrere Runden. Drei Angaben gehören hinein, eine ausdrücklich nicht. Was war falsch — das Feld beim Namen nennen. Warum war es falsch — Bereich, Format oder Vorbedingung.

8:27 Was hilft weiter — der konkrete nächste Aufruf. Und was nicht hineingehört: interne Pfade, Zugangsdaten, Stacktraces. Das ist keine Kosmetik, sondern eine Sicherheitsfrage. Alles, was in einer Fehlermeldung steht, landet im Kontext eines Sprachmodells — und damit möglicherweise in einer Antwort an jemanden, der es nicht sehen sollte.

8:49 Der erste Punkt ist der häufigste Entwurfsfehler: Ein Eingabefehler kommt als Protokollfehler zurück und beendet damit den Versuch, statt ihn zu korrigieren. Der dritte ist der sicherheitsrelevante — der Stacktrace im Ergebnis. Und der vierte ist einer, den man erst im Betrieb bemerkt: Rechtefehler und Eingabefehler sind nicht unterscheidbar.

9:09 Dann versucht ein Agent, einen fehlenden Zugriff durch andere Parameter zu reparieren, und kommt nie an. Das kostet Runden und sieht in den Protokollen aus wie ein Modellproblem.

Übung

9:20 Zum Abschluss prüfen wir beides: ob der Server hält, was er verspricht — und ob seine Meldungen tatsächlich helfen. Die Übung hat einen zweiten Teil, der ungewohnt ist: Sie lesen Ihre eigenen Fehlermeldungen mit den Augen eines Agenten gegen. Die Frage dabei lautet nicht, ob die Meldung korrekt ist — das ist sie meistens.

9:40 Die Frage lautet, ob jemand, der nur diese Meldung hat und sonst nichts, weiß, was er als Nächstes tun soll. Sie werden überrascht sein, wie oft die Antwort nein lautet. Für beide Werkzeuge die vier Fälle: gültige Eingabe, verletztes Schema, leere Treffermenge, ausgefallene Quelle. Für den Ausfall genügt ein Schalter, der die Anforderungsablage vorübergehend unerreichbar macht — Sie müssen nichts abschalten.

10:04 Danach rufen Sie dieselben Fälle im Inspector auf und prüfen jede Meldung auf zwei Dinge: Nennt sie das betroffene Feld, und nennt sie den nächsten Schritt? Der erste Punkt ist genau die Beobachtung von eben: Die Meldung ist technisch korrekt und trotzdem nicht handlungsleitend. Der zweite ist ein Testfehler, den man leicht macht — der Ausfalltest prüft, dass eine Ausnahme fliegt, statt zu prüfen, was beim Client ankommt.

10:29 Und der vierte ist ein Ratschlag für die Wartbarkeit: Prüfen Sie nicht den Wortlaut der Meldung. Sonst bricht Ihr Test bei jeder Umformulierung, und irgendwann formuliert niemand mehr um. Damit ist der Server fertig — im nächsten Modul geht es darum, ihn gut zu schneiden.