Risoluzione problemi

La maggior parte dei problemi di configurazione rientra in quattro categorie: la chiave API non raggiunge il server, il bridge mcp-remote 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.

Problemi con la chiave API#

Ogni richiesta si autentica con la tua chiave API, inviata come header Authorization: Bearer. 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, metti la chiave nel blocco env della configurazione.
• Assicurati che la chiave non sia scaduta o sia stata revocata.

Problemi con il bridge mcp-remote#

La maggior parte delle configurazioni client documentate avvia un processo bridge locale che inoltra il traffico MCP stdio al server remoto:

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

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 mcp-remote --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, Windsurf e Zed si connettono al server remoto in modo nativo con un header Bearer (Zed tramite context_servers). Il bridge serve solo per i client senza supporto nativo per gli header remoti, come i connettori solo-OAuth di Claude Desktop.

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