# Guida all'installazione

Canonical source: https://maguyva.ai/it/docs/installation

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

Inizia a usarlo in meno di 5 minuti. Questa guida include la configurazione per 23 client MCP, tra cui Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT, e Warp, e altri ancora.

**Prerequisiti**: ti servirà una chiave API da [app.maguyva.ai](https://app.maguyva.ai) e un repository GitHub collegato.

## Configurazione dell'ambiente

Per prima cosa, imposta la chiave API in una variabile d'ambiente. Ometti `repository` quando il tuo client MCP fornisce un default per la richiesta o la chiave può accedere a un solo repository; altrimenti passalo esplicitamente.

### macOS/Linux (Bash/Zsh)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

Sostituisci `mgv_xxxx` con la tua chiave API reale da [app.maguyva.ai](https://app.maguyva.ai).

## Configurazione del client

Scegli il tuo client MCP qui sotto per le istruzioni di configurazione specifiche.

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

Maguyva usa lo standard MCP. Qualsiasi client che supporti il protocollo può collegarsi — anche se non c'è una guida ufficiale qui sopra. 23 client documentati, altri aggiunti regolarmente.

## Verifica la tua configurazione

Dopo la connessione, prova a fare al tuo agente alcune domande:

- "Quali repository ho collegato?" — verifica che la connessione funzioni
- "Come viene gestita l'autenticazione in questo codebase?" — verifica la ricerca semantica
- "Trova tutte le funzioni che chiamano il database" — verifica la ricerca delle dipendenze
- "Da cosa dipende la classe UserService?" — verifica la ricerca dei simboli

Dovresti vedere risultati con percorsi dei file e numeri di riga dal tuo repository collegato. In caso contrario, consulta la sezione [troubleshooting](https://maguyva.ai/it/docs/troubleshooting) qui sotto.

## Formato del repository

Quando specifichi i repository:

- Con branch: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- Branch predefinito: `"owner/repo"`

**Suggerimento**: usa `repository_context(action="info", repository="...")` per verificare la risoluzione del repository. Un repository specificato esplicitamente vale solo per la chiamata corrente.

## Risoluzione dei problemi

### Problemi con la chiave API

- Verifica che la tua chiave inizi con il prefisso mgv_
- Controlla che la chiave sia impostata correttamente nel tuo ambiente
- Assicurati che la chiave non sia scaduta

### Repository non trovato

- Verifica che il repository sia collegato in app.maguyva.ai
- Controlla che il formato owner/repo sia corretto
- Assicurati di avere accesso al repository

### Problemi di connessione MCP

- Se il tuo client usa il bridge @maguyva/mcp, verifica che npx sia disponibile nel PATH
- Controlla che il tuo token API sia valido e non scaduto
- Testa la connettività a https://maguyva.tools/mcp
- Controlla la sintassi della configurazione MCP del tuo client

## Prossimi passi

- Riferimento API MCP: Documentazione API completa
- Come funziona: Capisci l'ottimizzazione del contesto
- Risoluzione dei problemi: Risolvi problemi di configurazione e connessione