Fehlerbehebung

Die meisten Einrichtungsfehler lassen sich vier Kategorien zuordnen: Der API-Key erreicht den Server nicht, die mcp-remote-Bridge startet nicht, das Repository kann nicht aufgelöst werden, oder der Client kann sich überhaupt nicht verbinden. Arbeite den Abschnitt durch, der zu deinem Symptom passt.

Probleme mit dem API-Key#

Jede Anfrage authentifiziert sich mit deinem API-Key, gesendet als Authorization: Bearer-Header. Wenn Tool-Aufrufe abgelehnt werden:

• Überprüfe, dass dein Key mit dem Präfix mgv_ beginnt.
• Überprüfe, dass du den Platzhalter mgv_xxxx aus den Konfigurationsbeispielen durch deinen echten Key von app.maguyva.ai ersetzt hast.
• Wenn deine Konfiguration den Key aus MAGUYVA_API_KEY liest, stelle sicher, dass die Variable in der Umgebung gesetzt ist, aus der dein Client tatsächlich gestartet wird. Shell-Exports in ~/.zshrc oder ~/.bashrc gelten erst nach einem Neuladen der Shell — und GUI-Apps übernehmen sie möglicherweise gar nicht. Im Zweifel den Key in den env-Block der Konfiguration eintragen.
• Stelle sicher, dass der Key nicht abgelaufen oder widerrufen wurde.

Probleme mit der mcp-remote-Bridge#

Die meisten dokumentierten Client-Konfigurationen starten einen lokalen Bridge-Prozess, der stdio-MCP-Traffic an den Remote-Server weiterleitet:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

Wenn der Server in deinem Client nie erscheint oder erscheint und sich sofort wieder trennt:

• Überprüfe, dass npx in deinem PATH verfügbar ist — die Bridge braucht eine funktionierende Node.js-Installation. Führe npx -y mcp-remote --help in einem Terminal aus, um zu bestätigen, dass sie starten kann.
• Überprüfe die MCP-Konfigurationssyntax deines Clients — eine fehlerhafte JSON-Datei schlägt bei manchen Clients stillschweigend fehl.
• Viele Clients brauchen die Bridge überhaupt nicht. Claude Code verwendet das Maguyva-Plugin (/plugin install maguyva@maguyva), und Cursor, VS Code, Windsurf und Zed verbinden sich nativ mit einem Bearer-Header direkt mit dem Remote-Server (Zed über context_servers). Die Bridge ist nur für Clients ohne native Remote-Header-Unterstützung gedacht, wie etwa die reinen OAuth-Connectors von Claude Desktop.

Repository nicht gefunden#

• Überprüfe, dass das Repository in app.maguyva.ai verbunden und indexiert ist.
• Überprüfe das Format: "owner/repo" zielt auf den Standard-Branch, "owner/repo:branch" zielt auf einen bestimmten Branch (z. B. "owner/repository:develop").
• Stelle sicher, dass dein Konto Zugriff auf das Repository hat.
• Prüfen Sie mit repository_context(action="info", repository="...") die Repository-Auflösung. Lassen Sie den Repository-Parameter nur weg, wenn Ihr MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann.

MCP-Verbindungsprobleme#

• Teste die Verbindung zu https://maguyva.tools/mcp von deinem Rechner aus — Firmen-Proxys und Firewalls sind die üblichen Verdächtigen.
• Überprüfe, dass dein API-Token gültig und nicht abgelaufen ist.
• Überprüfe die Client-Konfiguration erneut anhand der Installationsanleitung für deinen Client — Speicherort und Struktur der Konfigurationsdatei unterscheiden sich je nach Client.

Überprüfe die Lösung#

Frag deinen Agenten nach jeder Änderung "Welche Repositories habe ich verbunden?" — das überprüft die Verbindung end-to-end. Stell dann eine echte Frage zu deinem Repo; du solltest Antworten mit Dateipfaden und Zeilennummern aus deinem verbundenen Repository sehen.