Probleemoplossing

De meeste installatiefouten vallen in vier categorieën: de API-sleutel bereikt de server niet, de mcp-remote-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.

Problemen met API-sleutels#

Elk verzoek authenticeert met je API-sleutel, verzonden als een Authorization: Bearer-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. Zet de sleutel bij twijfel in het env-blok van de configuratie.
• Zorg dat de sleutel niet is verlopen of ingetrokken.

Problemen met de mcp-remote-brug#

De meeste gedocumenteerde clientconfiguraties starten een lokaal brugproces dat stdio-MCP-verkeer doorstuurt naar de remote server:

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

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 mcp-remote --help uit in een terminal om te bevestigen dat deze kan starten.
• Controleer de MCP-configuratiesyntax van je client — een misvormd JSON-bestand faalt in sommige clients stilzwijgend.
• Veel clients hebben de brug helemaal niet nodig. Claude Code gebruikt de Maguyva-plugin (/plugin install maguyva@maguyva), en Cursor, VS Code, Windsurf en Zed verbinden native met de remote server via een Bearer-header (Zed via context_servers). De brug is alleen voor clients zonder native ondersteuning voor remote headers, zoals de OAuth-only connectors van Claude Desktop.

Repository niet gevonden#

• Controleer of de repository is verbonden en geïndexeerd in app.maguyva.ai.
• Controleer het formaat: "owner/repo" richt zich op de standaardvertakking, "owner/repo:branch" richt zich op een specifieke vertakking (bijvoorbeeld "owner/repository:develop").
• Zorg ervoor dat uw account toegang heeft tot de repository.
• Gebruik repository_context(action="info", repository="...") om te controleren hoe de repository wordt herleid; laat de repository-parameter alleen weg wanneer uw MCP-client een standaardwaarde voor het verzoek opgeeft of wanneer de sleutel toegang heeft tot precies één repository.

MCP-verbindingsproblemen#

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

De oplossing verifiëren#

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.