# Risoluzione problemi

Canonical source: https://maguyva.ai/it/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).

Risolvi i problemi di configurazione più comuni di Maguyva: problemi con la chiave API, problemi con il bridge @maguyva/mcp, ricerche di repository ed errori di connessione.

### Problemi con la chiave API

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

### Problemi con il bridge @maguyva/mcp

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

### Repository non trovato

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

### Problemi di connessione MCP

- 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 rispetto alla Guida all'installazione per il tuo client -- la posizione e la forma del file di configurazione differiscono per ciascun client.

### Verifica la correzione

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.