Windsurf MCP-Fehlerbehebung: Auth-Header werden nicht gesendet

Windsurf verbindet mit Corcava MCP, aber Tool-Aufrufe schlagen fehl? Diese Windsurf-spezifische Anleitung hilft, wenn der Server verbindet, Tool-Aufrufe aber wegen fehlender Authorization-Header mit 401 fehlschlagen. So prüfen Sie die Header-Konfiguration und erhalten ein funktionierendes Beispiel.

Das Problem verstehen

Windsurf kann die Verbindung zum MCP-Server herstellen, sendet bei Tool-Aufrufen aber den Authorization-Header nicht, sodass die Aufrufe mit 401 fehlschlagen.

Symptom-Muster

MCP-Server erscheint in Windsurf als "connected"
Tools können in der Tool-Liste erscheinen
Tool-Aufrufe schlagen aber mit 401 Unauthorized fehl
Fehler weist auf fehlenden oder ungültigen Authorization-Header hin

Schritt 1: Header-Konfiguration prüfen

Prüfen Sie, dass Ihre Windsurf-MCP-Konfiguration den Authorization-Header enthält:

Korrektes Windsurf-Konfigurationsformat

Funktionierende Windsurf-Konfiguration

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Wichtig:

Objekt headers muss vorhanden sein
Schlüssel Authorization muss exakt "Authorization" sein (Groß-/Kleinschreibung)
Wert muss "Bearer " gefolgt von Ihrem API-Schlüssel sein (mit Leerzeichen)
Keine zusätzlichen Leerzeichen oder Formatierungsfehler

Häufige Konfigurationsfehler

Hinweis: Die JSON-Beispiele unten enthalten nur zur Erklärung Inline-//-Kommentare. Diese Kommentare sind kein gültiges JSON und müssen in Ihrer echten Konfigurationsdatei entfernt werden.

Fehlendes headers-Objekt

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp"
      // Objekt "headers" fehlt
    }
  }
}

Lösung: Objekt headers mit Schlüssel Authorization hinzufügen. Hinweis: Das Beispiel enthält einen Erklärungskommentar (kein gültiges JSON) – Kommentarzeile beim Erstellen Ihrer Konfiguration entfernen.

Falscher Header-Schlüsselname

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "authorization": "Bearer YOUR_API_KEY"  // Falsche Groß-/Kleinschreibung
        // oder
        "Auth": "Bearer YOUR_API_KEY"  // Falscher Name
      }
    }
  }
}

Lösung: Exakt "Authorization" verwenden (großes A, Rest klein). Hinweis: Das Beispiel enthält Erklärungskommentare (kein gültiges JSON) – Kommentarzeilen beim Erstellen Ihrer Konfiguration entfernen.

Fehlendes Bearer-Präfix

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"  // "Bearer " fehlt
      }
    }
  }
}

Lösung: "Bearer "-Präfix einfügen: "Bearer YOUR_API_KEY". Hinweis: Das Beispiel enthält einen Erklärungskommentar (kein gültiges JSON) – Kommentar beim Erstellen Ihrer Konfiguration entfernen.

Schritt 2: Windsurf-Einstellungen-Oberfläche prüfen

Wenn Sie die Windsurf-Einstellungen-Oberfläche (nicht die JSON-Datei) nutzen, prüfen Sie, dass der Header korrekt konfiguriert ist:

Konfiguration in der Einstellungen-Oberfläche

Unter Windsurf Einstellungen → MCP-Server:

Eintrag für Corcava MCP-Server finden
Abschnitt "Headers" oder "Authentication" prüfen
Prüfen, dass der "Authorization"-Header vorhanden ist
Wert sollte sein: Bearer YOUR_API_KEY
Einstellungen speichern
Windsurf bei Bedarf neu starten

Einstellungen-Oberfläche vs. JSON-Datei

Konfigurationsquelle

Windsurf kann nutzen:

Einstellungen-Oberfläche: Über die Windsurf-Einstellungen konfiguriert
JSON-Datei: In einer Konfigurationsdatei (Speicherort variiert)

Sicherstellen, dass Sie die richtige Quelle prüfen. Änderungen in der einen können sich in der anderen nicht widerspiegeln.

Schritt 3: Header-Übertragung testen

Prüfen, ob Windsurf den Authorization-Header tatsächlich sendet:

Diagnose-Schritte

Prüfen, ob Header gesendet werden:

Einen einfachen Tool-Aufruf versuchen: "List my projects"
Bei 401 die Fehlermeldung prüfen
Fehler sollte auf fehlenden Authorization-Header hinweisen
Mit funktionierendem curl-Test vergleichen (siehe unten)

Vergleich mit curl-Test

Test mit curl (sollte funktionieren)

curl -H "Authorization: Bearer <API_KEY_PLACEHOLDER>" \
  https://app.corcava.com/mcp

Wenn curl funktioniert, Windsurf aber nicht, liegt ein Windsurf-Header-Übertragungsproblem vor.

Schritt 4: Funktionierendes Beispiel

Hier eine vollständige, funktionierende Windsurf-Konfiguration:

Vollständige funktionierende Konfiguration

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Ersetzen Sie YOUR_API_KEY durch Ihren tatsächlichen Corcava-API-Schlüssel.

Beispiel mit mehreren Servern

Bei mehreren MCP-Servern:

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CORCAVA_API_KEY"
      }
    },
    "other-server": {
      "url": "https://other-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_OTHER_API_KEY"
      }
    }
  }
}

Schritt 5: Windsurf neu starten

Nach der Korrektur der Header-Konfiguration Windsurf neu starten, damit die Änderungen greifen:

Neustart-Schritte

Konfiguration speichern (JSON-Datei oder Einstellungen-Oberfläche)
Windsurf vollständig beenden
Einige Sekunden warten
Windsurf erneut öffnen
Mit einem einfachen Tool-Aufruf testen

Schritt 6: Prüfen, ob der Header gesendet wird

Nach dem Neustart prüfen, ob Tool-Aufrufe funktionieren:

Tool-Aufrufe testen

Diese Test-Prompts ausprobieren:

"List my Corcava projects" (testet list_projects)
"Show me my tasks" (testet list_tasks)
"What MCP tools are available?" (testet Tool-Erkennung)

Wenn diese funktionieren, werden die Header korrekt gesendet. Schlagen sie mit 401 fehl, werden die Header weiterhin nicht übertragen.

Erwartetes Verhalten

Wenn die Header korrekt funktionieren:

Tool-Aufrufe gelingen (keine 401-Fehler)
Sie erhalten echte Daten (Projekte, Aufgaben usw.)
Keine "unauthorized"- oder "missing header"-Fehler

Schnell-Checkliste

Vor der Eskalation

✅ Konfiguration enthält Objekt headers
✅ Schlüssel Authorization ist exakt "Authorization" (Groß-/Kleinschreibung)
✅ Header-Wert ist "Bearer YOUR_API_KEY" (mit Leerzeichen nach Bearer)
✅ API-Schlüssel ist aktiv und nicht widerrufen
✅ Konfigurationsdatei ist gültiges JSON (bei JSON-Datei)
✅ Einstellungen in Windsurf gespeichert (bei Einstellungen-Oberfläche)
✅ Windsurf nach Konfigurationsänderungen vollständig neu gestartet
✅ Mit curl getestet – funktioniert (bestätigt, dass API-Schlüssel gültig ist)

Immer noch Probleme?

Wenn die Header nach allen Schritten weiterhin nicht gesendet werden:

Windsurf-Version prüfen (auf neueste Version aktualisieren)
Windsurf-Protokolle auf MCP-bezogene Fehler prüfen
MCP-Server-Konfiguration entfernen und erneut hinzufügen
401 Unauthorized für allgemeine Auth-Fehlerbehebung
Tools werden nicht aufgelistet bei Verbindungsproblemen
Windsurf-Support mit konkreten Fehlermeldungen kontaktieren