# Fehlerbehebung

Canonical source: https://maguyva.ai/de/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Behebe die häufigsten Maguyva-Einrichtungsfehler: Probleme mit dem API-Key, Probleme mit der Bridge @maguyva/mcp, Repository-Lookups und Verbindungsfehler.

### Probleme mit dem API-Key

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

### Probleme mit der Bridge @maguyva/mcp

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

### 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ü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.

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