Inspektion und Debugging von MCP: MCP Jam, Inspector, Logs

1. Wozu braucht man überhaupt einen MCP‑Inspektor

Stellen Sie sich vor, Sie debuggen ein Frontend, dürfen aber die DevTools nicht öffnen. Ungefähr so fühlt sich das Leben ohne MCP‑Inspektor an. Das MCP‑Protokoll läuft „unter der Haube“ von ChatGPT und dem Apps SDK; wenn Sie nur auf die Antwort im Chat schauen und denken: „Warum sieht es mein Tool nicht?“, schießen Sie im Grunde ins Blaue.

Inspektoren wie der MCP Inspector (offiziell) oder MCP Jam sind spezielle MCP‑Clients für Entwickler. Sie können:

• sich mit Ihrem MCP‑Server genau so verbinden, wie es ChatGPT tut;
• den Handshake / die capabilities durchlaufen;
• die Liste von tools/resources/prompts anfordern;
• jedes Tool manuell mit beliebigen Argumenten aufrufen;
• rohe JSON‑Nachrichten anzeigen (Requests / Replies / Errors).

Im Grunde ist das „Postman für MCP, aber mit Köpfchen“. Im Unterschied zu einem normalen REST‑Client kennt der Inspektor die MCP‑Spezifika: er versteht tools/list, tools/call, kann Argument‑Schemas anzeigen und unterstützt mitunter sogar OAuth‑Flows für geschützte Server.

Ohne Inspektor sieht Debugging so aus: Sie starten ChatGPT, versuchen, eine App aufzurufen, sehen „Error talking to app“ oder dass das Tool gar nicht aufgerufen wird, und beginnen zu raten: Wollte das Modell das Tool nicht verwenden, ist Ihr MCP nicht gestartet oder gibt es einen JSON‑Fehler? Mit dem Inspektor können Sie jede Schicht separat prüfen: zuerst MCP‑Server eins zu eins mit dem Inspektor, danach die Kopplung ChatGPT ↔ MCP.

2. Mini‑Überblick über Inspektoren: MCP Inspector, Jam & Co.

In der Praxis werden Sie meist zwei Arten von Inspektoren für MCP verwenden.

Zum einen den offiziellen MCP Inspector aus dem Repository des Model Context Protocol. Das ist eine Web‑App (in der Regel eine React‑SPA), die entweder lokal oder via npx/Docker gestartet wird und sich per HTTP/SSE mit Ihrem MCP‑Server verbinden kann.

Zum anderen gibt es MCP Jam‑ähnliche Inspektoren, die häufig zusätzlichen Komfort rund um OAuth bieten. Sie können selbst .well-known/oauth-protected-resource lesen, daraus authorization_endpoint und token_endpoint extrahieren, den PKCE‑Flow durchlaufen und anschließend autorisiert den MCP ansprechen.

MCP Jam wurde von den Entwicklern auf Basis des MCP Inspector erstellt. Wenn der MCP Inspector den Minimalumfang an Debug‑Funktionen bietet, deckt MCP Jam alles ab, was Sie als Entwickler in der täglichen Arbeit mit MCP brauchen. Ich persönlich empfehle, gleich mit MCP Jam zu starten, um späteres Umlernen zu vermeiden.

Für unseren Kurs besteht der Unterschied darin, dass:

• der Basis‑Inspector immer nützlich ist, selbst für einen einfachsten, ungeschützten MCP‑Server;
• MCP Jam (oder ein Pendant) dann hilfreich wird, wenn Sie Module zu Authentifizierung und Autorisierung erreichen.

Aber die Grundidee ist dieselbe: Es ist ein gewöhnlicher MCP‑Client, der nur das, was ChatGPT „stumm“ erledigt, schön sichtbar macht.

3. Typisches Vorgehen mit einem MCP‑Inspektor

Gehen wir ein Standardszenario durch: Sie haben ein neues Tool in Ihrem MCP‑Server geschrieben und wollen sicherstellen, dass es wirklich funktioniert.

In der letzten Vorlesung haben Sie bereits einen minimalen MCP‑Server hochgezogen. Jetzt ergänzen wir das um einen systematischen Prüfansatz: Wir lassen den vollständigen Zyklus „Server → Inspektor → JSON‑Logik“ Schritt für Schritt durchlaufen.

Schritt 1 — MCP‑Server starten

Das haben Sie bereits zuvor getan: Angenommen, Sie haben ein Skript npm run mcp-dev:

# Beispiel für den Start eines MCP‑Servers
npm run mcp-dev
# unter der Haube etwa so: ts-node src/mcp-server.ts

Wichtig ist, dass der Server auf Ihrem gewählten Transport lauscht: im Kurs ist das meist ein HTTP‑Endpoint /mcp auf einem bestimmten Port, zum Beispiel http://localhost:4001/mcp.

Schritt 2 — MCP Jam starten

Ein zweites Terminal:

# eine der Möglichkeiten, MCP Jam zu starten
npx @mcpjam/inspector@latest
# bei Bedarf können Sie --port 4002 usw. hinzufügen

Danach öffnet sich der Inspektor im Browser, meist unter http://localhost:6274 oder einem ähnlichen Port.

Auf dem Startbildschirm von MCP Jam werden Sie nach der URL des MCP‑Servers gefragt. Sie geben ein:

http://localhost:4001/mcp

oder Ihre getunnelte URL, wenn Sie bereits alles über ngrok laufen lassen.

Schritt 3 — Handshake / Capabilities

Sobald MCP Jam verbunden ist, macht es automatisch dasselbe wie ChatGPT:

1. Es sendet eine Initialisierungsanfrage (initialize) mit Client‑Daten.
2. Es erhält eine Antwort mit der Protokollversion und den capabilities Ihres Servers.
3. Anhand der capabilities erkennt es, ob der Server tools, resources, prompts und weitere Features unterstützt.

Im UI wird das gewöhnlich etwa so dargestellt:

Connected
Protocol: mcp/2025-06-18
Capabilities:
- tools: list, call
- resources: list, read
- prompts: list, get

Wenn der Inspektor schon in diesem Schritt nicht verbinden kann (connection refused, CORS, 500 usw.), sehen Sie sofort den Fehler und wissen: Das Problem liegt definitiv nicht beim Modell und nicht bei ChatGPT, sondern in Ihrem Serverteil oder im Netzwerk.

Schritt 4 — Discovery: tools/resources/prompts ansehen

Nach einem erfolgreichen Handshake ruft der Inspektor normalerweise selbst Methoden wie tools/list, resources/list, prompts/list auf, um die Seitenleiste zu füllen. Sie sehen:

• eine Liste der Tools mit Beschreibungen und JSON‑Schema der Eingabeargumente;
• eine Liste der Ressourcen, gruppiert nach Collections/Pfaden;
• eine Liste der Prompts mit Kurzbeschreibungen.

Wenn Sie gerade ein neues Tool hinzugefügt haben, es aber nicht in der Liste erscheint, ist es auf dem Server falsch registriert oder der Server wurde nicht mit dem aktualisierten Code gestartet. Das ist hier viel einfacher zu erkennen, als zu rätseln, warum ChatGPT Ihr Tool „nicht aufrufen will“.

4. Tools manuell mit MCP Jam aufrufen

Die nützlichste Funktion von MCP Jam ist der manuelle Aufruf von Tools. Das ist Ihr persönliches UI für tools/call.

Tool auswählen und Argumente ausfüllen

Nehmen wir an, Sie haben im vorherigen Modul das Tool suggest_gifts geschrieben:

// irgendwo in src/mcp/tools/suggestGifts.ts
export const suggestGiftsTool = {
  name: "suggest_gifts",
  description: "Schlägt Geschenkideen nach Alter, Budget und Interessen vor",
  inputSchema: {
    type: "object",
    properties: {
      age: { type: "number" },
      budget: { type: "number" },
      interests: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["age", "budget"]
  },
  // handler wird separat definiert
};

In MCP Jam klicken Sie auf suggest_gifts. Rechts öffnet sich ein Formular, das anhand des inputSchema generiert wurde. Dort füllen Sie etwa Folgendes aus:

{
  "age": 30,
  "budget": 100,
  "interests": ["Spiele", "Bücher"]
}

und klicken auf „Call“ oder eine entsprechende Schaltfläche.

Der Inspektor sendet eine MCP‑Anfrage tools/call, und Sie sehen sofort:

• die rohen JSON‑Daten der Anfrage (was genau an den Server gesendet wird);
• die rohen JSON‑Daten der Antwort (result oder error);
• gegebenenfalls eine praktische Vorschau des Ergebnisses.

JSON‑Logs im Inspektor lesen

Der Inspektor zeigt gewöhnlich etwas in dieser Art:

// Request
{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "suggest_gifts",
    "arguments": {
      "age": 30,
      "budget": 100,
      "interests": ["Spiele", "Bücher"]
    }
  }
}

// Reply
{
  "id": "1",
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1) Gesellschaftsspiel … 2) Geschenkgutschein für eine Buchhandlung …"
      }
    ]
  }
}

Wenn Ihr Handler mit einer Ausnahme abstürzt, sehen Sie ein error im JSON‑RPC‑Stil:

{
  "id": "1",
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "TypeError: Cannot read properties of undefined ..."
  }
}

Wichtig: Hier sehen Sie die Protokollebene. Wenn das Antwortformat nicht dem entspricht, was Apps SDK/ChatGPT erwartet, erkennen Sie das, bevor Sie sich über „Bugs in GPT“ ärgern.

5. Ressourcen und Prompts debuggen

Tools sind nicht alles, was MCP kann. Sie wissen bereits, dass es außerdem resources und prompts gibt.

Über den Inspektor können Sie:

• die Liste der Ressourcen öffnen (resources/list) und ihre Metadaten ansehen;
• eine konkrete Ressource lesen (resources/read) und prüfen, ob die zurückgegebenen Daten korrekt sind;
• die Suche über Ressourcen ausführen (falls implementiert);
• vorgefertigte Prompts und deren Text ansehen.

Beispielsweise, wenn Sie eine Ressource gift_catalog haben:

// Pseudocode zur Registrierung einer Ressource
registerResource({
  uri: "resource://giftgenius/catalog",
  name: "Geschenkkatalog",
  mimeType: "application/json",
  handler: async () => {
    return JSON.stringify(giftCatalogData);
  }
});

Im Inspektor sehen Sie diese Ressource, klicken darauf und können den JSON sofort einsehen. Wenn sich herausstellt, dass der JSON ungültig ist oder der MIME‑Typ merkwürdig, fangen Sie das ab, bevor ChatGPT darüber stolpert, wenn es versucht, die Daten zu lesen oder in ein Widget einzubetten.

6. Logs des MCP‑Servers: was, wo und wie loggen

MCP Jam ist gut, aber nicht ausreichend: Sie brauchen Logs des MCP‑Servers selbst. Ohne sie wird jeder Betrieb zum Lotteriespiel.

Was loggen

Das sinnvolle Minimum:

• jede eingehende MCP‑Nachricht (Request/Notification) mit:
  • Zeit;
  • Methode (tools/call, tools/list usw.);
  • Namen des Tools (falls vorhanden);
  • gekürzten Argumenten (ohne sensible Daten);
• jede ausgehende Antwort:
  • Status (Erfolg / Fehler);
  • Ausführungszeit;
  • verkürzte Ergebnisdarstellung oder zumindest den Typ;
• technische Fehler:
  • JSON‑Parsing;
  • unerwartete Ausnahmen in Handlers.

Dabei ist es sehr wichtig, PII und Secrets nicht vollständig zu loggen: Token, Passwörter, vollständige Texte vertraulicher Anfragen. In Empfehlungen für Logging im Produktivbetrieb wird explizit geraten, Daten mit gekürzter PII zu loggen.

Wohin loggen: stdout / stderr

Bei MCP gibt es eine wichtige Anforderung: JSON‑Nachrichten müssen über den „richtigen Kanal“ laufen, und alle Debug‑Logs über einen anderen. Wenn Sie z. B. einen Transport über stdout/stderr verwenden, dann gilt:

• JSON‑RPC‑Nachrichten müssen auf stdout ausgegeben werden;
• alle console.log, console.error usw. müssen auf stderr gehen.

Wenn Sie JSON und Text‑Logs in einem Stream mischen, kann der Client (MCP Jam oder ChatGPT) die Nachrichten schlicht nicht parsen, weil mitten im JSON plötzlich eine Zeile wie Server started at http://localhost:4001 auftaucht. Das ist einer der häufigsten Fehler bei MCP‑Servern.

Im HTTP‑Szenario ist das Problem einfacher, aber das Prinzip bleibt: Die HTTP‑Antwort muss reines JSON enthalten, und alle Logs gehören in die Konsole/Datei, aber nicht in den Antwort‑Body.

Ein einfacher Logger für einen TypeScript‑MCP‑Server

Fügen wir unserem hypothetischen MCP‑Server einen kleinen Logger hinzu:

// src/logger.ts
export function logRequest(method: string, details: unknown) {
  console.error(
    JSON.stringify({
      level: "info",
      type: "request",
      method,
      details,
      ts: new Date().toISOString(),
    })
  );
}

export function logError(method: string, error: unknown) {
  console.error(
    JSON.stringify({
      level: "error",
      type: "error",
      method,
      error: String(error),
      ts: new Date().toISOString(),
    })
  );
}

Und im Handler für Tools:

// src/mcp-server.ts (Ausschnitt)
server.setRequestHandler("tools/call", async (req) => {
  logRequest("tools/call", {
    name: req.params?.name,
    // hier besser nicht die gesamte Payload, sondern nur sichere Felder loggen
  });

  try {
    const result = await handleToolCall(req);
    return result;
  } catch (e) {
    logError("tools/call", e);
    throw e;
  }
});

So sehen Sie in der Konsole strukturierte JSON‑Logs, die Sie anschließend leicht über ts oder eine zusätzliche requestId miteinander in Beziehung setzen können.

7. Zusammenspiel: MCP Jam + Logs

Die richtige Debug‑Strategie für MCP sieht fast immer so aus:

1. Sie reproduzieren das Problem im Inspektor: Sie sehen, dass tools/list eine leere Liste zurückgibt, tools/call abstürzt, die JSON‑Antwort seltsam ist usw.
2. Gleichzeitig sehen Sie in die Logs des MCP‑Servers: was er beim Start schreibt, welche Fehler er für jede Nachricht ausgibt, ob es einen Stacktrace gibt.
3. Sie gleichen id, method, ts in den Logs mit dem ab, was der Inspektor zeigt.

Beispiel: Sie sehen im Inspektor:

{
  "error": {
    "code": -32603,
    "message": "Internal error"
  }
}

Und parallel in den Logs:

{
  "level": "error",
  "type": "error",
  "method": "tools/call",
  "error": "TypeError: Cannot read properties of undefined (reading 'age')",
  "ts": "2025-11-21T10:15:12.345Z"
}

Schon ist die Diagnose klar: Irgendwo im Handler erwarten Sie age, aber Schema/Argumente sind anders.

8. Mini‑Checkliste „Ist der MCP‑Server bereit für die Integration mit der App?“

Bevor Sie den MCP‑Server an eine echte ChatGPT‑App hängen, ist es praktisch, mit dem Inspektor eine kleine Checkliste durchzugehen.

Erstens sollten Handshake und Capabilities fehlerfrei funktionieren. MCP Jam sollte anzeigen, dass der Server die benötigten Entitäten unterstützt: mindestens tools und, falls verwendet, resources / prompts.

Zweitens sollte die Liste der tools/resources/prompts im Inspektor mit dem Satz an Tools, Ressourcen und Prompts übereinstimmen, den Sie als implementiert ansehen. Tippfehler in name, vergessene Registrierungen usw. fallen hier sofort auf.

Drittens sollten Aufrufe von Tools mit gültigen Argumenten stabil ein korrektes result zurückgeben. Am besten probieren Sie mehrere typische Fälle (Anfragen, auf die Sie im Produktivbetrieb tatsächlich setzen).

Viertens sollten Aufrufe mit ungültigen Argumenten aussagekräftige error-Antworten im JSON‑RPC‑Stil liefern und nicht mit 500 abstürzen. Fehlt z. B. ein Pflichtparameter, wäre eine strukturierte Fehlermeldung sinnvoll, die ChatGPT später in eine verständliche Benutzerinformation umwandeln kann.

Fünftens sollten die Server‑Logs dabei nicht die Konsole mit Gigabytes an Stacktraces zuschütten. Fehler sollten strukturiert sein, und sensible Daten sauber herausgefiltert.

Wenn all das im Inspektor erfüllt ist, können Sie den MCP‑Server deutlich beruhigter mit dem Apps SDK verbinden und im Dev Mode mit Widgets experimentieren.

9. Typische Bugs im MCP‑Server und wie man sie mit dem Inspektor findet

Gehen wir nun das Interessanteste durch — was am häufigsten kaputtgeht und wie man es erkennt.

Konfiguration und Verbindung

Manchmal scheint es, als würde der „Server nicht funktionieren“, dabei lauscht er schlicht nicht auf dem richtigen Port oder Endpoint. Der Inspektor meldet dann ehrlich connection refused oder kann gar nicht verbinden. Häufige Ursachen: falsche URL (z. B. /mcp statt /api/mcp), Port wird von einem anderen Prozess belegt, Tunnel läuft nicht oder CORS blockiert Anfragen.

Ungültiges JSON / Vermischung von Logs und Protokoll

Eine der schmerzhaftesten Geschichten ist, wenn Sie console.log("Server started") auf stdout ausgeben, während darüber JSON‑RPC‑Nachrichten laufen sollen. Der Client erwartet reines JSON, bekommt aber Text + JSON, versucht zu parsen und scheitert am Formatfehler.

Die Lösung ist einfach: strikt trennen, was in den Protokoll‑Stream (stdout oder HTTP‑Antwort‑Body) gehört, und was in die Logs (stderr oder separate Logdatei).

Schema und Tool‑Implementierung passen nicht zusammen

Ein weiterer Klassiker: Im inputSchema haben Sie das eine deklariert, im Code erwarten Sie etwas anderes. Zum Beispiel sagt das Schema: age — Zahl, interests — optionales Array von Strings, aber der Code versucht arguments.interests.toLowerCase(). Das Modell (und der Inspektor) senden interests dann ehrlich als null oder lassen das Feld ganz weg — und an dieser Stelle crasht es.

Der Inspektor lässt Sie explizit sehen, welches JSON tatsächlich in tools/call geht, und das mit Ihrem Code abgleichen.

Falsche Namen von tools/resources

Wenn Sie in capabilities / tools/list ein Tool als suggest_gifts_v2 exportieren, im Apps‑Manifest oder Widget jedoch suggest_gifts erwarten, wird „Tool nicht gefunden“ Sie bis zum Projektende begleiten. Im Inspektor ist das anhand der Liste der Tools und ihrer name‑Felder sofort sichtbar, ohne zu rätseln, was GPT denkt.

Langsame oder hängende Tools

Wenn der Aufruf eines Tools im Inspektor 30 Sekunden dauert und dann in ein Timeout läuft, sollten Sie nicht hoffen, dass ChatGPT besser reagiert. Der MCP‑Inspektor hilft zu erkennen, an welcher Phase Sie ausbremsen: Netzaufruf, Datenbank, externer API‑Dienst. In den Logs ist es hilfreich, Start‑ und Endzeitpunkt jeder Anfrage zu haben, um Ausreißer sofort zu sehen.

10. Typische Fehler bei Inspektion und Debugging von MCP

Fehler Nr. 1: MCP nur über ChatGPT debuggen wollen.
Viele Entwickler schließen MCP zuerst an eine App an, sehen, dass „etwas nicht funktioniert“, und beginnen, Prompts, Tool‑Beschreibungen und manchmal sogar die Modellversion zu ändern. Währenddessen startet der MCP‑Server überhaupt nicht oder tools/list ist leer. Fangen Sie immer mit dem Inspektor an: Wenn dort alles schlecht aussieht, ist das Modell unschuldig.

Fehler Nr. 2: JSON‑RPC und Logs im selben Stream mischen.
Wenn der MCP‑Client reines JSON erwartet, Sie aber Debug‑Zeilen auf stdout drucken, ist das Ergebnis vorhersehbar — das Parsing bricht, der Inspector zeigt seltsame Fehler. Logs müssen getrennt laufen (stderr, Dateien, externe Logsysteme), Protokollnachrichten strikt in ihrem eigenen Kanal.

Fehler Nr. 3: Capabilities und Tool‑Liste nicht ansehen.
Oft „verschwindet“ ein Tool einfach deshalb, weil Sie vergessen haben, es zu registrieren oder die entsprechende Capability zu aktivieren. Wenn man nicht auf capabilities und tools/list im Inspektor schaut, kann man lange denken, das Modell sei schuld — dabei stimmt die Registrierungslogik nicht.

Fehler Nr. 4: Schemafehler und JSON‑Diskrepanzen ignorieren.
Wenn inputSchema und tatsächliches JSON auseinanderlaufen, verhalten sich Modell und Inspektor konsequenterweise merkwürdig. Wenn Sie nicht auf die rohen JSON‑Nachrichten im Inspektor schauen und das Schema nicht validieren, tauchen diese Fehler an den unerwartetsten Stellen auf.

Fehler Nr. 5: alles ungefiltert loggen, einschließlich PII und Tokens.
Im Eifer des Debuggings beginnt man leicht, den kompletten Request‑Body zu loggen — inklusive personenbezogener Daten oder Secrets. Im Produktivbetrieb wird das zur Zeitbombe: Leaks, Compliance‑Probleme usw. Loggen Sie nur, was wirklich für die Diagnose nötig ist, und in gekürzter/anononymisierter Form.

Fehler Nr. 6: das Problem nicht mit minimalen Fällen reproduzieren.
Manchmal zeigt sich ein Bug in einem komplexen Dialog über ChatGPT, und der Entwickler versucht, genau diesen zu debuggen. Viel effektiver ist es, dasselbe Szenario im Inspektor mit ein bis zwei MCP‑Requests nachzustellen, den Einfluss von Prompts, Gesprächshistorie und der „Laune“ des Modells auszuschließen.