MCP-Server testen und debuggen mit dem MCP Inspector

Der MCP Inspector ist ein leistungsstarkes Tool zum Validieren, Testen und Debuggen von MCP-Servern. Diese Anleitung zeigt, wie Sie den Inspector nutzen, um Ihren MCP-Server zu prüfen und typische Probleme zu beheben.

Was ist der MCP Inspector?

Der MCP Inspector ist ein Debugging-Tool, mit dem Sie:

Direkt mit einem MCP-Server verbinden
Verfügbare Tools und Ressourcen auflisten
Test-Toolaufrufe ausführen
Request-/Response-Payloads anzeigen
Authentifizierungsprobleme debuggen
Serverantworten validieren

MCP Inspector beziehen

Der MCP Inspector ist in der Regel verfügbar als:

Kommandozeilen-Tool
Web-Oberfläche
Teil der MCP-Entwicklungstools

In der offiziellen MCP-Dokumentation finden Sie das aktuelle Inspector-Tool und Installationsanleitungen.

Schritt 1: Mit Ihrem MCP-Server verbinden

Verbinden Sie den Inspector mit Ihrem MCP-Server. Für Corcava:

Verbindungsparameter

Endpoint-URL: https://app.corcava.com/mcp
Transport: HTTP/SSE (Remote-Server)
Authentifizierung: Bearer-Token (API-Key)

Inspector über die Kommandozeile nutzen

Bei Nutzung des Inspector über die Kommandozeile:

mcp-inspector \
  --url https://app.corcava.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

⚠️ Sicherheitshinweis

Speichern Sie Ihren API-Key niemals in der Versionskontrolle. Nutzen Sie Umgebungsvariablen oder sichere Key-Speicher. In Beispielen verwenden wir YOUR_API_KEY als Platzhalter.

Schritt 2: Verfügbare Tools auflisten

Nach der Verbindung prüfen Sie zuerst, ob Tools verfügbar sind. Der Inspector sollte eine Liste der vom Server bereitgestellten Tools anzeigen.

Erwartete Ausgabe für Corcava

Sie sollten u. a. folgende Tools sehen:

list_tasks
get_task
create_task
update_task
delete_task
list_projects
get_project
list_boards
get_board
list_task_comments
add_task_comment
start_time_tracking
stop_time_tracking
get_tracking_status

Wenn keine Tools erscheinen

Ist die Tool-Liste leer, prüfen Sie:

Ist der API-Key gültig und aktiv?
Ist die Endpoint-URL korrekt?
Gibt es Netzwerk- oder Firewall-Probleme?
Läuft der Server und ist er erreichbar?

Weitere Hilfe: Fehlerbehebungs-Leitfaden.

Schritt 3: Einen einfachen Tool-Aufruf ausführen

Testen Sie die Verbindung mit einem einfachen schreibgeschützten Tool-Aufruf. Beginnen Sie mit list_tasks:

Beispiel: list_tasks

Tool-Aufruf:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}

Erwartete Antwort:

{
  "tasks": [
    {
      "id": 123,
      "title": "Beispielaufgabe",
      "status": "open",
      ...
    }
  ],
  "total": 10
}

Antwort auswerten

Eine erfolgreiche Antwort bedeutet:

✅ Verbindung funktioniert
✅ Authentifizierung ist gültig
✅ Server verarbeitet Anfragen
✅ Tool funktioniert korrekt

Schritt 4: Authentifizierung testen

Prüfen Sie, ob die Authentifizierung funktioniert:

Test mit gültigem Schlüssel

Mit einem gültigen API-Key sollten Sie:

Erfolgreich verbinden
Tools aufgelistet sehen
Tool-Aufrufe ausführen können

Test mit ungültigem Schlüssel

Bei ungültigem/widerrufenem Schlüssel sollten Sie sehen:

401-Nicht-autorisiert-Fehler
Verbindung abgelehnt
Keine Tools aufgelistet

401-Fehlerbehebungs-Leitfaden lesen →

Corcava-Beispielablauf

Ein vollständiger Validierungsablauf am Beispiel Corcava:

Validierungs-Checkliste

Mit Server verbinden

mcp-inspector --url https://app.corcava.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Tools auflisten
Prüfen Sie, ob Corcava-Tools angezeigt werden (list_tasks, create_task usw.)
list_tasks testen
```
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}
```
Sollte eine Aufgabenliste zurückgeben (oder leeres Array, wenn keine existieren)
Test get_task
```
{
  "tool": "get_task",
  "arguments": {
    "task_id": 123
  }
}
```
Sollte Aufgabendetails zurückgeben (oder Fehler, wenn die Aufgabe nicht existiert)
create_task testen (optional – Schreibzugriff)
```
{
  "tool": "create_task",
  "arguments": {
    "title": "Testaufgabe vom Inspector",
    "description": "MCP-Verbindung testen",
    "project_id": YOUR_PROJECT_ID
  }
}
```
Sollte eine Aufgabe anlegen und das neue Aufgabenobjekt zurückgeben
⚠️ Dies legt eine echte Aufgabe an – mit Vorsicht nutzen!

Fehler interpretieren

Der Inspector hilft zu verstehen, was schiefgelaufen ist:

401 Nicht autorisiert

Bedeutung: Authentifizierung fehlgeschlagen

Häufige Ursachen:

Ungültiger API-Key
Widerrufener API-Key
Fehlender Authorization-Header
Falsches Bearer-Format

401-Fehler beheben →

403 Verboten

Bedeutung: Angemeldet, aber nicht berechtigt

Häufige Ursachen:

API-Key hat keinen Zugriff auf die angeforderte Ressource
Workspace-/Team-Berechtigung passt nicht
Ressource existiert nicht oder ist privat

403-Fehler beheben →

400 Bad Request

Bedeutung: Ungültige Anfrageparameter

Häufige Ursachen:

Fehlende Pflichtparameter
Ungültige Parametertypen
Ungültige IDs (task_id, project_id usw.)
Validierungsfehler

Validierungsfehler beheben →

Verbindung abgelehnt / Timeout

Bedeutung: Server nicht erreichbar

Häufige Ursachen:

Netzwerkverbindungsprobleme
Firewall blockiert Verbindung
Unternehmens-Proxy stört
Server ausgefallen

Verbindungsprobleme beheben →

Debugging-Checkliste

Schnelle Debugging-Checkliste

✅ Prüfen, ob API-Key in Corcava unter Einstellungen → Integrationen aktiv ist
✅ Prüfen, ob Endpoint-URL stimmt: https://app.corcava.com/mcp
✅ Authorization-Header bestätigen: Bearer YOUR_API_KEY (mit Leerzeichen)
✅ Prüfen, ob Endpoint erreichbar ist (im Browser oder mit curl testen)
✅ Prüfen, ob JSON-Syntax gültig ist (keine trailing commas, korrekte Anführungszeichen)
✅ Prüfen, ob Netzwerk/Firewall die Verbindung blockiert
✅ Server-Logs auf Fehlermeldungen prüfen
✅ Zuerst einen einfachen Nur-Lesen-Tool-Aufruf testen (list_tasks)
✅ Prüfen, ob Tool-Parameter zum erwarteten Schema passen
✅ Auf Rate-Limiting prüfen (429-Fehler)

Erweitertes Debugging

Request-/Response-Payloads anzeigen

Der Inspector zeigt die exakte Anfrage und Antwort:

Request-Payload

POST https://app.corcava.com/mcp
Headers:
  Authorization: Bearer sk_...
  Content-Type: application/json

Body:
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10,
    "project_id": 456
  }
}

Response-Payload

Status: 200 OK

Body:
{
  "tasks": [...],
  "total": 25,
  "has_more": true
}

Fehlerszenarien testen

Mit dem Inspector die Fehlerbehandlung testen:

Tool mit ungültigen Parametern aufrufen
Zugriff auf eine nicht vorhandene Ressource testen
Mit widerrufenem API-Key testen
Prüfen, ob Fehlermeldungen hilfreich sind

Häufige Probleme beheben

Problem: „Werkzeugliste ist leer“

Mögliche Ursachen:

Authentifizierung schlägt still fehl
Server liefert keine Tools zurück
Caching-Problem im Client

Lösung: Zuerst Auth prüfen, dann prüfen ob der Server antwortet. Siehe Fehlerbehebung leere Tool-Liste.

Problem: „Tool-Aufruf schlägt mit Validierungsfehler fehl“

Mögliche Ursachen:

Fehlende Pflichtparameter
Falsche Parametertypen
Ungültige IDs

Lösung: Tool-Schema prüfen, Parametertypen abgleichen. Siehe Tool-Referenz für korrekte Parameter.

Problem: „Verbindung läuft zeitlich ab“

Mögliche Ursachen:

Netzwerkverbindungsprobleme
Firewall blockiert HTTPS
Unternehmens-Proxy-Probleme
Server ist überlastet

Lösung: Endpunkt-Erreichbarkeit testen, Netzwerkeinstellungen prüfen. Siehe Fehlerbehebung Verbindung.

Inspector-Ergebnisse nutzen

Wenn der Inspector bestätigt, dass Ihr Server funktioniert:

Ergebnisse im Team teilen: Funktionierende Konfiguration dokumentieren
Client-Probleme debuggen: Inspector-Ergebnisse mit Client-Verhalten vergleichen
Änderungen validieren: Nach Server-Updates oder Konfigurationsänderungen testen
Neue Nutzer onboarden: Inspector zur Verifizierung ihres Setups nutzen

Weitere Hilfe?

Unsere Fehlerbehebungs-Anleitungen nutzen

Fehlerbehebungs-Index →Debugging-Checkliste