Fehlerbehebung

Die meisten Einrichtungsfehler lassen sich vier Kategorien zuordnen: Der API-Key erreicht den Server nicht, die @maguyva/mcp-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.

Jede Anfrage authentifiziert sich mit deinem API-Key, gesendet als Authorization: Bearer-Header oder – wenn ein Client keinen setzen kann – als X-API-Key-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 direkt in die Konfiguration schreiben: bei einer nativen Remote-Konfiguration in den Authorization-Header (Bearer gefolgt von deinem Key), bei einer Konfiguration mit der @maguyva/mcp-Bridge in den env-Block.
• Stelle sicher, dass der Key nicht abgelaufen oder widerrufen wurde.

Falls dein Client die Bridge @maguyva/mcp nutzt, startet sie einen lokalen Prozess, der sich mit dem entfernten Server von Maguyva verbindet:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

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 @maguyva/mcp --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, Devin Desktop und Zed verbinden sich nativ mit einem Bearer-Header direkt mit dem Remote-Server (Zed über context_servers). Die Bridge ist für Clients gedacht, die diesen Header nicht aus ihrer Konfiguration senden können, etwa Claude Desktop, dessen claude_desktop_config.json nur lokale Server startet. Benutzerdefinierte Connectors von Claude Desktop können einen Authorization-Request-Header senden, aber Request-Header sind eine Beta für eine begrenzte Zahl von Organisationen.

• Ü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üfe mit repository_context(action="info", repository="...") die Repository-Auflösung. Lass den Repository-Parameter nur weg, wenn dein MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann.

• 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.

Frag deinen Agent 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.