Risoluzione problemi

La maggior parte dei problemi di configurazione rientra in quattro categorie: la chiave API non raggiunge il server, il bridge @maguyva/mcp non si avvia, il repository non può essere risolto, oppure il client non riesce proprio a connettersi. Segui la sezione che corrisponde al tuo sintomo.

Ogni richiesta si autentica con la tua chiave API, inviata come header Authorization: Bearer oppure, se un client non è in grado di impostarlo, come header X-API-Key. Se le chiamate agli strumenti vengono rifiutate:

• Verifica che la tua chiave inizi con il prefisso mgv_.
• Controlla di aver sostituito il segnaposto mgv_xxxx negli esempi di configurazione con la tua chiave reale da app.maguyva.ai.
• Se la tua configurazione legge la chiave da MAGUYVA_API_KEY, conferma che la variabile sia impostata nell'ambiente da cui il tuo client viene effettivamente avviato. Gli export di shell aggiunti a ~/.zshrc o ~/.bashrc si applicano solo dopo aver ricaricato la shell — e le app GUI potrebbero non ereditarli affatto. In caso di dubbio, scrivi la chiave direttamente nella configurazione: nell'header Authorization di una configurazione remota nativa (Bearer seguito dalla tua chiave), oppure nel blocco env di una configurazione con il bridge @maguyva/mcp.
• Assicurati che la chiave non sia scaduta né revocata.

Se il tuo client usa il bridge @maguyva/mcp, avvia un processo locale che si connette al server remoto di Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Se il server non compare mai nel tuo client, oppure compare e si disconnette subito:

• Verifica che npx sia disponibile nel tuo PATH — il bridge richiede un'installazione funzionante di Node.js. Esegui npx -y @maguyva/mcp --help in un terminale per confermare che possa avviarsi.
• Controlla la sintassi della configurazione MCP del tuo client — un file JSON malformato fallisce silenziosamente in alcuni client.
• Molti client non hanno affatto bisogno del bridge. Claude Code usa il plugin Maguyva (/plugin install maguyva@maguyva), e Cursor, VS Code, Devin Desktop e Zed si connettono al server remoto in modo nativo con un header Bearer (Zed tramite context_servers). Il bridge serve ai client che non possono inviare quell'header dalla loro configurazione, come Claude Desktop, il cui claude_desktop_config.json avvia solo server locali. I connettori personalizzati di Claude Desktop possono inviare un header di richiesta authorization, ma gli header di richiesta sono in beta per un numero limitato di organizzazioni.

• Verifica che il repository sia connesso e indicizzato in app.maguyva.ai.
• Controlla il formato: "owner/repo" punta al branch predefinito, "owner/repo:branch" punta a un branch specifico (ad es. "owner/repository:develop").
• Assicurati che il tuo account abbia accesso al repository.
• Usa repository_context(action="info", repository="...") per ispezionare la risoluzione del repository; ometti il parametro repository solo quando il tuo client MCP fornisce un default per la richiesta o la chiave può accedere a un solo repository.

• Testa la connettività a https://maguyva.tools/mcp dalla tua macchina — proxy aziendali e firewall sono i soliti colpevoli.
• Controlla che il tuo token API sia valido e non scaduto.
• Ricontrolla la configurazione del client seguendo la sezione «Guida all'installazione» relativa al tuo client: la posizione e la struttura del file di configurazione variano da un client all'altro.

Dopo ogni modifica, chiedi al tuo agente "Quali repository ho connessi?" — questo verifica la connessione end to end. Poi fai una domanda vera sul tuo repository; dovresti vedere risposte con percorsi di file e numeri di riga dal tuo repository connesso.