MCP-Server mit MCP Inspector testen und debuggen

Wenn Sie dies über die Suche nach „MCP Inspector verbindet sich nicht“ oder „Wie teste ich meinen MCP-Server?“ gefunden haben, sind Sie hier richtig. Und wenn Ihr Server sauber kompiliert, Sie aber nicht wissen, ob er sich tatsächlich korrekt verhält, bis ein echter Client daran scheitert – genau dafür ist dieser Artikel da.

MCP Inspector bietet Ihnen einen vollständigen, transportbewussten Debugging-Kreislauf für jeden MCP-Server, den Sie entwickeln oder warten. Aber nur, wenn Sie Transporttyp, Pfade und Authentifizierung von Anfang an richtig konfigurieren. Konfigurieren Sie diese drei Dinge falsch, verbringen Sie eine Stunde mit der Suche nach einem Verbindungsfehler, der nichts mit Ihrem Servercode zu tun hat.

Was bereits vor dem Verbindungsaufbau scheitert

• MCP Inspector stellt Tools, Ressourcen und Prompts getrennt dar – sodass Sie jede Protokollprimitive unabhängig validieren können.
• Der falsche Transporttyp erzeugt stille Timeouts statt hilfreicher Fehler; hier entstehen die meisten Setup-Tickets.
• HTTP-Server benötigen das Pfadsegment /mcp – wenn es fehlt, treten Routing-Fehler auf, selbst wenn der Server auf Pings antwortet.
• Ein erfolgreicher Inspector-Test bestätigt eine saubere Verbindung und korrekte Schemas, nicht jedoch, dass sich Ihr Produktionsclient identisch verhalten wird.

Voraussetzungen zum Ausführen von MCP Inspector

Stellen Sie Folgendes bereit, bevor Sie Inspector verwenden. Wenn nur eine dieser Voraussetzungen fehlt, entsteht jeweils ein anderer, verwirrender Fehlermodus.

• Node.js und npm installiert

  Inspector wird über npx gestartet, das mit npm geliefert wird. Ohne Node.js auf Ihrem Rechner schlägt der CLI-Befehl sofort mit einem Fehler wie „Befehl nicht gefunden“ fehl, der wie ein Inspector-Problem aussieht, aber keines ist. Es handelt sich um ein Laufzeitproblem.

• Ein laufender MCP-Server vor dem Verbindungsaufbau

  Dies ist ein Open-Source-Entwicklertool zum Testen und Debuggen – es startet Ihren Server nicht für Sie. Wenn der Serverprozess noch nicht läuft, versucht Inspector eine Verbindung herzustellen, läuft in einen Timeout und zeigt einen Fehler an, der wie eine Fehlkonfiguration des Transports aussieht. Der Server muss bereits laufen, bevor Inspector ins Spiel kommt.

• Ein moderner Browser für die GUI

  Inspector stellt seine Oberfläche über einen lokalen Node-Prozess auf Port 6274 bereit. Verwenden Sie Chrome oder Firefox in einer aktuellen Version. Bei älteren Browsern konnte die UI nicht gerendert werden. Das Tool ist eine browserbasierte GUI und keine Desktop-App – das überrascht viele beim ersten Mal.

• VS Code mit installierter MCP-Erweiterung (bei Verwendung der IDE-Variante)

  Der in VS Code und ähnlichen IDEs verfügbare integrierte Inspector benötigt die installierte Erweiterung, damit der Autostart funktioniert. Wenn Sie diesen Schritt überspringen und erwarten, dass der npx-Weg die in die IDE integrierte Variante startet, erhalten Sie nichts Brauchbares.

• OAuth-Zugangsdaten bereit, wenn Ihr Server Authentifizierung erfordert

  Client-ID, Client Secret und Redirect-URL müssen vorliegen, bevor Sie sich mit einem auth-geschützten Server verbinden. Wenn Sie versuchen, die Zugangsdaten erst zu klären, nachdem Inspector bereits geöffnet wurde, führt das zu unvollständigen Abläufen, Verwirrung beim Sitzungsstatus und Token-Fehlern, die wie Serverprobleme aussehen.

Erste Schritte: So starten Sie MCP Inspector

Es gibt zwei Hauptwege, Inspector zu starten. Der CLI-Weg über npx ist am direktesten und funktioniert überall, wo Node installiert ist. Der in die IDE integrierte Weg startet die Anwendung automatisch in Ihrer Entwicklungsumgebung, wenn Sie die richtige Erweiterung haben. Beide stellen dieselbe browserbasierte UI auf localhost bereit.

MCP Inspector über die npx-CLI ausführen

Öffnen Sie Ihr Terminal und führen Sie Folgendes aus:

npx @modelcontextprotocol/inspector@latest

Das ist alles für den Befehl. Danach passiert Folgendes: Ein lokaler Node-Prozess startet und Inspector stellt seine Browser-UI bereit – standardmäßig unter http://localhost:6274. Ihr Browser sollte sich automatisch öffnen. Falls nicht, navigieren Sie manuell dorthin.

Was viele in diesem Moment der ersten Schritte übersehen: Sie erwarten eine Desktop-Anwendung. Inspector ist keine. Es ist ein Browser-Tab, der von einem lokalen Server bereitgestellt wird. Das bedeutet: Wenn Sie das Terminal schließen, verschwindet die UI. Lassen Sie den Prozess laufen, während Sie die Inspector-UI verwenden.

Wenn Sie einen Serverbefehl direkt über die CLI übergeben, kann Inspector den stdio-Serverprozess auch direkt für Sie starten – zum Beispiel:

npx @modelcontextprotocol/inspector node /absolute/path/to/server.js

Das ist eine hilfreiche Abkürzung, wenn Sie MCP Inspector mit einem lokalen stdio-Server verwenden. Die Befehlszeile wird zur Verbindung.

MCP Inspector aus einer IDE oder integrierten Umgebung starten

Einige Umgebungen, darunter VS Code mit installierter MCP-Erweiterung, enthalten Inspector und starten die Browser-UI automatisch, wenn Sie ihn aus der IDE auslösen. Das offizielle Repository auf GitHub ist die maßgebliche Quelle für Architekturdetails und versionsspezifisches Verhalten.

Diese in die IDE integrierten Varianten handhaben die Claude Desktop-Integration direkter, da die Erweiterung Ihren Workspace-Kontext kennt. Die Erweiterung muss jedoch zuerst installiert sein. Wenn Sie versuchen, Inspector ohne sie aus VS Code aufzurufen, passiert nichts – kein Fehler, keine UI, kein hilfreiches Feedback. Installieren Sie die Erweiterung und lösen Sie den Start anschließend aus.

Den richtigen Transport wählen: stdio, SSE und Streamable HTTP

Hier entstehen die meisten Support-Tickets. Ein falscher Transporttyp erzeugt keinen eindeutigen Fehler. Er führt zu einem stillen Timeout oder einem Handshake-Fehler ohne Meldung, die erklärt, was schiefgelaufen ist. Sie werden auf den Ladekreis beim Verbindungsstatus starren und annehmen, dass der Server nicht läuft. Wahrscheinlich tut er das doch.

MCP unterstützt drei unterschiedliche Transportmodi, und sie sind nicht austauschbar. Die falsche Auswahl in Inspector ist genau wie der Versuch, Französisch mit jemandem zu sprechen, der nur Portugiesisch versteht – technisch dasselbe Treffen, aber es wird nichts kommuniziert.

stdio-Transport konfigurieren: Befehl, Argumente und absolute Pfade

Verwenden Sie den stdio-Transport, wenn Ihr MCP-Server als lokaler Kindprozess läuft, der direkt von Inspector oder einem Client gestartet wird. Die Serverkonfiguration in Inspector erfordert zwei Felder: Command (die ausführbare Datei) und Arguments (alle Flags oder Dateipfade).

Der mit Abstand häufigste Konfigurationsfehler bei stdio, den ich sehe: Es wird ein relativer statt eines absoluten Pfads verwendet. Relative Pfade verhindern still den Start des Serverprozesses. Der zurückgegebene Fehler lautet nicht „ungültiger Pfad“. Die Verbindung wird einfach nicht hergestellt. Verwenden Sie immer den vollständigen absoluten Pfad.

Eine gültige stdio-Konfiguration sieht folgendermaßen aus:

Übergeben Sie Umgebungsvariablen über das Feld Environment und nicht durch Änderungen an Ihrer Shell-Sitzung. Inspector muss sie auf Prozessebene sehen können.

HTTP- und SSE-Transport konfigurieren: URL-Format und der Pfad /mcp

Verwenden Sie HTTP- oder SSE-Transport, wenn Ihr MCP-Server einen HTTP-Endpunkt bereitstellt, entweder lokal oder remote. Die Cloudflare Agents-Dokumentation empfiehlt diesen Weg ausdrücklich zum Testen von Remote-MCP-Servern und Gateways, bevor Sie sie mit einem Agenten verbinden.

Das konfigurierbare URL-Feld ist unkompliziert. Die Falle ist das Pfadsegment. Für Server, die das MCP-Protokoll über HTTP implementieren, muss die URL am Ende /mcp enthalten:

https://your-server.example.com/mcp

Wenn /mcp fehlt, entstehen Routing-Fehler, die wie Verbindungsfehler aussehen, selbst wenn der Server vollständig erreichbar ist. Der Server antwortet an seiner Root-Adresse. Der MCP-Protokollendpunkt jedoch nicht. Je nachdem, wie der Server unbekannte Routen verarbeitet, erhalten Sie einen 404-Fehler oder einen stillen Timeout. Fügen Sie das Pfadsegment hinzu – es ist nicht optional.

Wenn Sie benutzerdefinierte Header bereitstellen müssen, etwa einen Authorization-Header für ein Gateway, enthält die HTTP-Transportkonfiguration von Inspector einen Bereich für Headers. Fügen Sie diese vor dem Verbindungsaufbau dort hinzu.

Authentifizierung für OAuth-geschützte MCP-Server handhaben

Authentifizierungsfehler in MCP Inspector sind fast immer Probleme in der Konfigurationsreihenfolge, keine Serverprobleme. Der Server ist erreichbar. Die Zugangsdaten existieren. Aber etwas wurde vor dem Verbindungsversuch nicht eingegeben oder nicht in der richtigen Reihenfolge eingegeben, und das Token fehlt oder ist ungültig, wenn Inspector seine erste Anfrage stellt.

Ich sehe immer wieder dieses Muster: Jemand debuggt 45 Minuten lang in der Annahme, der MCP-Server habe einen Fehler, und entdeckt dann, dass das Feld für das Proxy-Sitzungstoken die ganze Zeit leer war. Clientseitige Authentifizierungsfehlermeldungen sind oft still oder irreführend – das bedeutet, dass Sie das benötigte Signal in Inspector finden, nicht in Ihren Server-Logs.

Den MCP Inspector-Client bei Ihrem Identity Provider registrieren

Bevor Inspector einen OAuth-Ablauf abschließen kann, muss Ihr Identity Provider wissen, dass Inspector als Client existiert. Bei Auth0 und ähnlichen Anbietern bedeutet das, eine Anwendung zu erstellen, die den Inspector-Client repräsentiert, und deren Zugangsdaten zu erhalten.

Sie benötigen eine Client-ID, ein Client Secret und eine registrierte Redirect-URL. Die Redirect-URL muss exakt dem entsprechen, was Inspector erwartet – normalerweise etwas wie http://localhost:6274/oauth/callback. Eine Abweichung führt dazu, dass der Consent-Ablauf beim Redirect-Schritt mit einem allgemeinen Fehler scheitert, der wie ein Berechtigungsproblem aussieht.

Es gibt zwei Registrierungswege:

Wenn Ihr Identity Provider DCR unterstützt, kann Inspector den Registrierungsablauf selbst übernehmen. Wenn nicht, verwenden Sie die statische Registrierung. Prüfen Sie die Dokumentation Ihres Anbieters – Auth0 unterstützt beides, aber DCR erfordert ein explizites Konfigurationsflag zur Aktivierung. Wenn Sie dies falsch konfigurieren, kommt Inspector mit Zugangsdaten an, die der Anbieter nicht erkennt, und Sie erhalten einen 401-Fehler, der nichts mit Ihrem MCP-Server zu tun hat.

Was Berechtigungen angeht: Deaktivieren Sie Scopes nicht, nur um das Setup vermeintlich zu vereinfachen. Der MCP-Server benötigt bestimmte Scopes, um seine Tools korrekt bereitzustellen. Zu eng gefasste Berechtigungen führen zu unvollständigen Tool-Listen und 403-Fehlern während der Sitzung, die wie Inspector-Bugs aussehen.

Den OAuth-Ablauf abschließen und Zugangsdaten in Inspector eingeben

Geben Sie in der Inspector-UI Ihre Client-ID, Ihr Client Secret und das Proxy-Sitzungstoken im Konfigurationsbereich für die Authentifizierung ein, bevor Sie auf Connect klicken. Diese Reihenfolge ist wichtig. Zuerst auf Connect zu klicken und zu erwarten, dass Sie Zugangsdaten in einem Pop-up eingeben können, ist nicht der vorgesehene Ablauf.

Sobald Sie mit hinterlegten Zugangsdaten auf Connect klicken, löst Inspector den browserbasierten Consent-Bildschirm aus. Schließen Sie die Anmeldung ab und akzeptieren Sie die Berechtigungen. Nach diesem Redirect hält Inspector ein aktives Sitzungstoken und Sie können mit dem Tools-Tab fortfahren.

Das Proxy-Sitzungstoken ist der Teil, den die meisten übersehen. Es ist von den OAuth-Client-Zugangsdaten getrennt. Es ermöglicht der Proxy-Schicht von Inspector, die Sitzung zwischen Ihrem Browser und dem MCP-Server aufrechtzuerhalten. Lassen Sie es leer, erhalten Sie einen Fehler „Token fehlt“, obwohl der Serverendpunkt perfekt erreichbar und die OAuth-Zugangsdaten korrekt sind.

Hier beginnt das Ticket normalerweise.

MCP-Server testen: Tool-Erkennung und Ausführung von Tools

Sobald die Verbindung hergestellt ist, besteht der zentrale Test-Workflow aus drei Schritten: Connect, List Tools, Run Tool. Diese Reihenfolge ist alles. Nützlich wird sie dadurch, dass Sie die Rückgaben in jedem Schritt sorgfältig lesen.

Eine erfolgreiche Verbindung zeigt in Inspector einen grünen Statusindikator, zusammen mit Servername und sichtbarer Protokollversion. Wenn Sie das sehen, haben Sie den Test noch nicht abgeschlossen – Sie haben die Verbindung abgeschlossen. Der Test beginnt jetzt.

Mit dem Tools-Tab Tool-Schemas auflisten und prüfen

Klicken Sie im Tools-Tab auf List Tools. Inspector sendet die MCP-Anfrage tools/list an Ihren Server und rendert die Antwort – Tool-Namen, Beschreibungen und das vollständige JSON-Schema für die Parameter jedes Tools.

Hier validieren Sie mehrere Dinge gleichzeitig. Sind die Tool-Namen korrekt? Sind die Parameterbeschreibungen präzise? Werden Pflichtparameter im Schema als erforderlich angezeigt? Entspricht das Input-Schema dem, was Ihr Server tatsächlich erwartet?

Bei Servern, die mehrere Tool-Namespaces bereitstellen – häufig bei Ontology MCP-Servern oder Servern, die mehrere Backend-APIs bündeln –, bestätigt Ihnen die Tool-Liste, ob die Namespace-Grenzen funktionieren. Ein Schema, das für ein Tool den falschen Parametertyp zeigt, ist ein Server-Bug, und Sie sollten ihn lieber hier finden als in einem Produktionsagenten, der stillschweigend den falschen Typ übergibt und unbrauchbare Ergebnisse zurückerhält.

Prüfen Sie das rohe JSON-Schema direkt in Inspector, bevor Sie etwas ausführen. Das dauert 30 Sekunden und hat bereits echte Bugs aufgedeckt, die erst beim dritten oder vierten Tool-Aufruf sichtbar geworden wären.

Ein Tool ausführen und die Antwort in Echtzeit lesen

Wählen Sie ein Tool aus der Liste. Inspector rendert ein Formular auf Basis des Input-Schemas des Tools – füllen Sie die erforderlichen Parameter aus, ergänzen Sie für Ihren Test relevante optionale Felder und klicken Sie auf Run Tool.

Inspector zeigt die gesendete rohe Request-Payload sowie die empfangene rohe Response an. Lesen Sie beides. Die Anfrage zeigt Ihnen, was Inspector tatsächlich aus Ihren Parametereingaben serialisiert hat – hilfreich, um Typkonvertierungen zu erkennen. Die Antwort zeigt die vollständige Serverausgabe einschließlich aller Fehler-Payloads.

Als praktisches Erfolgskriterium: Führen Sie dasselbe Tool zweimal mit identischen Eingaben aus. Die Antworten sollten identisch sein – oder sich deterministisch unterscheiden, wenn das Tool Live-Daten abfragt. Inkonsistente Antworten bei identischen Eingaben deuten normalerweise auf ein serverseitiges Zustandsproblem oder eine Race Condition in der Tool-Implementierung hin. Führen Sie es fünfmal aus, wenn das Tool externe APIs verwendet – Rate-Limit-Verhalten und Timeout-Behandlung werden bei wiederholten Durchläufen sichtbar, anders als in einem einzelnen Test.

Chris Eberts Anleitung zum AWS Documentation MCP Server in Inspector ist eine gute Referenz dafür, wie ein sauberer Workflow für Tool-Aufrufe von Anfang bis Ende aussieht – Sie sehen die Parameter des Tools search_documentation, das Schema und wie die Antwort zu interpretieren ist, bevor Sie den Server mit einem Agenten verbinden.

📊 In der Praxis:
Ein erfolgreicher Inspector-Test bestätigt einen sauberen Verbindungsstatus, korrekte Tool-Schemas und konsistente Tool-Antworten bei erwarteten Eingaben. Er bestätigt nicht, dass Ihr Produktions-MCP-Client – eine KI-IDE, Claude Desktop oder ein Agent-Framework – Edge Cases auf dieselbe Weise handhaben wird. Inspector validiert das Protokollverhalten Ihres Servers. Der Client bringt seine eigene Interpretationsebene mit.

MCP-Server-Fehler debuggen: Logs, Anfragen und Ansichten auf Protokollebene

Wenn etwas in Inspector fehlschlägt, hilft Ihnen das Layout mit seinen Tabs dabei herauszufinden, wo der Fehler aufgetreten ist. Die Tabs sind keine Dekoration. Jeder zeigt eine andere Ebene der Protokollinteraktion.

MCP-Server stellen drei primäre Primitiven bereit: Ressourcen für Kontext, Tools für Aktionen und Prompts für vorlagenbasierte Interaktionen. Die GitHub-Community-Diskussion zur MCP-Architektur beschreibt diese klar. Inspector zeigt alle drei getrennt an, sodass Sie jeden Bereich unabhängig validieren können, statt anzunehmen, dass eine funktionierende Tool-Liste bedeutet, alles andere sei ebenfalls in Ordnung. Das tut es nicht.

Das Fehlerausgabefeld sowie Anfrage-/Antwort-Logs lesen

Das Fehlerausgabefeld zeigt serverseitige Meldungen, stderr-Ausgaben und Fehlercodes auf Protokollebene. Wenn ein Tool-Aufruf fehlschlägt, schauen Sie zuerst hier nach. Ein 401 bedeutet ein Problem mit dem Authentifizierungstoken. Ein Fehler wegen eines Schema-Mismatch bedeutet, dass Ihr Server eine Antwort zurückgibt, die nicht dem entspricht, was das Tool-Schema deklariert hat. Ein Timeout ohne Fehlercode bedeutet normalerweise, dass der Server die Anfrage erhalten und während der Ausführung nicht mehr geantwortet hat.

Die Anfrage-/Antwort-Logs zeigen die rohen MCP-Protokollnachrichten einschließlich des Initialisierungs-Handshakes. Hier prüfen Sie Payloads und Details auf Protokollebene vollständig. Wenn der Handshake einen unerwarteten capabilities-Mismatch zeigt, ist das oft die Ursache dafür, dass Tools nicht gelistet werden können, obwohl die Verbindung grün erscheint. Prüfen Sie das Log, bevor Sie annehmen, der Servercode sei fehlerhaft. Das Problem liegt häufig im Verhandlungsschritt.

Verwenden Sie den Prompts-Tab und den Resources-Tab auf dieselbe Weise: Listen Sie sie auf, prüfen Sie ihre Schemas und rufen Sie sie mit Testeingaben auf. Ein Server, der Tools korrekt auflistet, aber fehlerhafte Ressourcen-URIs zurückgibt, wird in bestimmten Agent-Workflows scheitern, die Tool-Aufrufe mit Kontextabruf kombinieren. Finden Sie das jetzt heraus, nicht nachdem Sie den Server mit einem Produktions-KI-Workflow verbunden haben.

Iterieren Sie, indem Sie den Servercode anpassen, die Verbindung erneut herstellen und erneut ausführen. Inspector speichert zwischen Serverneustarts keine Sitzungen – aber die erneute Verbindung ist schnell, und dieser Kreislauf (Code ändern → Server neu starten → Inspector erneut verbinden → Tool erneut ausführen) ist der zentrale Entwicklungsrhythmus bei jeder Arbeit mit MCP-Servern.

Verbindungsfehler und häufige Fehlkonfigurationen beheben

Wenn die Verbindung fehlschlägt, gehen Sie diese Liste durch, bevor Sie annehmen, der Server habe einen Bug:

• Server vor dem Verbindungsaufbau nicht gestartet

  Inspector kann Ihren Server in den meisten Setups nicht starten. Wenn der Prozess nicht läuft, tritt bei der Verbindung ein Timeout auf. Starten Sie den Server, bestätigen Sie, dass er Verbindungen akzeptiert, und öffnen Sie dann Inspector.

• Falscher Transporttyp ausgewählt

  Ein als HTTP konfigurierter stdio-Server oder umgekehrt erzeugt einen fehlgeschlagenen Handshake ohne hilfreiche Diagnosemeldung. Sehen Sie sich an, wie Ihr Server startet: Wenn er ein Kindprozess ist, handelt es sich um stdio. Wenn er an einen Port gebunden ist, handelt es sich um HTTP oder SSE.

• Fehlendes Pfadsegment /mcp in der URL

  Bei HTTP-/Streamable-HTTP-Transporten muss die URL für ein korrektes Protokoll-Routing mit /mcp enden. Dass ein Server an seiner Root-Adresse erreichbar ist, bedeutet nicht, dass der MCP-Endpunkt erreichbar ist.

• Authentifizierungstoken oder Proxy-Sitzungstoken vor dem Verbindungsaufbau nicht eingegeben

  Geben Sie alle Zugangsdaten ein, bevor Sie auf Connect klicken. Wenn Sie sie nach einem fehlgeschlagenen Verbindungsversuch eingeben, bleibt Inspector in einem unvollständigen Zustand, der manchmal ein vollständiges Neuladen erfordert, um zurückgesetzt zu werden.

• Relativer Pfad in der stdio-Konfiguration

  Verwenden Sie absolute Pfade für den Serverbefehl. Relative Pfade schlagen beim Prozessstart still fehl, was wie ein Verbindungsfehler aussieht.

🤔 Moment.
Inspector validiert, dass sich Ihr Server während einer Inspector-Sitzung korrekt verhält. Ihr Produktions-MCP-Client – egal ob Claude Desktop-Setup, KI-IDE oder benutzerdefinierter Agent – hat jedoch seine eigene Interpretation des Protokolls, sein eigenes Wiederholungsverhalten und seine eigene Timeout-Logik. Entwickler entdecken regelmäßig Abweichungen erst nach dem Wechsel von Inspector zu ihrem tatsächlichen Client. Inspector ist ein notwendiger Schritt, aber nicht der letzte.

Noch etwas Wissenswertes zum Debugging-Kreislauf: Wenn Ihr MCP-Server authentifizierte Aufrufe verarbeitet und Sie sporadische Authentifizierungsfehler sehen, die sich in Inspector nicht konsistent reproduzieren lassen, liegt das Problem häufig eher im Token-Scope als in der Token-Gültigkeit. Wenn Entwickler in Latenode einen MCP-Server mit einem mehrstufigen Automatisierungs-Workflow verbinden, fügen sie einen JavaScript-Node hinzu, der bei jedem Aufruf das genaue Token, die Scopes und den Request-Body protokolliert – sodass sie bei einem 401 den vollständigen Kontext an einem Ort haben, statt ihn aus drei unterschiedlichen Logs zusammensetzen zu müssen. Dieses Muster ist hier direkt nützlich: Integrieren Sie das Logging in den Workflow, bevor Sie annehmen, dass der Server defekt ist.