Probleemoplossing

De meeste installatiefouten vallen in vier categorieën: de API-sleutel bereikt de server niet, de @maguyva/mcp-brug start niet, de repository kan niet worden herkend, of de client kan helemaal geen verbinding maken. Werk de sectie door die bij je symptoom past.

Elk verzoek authenticeert met je API-sleutel, verzonden als een Authorization: Bearer-header of, als een client die niet kan instellen, als een X-API-Key-header. Als tool-aanroepen worden geweigerd:

• Controleer of je sleutel begint met het mgv_-voorvoegsel.
• Controleer of je de mgv_xxxx-placeholder uit de configuratievoorbeelden hebt vervangen door je echte sleutel van app.maguyva.ai.
• Als je configuratie de sleutel leest uit MAGUYVA_API_KEY, bevestig dan dat de variabele is ingesteld in de omgeving waaruit je client daadwerkelijk start. Shell-exports die zijn toegevoegd aan ~/.zshrc of ~/.bashrc gelden pas na het herladen van de shell — en GUI-apps erven ze mogelijk helemaal niet over. Schrijf de sleutel bij twijfel rechtstreeks in de configuratie: in de Authorization-header van een native remote configuratie (Bearer gevolgd door je sleutel), of in het env-blok van een configuratie met de @maguyva/mcp-brug.
• Zorg dat de sleutel niet is verlopen of ingetrokken.

Als je client de brug @maguyva/mcp gebruikt, start deze een lokaal proces dat verbinding maakt met de externe server van Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Als de server nooit verschijnt in je client, of verschijnt en meteen weer wordt losgekoppeld:

• Controleer of npx beschikbaar is in je PATH — de brug heeft een werkende Node.js-installatie nodig. Voer npx -y @maguyva/mcp --help uit in een terminal om te bevestigen dat deze kan starten.
• Controleer de syntaxis van de MCP-configuratie van je client — een ongeldig JSON-bestand veroorzaakt in sommige clients een fout zonder melding.
• Veel clients hebben de brug helemaal niet nodig. Claude Code gebruikt de Maguyva-plugin (/plugin install maguyva@maguyva), en Cursor, VS Code, Devin Desktop en Zed verbinden native met de remote server via een Bearer-header (Zed via context_servers). De brug is voor clients die die header niet vanuit hun configuratie kunnen versturen, zoals Claude Desktop, waarvan claude_desktop_config.json alleen lokale servers start. Aangepaste connectors van Claude Desktop kunnen een authorization-requestheader versturen, maar requestheaders zijn in bèta voor een beperkt aantal organisaties.

• Controleer of de repository is verbonden en geïndexeerd in app.maguyva.ai.
• Controleer de indeling: "owner/repo" verwijst naar de standaardbranch, "owner/repo:branch" naar een specifieke branch (bijvoorbeeld "owner/repository:develop").
• Zorg ervoor dat je account toegang heeft tot de repository.
• Gebruik repository_context(action="info", repository="...") om te controleren welke repository wordt gekozen; laat de repository-parameter alleen weg wanneer je MCP-client een standaardwaarde voor het verzoek opgeeft of wanneer de sleutel toegang heeft tot precies één repository.

• Test de connectiviteit met https://maguyva.tools/mcp vanaf je machine — bedrijfsproxy's en firewalls zijn meestal de boosdoener.
• Controleer of je API-token geldig is en niet is verlopen.
• Controleer de clientconfiguratie opnieuw aan de hand van de Installatiehandleiding voor je client — de locatie en vorm van het configuratiebestand verschillen per client.

Vraag na elke wijziging je agent "Welke repositories heb ik verbonden?" — dat verifieert de verbinding van begin tot eind. Stel daarna een echte vraag over je repo; je zou antwoorden moeten zien met bestandspaden en regelnummers uit je verbonden repository.