Vai al contenuto

Guida all'installazione

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 / GitHub Copilot, e Devin Desktop (Windsurf), e altri ancora.

Prerequisiti: ti servirà una chiave API da 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)

# 
# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)

# 
# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

Sostituisci mgv_xxxx con la tua chiave API reale da app.maguyva.ai.

Configurazione del client

#

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

Nota sulla compatibilità: Maguyva usa lo standard MCP. Qualsiasi client con supporto MCP può connettersi allo stesso server, anche se non abbiamo ancora scritto una guida di configurazione ufficiale per esso.

Claude Code

Installa il plugin Maguyva dal marketplace di Claude Code:

Aggiungi il marketplace di Maguyva, poi installa il plugin (esegui ogni comando dentro Claude Code):

/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

/plugin install apre i dettagli del plugin, dove scegli l'ambito di installazione: solo tu (user), tutti quelli che lavorano in questo repository (project) o solo tu in questo repository (local). Questi comandi nella sessione non accettano il flag --scope.

Il plugin si autentica tramite la variabile d'ambiente MAGUYVA_API_KEY. Impostala nella tua shell:

export MAGUYVA_API_KEY=mgv_xxxx

Si consiglia direnv per progetto (.envrc) — le chiavi sono legate al repository, quindi un valore per progetto corrisponde all'accesso di ciascun progetto. Un export di shell globale funziona se una sola chiave copre tutto il tuo lavoro.

Per un team puoi invece eseguire la forma shell di entrambi i comandi dalla root del repository, fuori da Claude Code:

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

L'ambito project registra il plugin nel file .claude/settings.json del repository, che committi. Questo attiva il plugin per i colleghi ma non lo scarica, quindi ogni collega esegue il comando di installazione una volta.

Manuale (.mcp.json) — avanzato
claude mcp add 
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'
.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Claude Code →

Documentazione MCP di Claude Code →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Aggiungi al tuo file di configurazione di Claude Desktop:

claude_desktop_config.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

claude_desktop_config.json avvia solo server locali, quindi questa configurazione usa il bridge @maguyva/mcp (richiede Node.js / npx). Claude Desktop può anche raggiungere Maguyva come connettore personalizzato (Customize → Connectors) con un header di richiesta authorization, ma gli header di richiesta sono in beta per un numero limitato di organizzazioni.

Cosa aggiunge Maguyva a Claude Desktop →

Documentazione MCP di Claude Desktop →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

Aggiungi a .cursor/mcp.json nella radice del tuo progetto:

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

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Cosa aggiunge Maguyva a Cursor →

Documentazione MCP di Cursor →

VS Code / GitHub Copilot

Aggiungilo a .vscode/mcp.json nel tuo progetto, oppure al mcp.json del tuo profilo (esegui MCP: Open User Configuration):

.vscode/mcp.json 
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Questo è il formato di VS Code (chiave servers). VS Code risolve il riferimento a MAGUYVA_API_KEY dall’ambiente in cui si avvia. Il flusso Add Server ora preferisce il .mcp.json portabile (chiave mcpServers), letto anche da GitHub Copilot CLI; quel file non supporta le variabili di input né i file d’ambiente di VS Code.

Cosa aggiunge Maguyva a VS Code / GitHub Copilot →

Documentazione MCP di VS Code / GitHub Copilot →

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

Windsurf ora si chiama Devin Desktop. Aggiungilo al suo file di configurazione MCP:

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

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Devin Local, l’agente predefinito, legge questo file dalla versione 3.6; le versioni precedenti tenevano i server nel file di configurazione principale e li spostano qui all’avvio. Il vecchio agente Cascade, con cui le nuove conversazioni non si avviano, legge lo stesso file. Devin Desktop risolve il riferimento a MAGUYVA_API_KEY dall’ambiente in cui si avvia.

Cosa aggiunge Maguyva a Devin Desktop (Windsurf) →

Documentazione MCP di Devin Desktop (Windsurf) →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Aggiungi alla configurazione di Codex CLI (~/.codex/config.toml):

.codex/config.toml 
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Cosa aggiunge Maguyva a Codex →

Documentazione MCP di Codex →

GitHub Copilot CLI

Aggiungi a ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
copilot mcp add 
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a GitHub Copilot CLI →

Documentazione MCP di GitHub Copilot CLI →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Aggiungi alle impostazioni di Gemini CLI (~/.gemini/settings.json):

settings.json 
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Cosa aggiunge Maguyva a Gemini CLI →

Documentazione MCP di Gemini CLI →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Aggiungi alle tue impostazioni MCP di Cline:

cline_mcp_settings.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Cline →

Documentazione MCP di Cline →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %APPDATA%\Block\goose\config\config.yaml
Linux: ~/.config/goose/config.yaml

Aggiungi alla tua configurazione di Goose:

config.yaml 
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Goose →

Documentazione MCP di Goose →

LM Studio

In LM Studio, apri la scheda Program nella barra laterale destra, scegli Install → Edit mcp.json e aggiungi:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Documentazione MCP di LM Studio →

Continue

Salvalo come .continue/mcpServers/maguyva.yaml nel tuo workspace (oppure aggiungi la voce mcpServers a ~/.continue/config.yaml), poi imposta MAGUYVA_API_KEY in ~/.continue/.env:

.continue/mcpServers/maguyva.yaml 
name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Continue usa i server MCP solo in modalità agente. Cerca il segreto in ~/.continue/.env, poi in .continue/.env e .env del workspace, infine nell’ambiente del processo.

Cosa aggiunge Maguyva a Continue →

Documentazione MCP di Continue →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

Aggiungilo alla configurazione MCP di Kiro CLI (~/.kiro/settings/mcp.json, o .kiro/settings/mcp.json in un progetto):

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Kiro CLI ha sostituito Amazon Q Developer CLI. Durante l'installazione copia una sola volta i tuoi server da ~/.aws/amazonq/mcp.json a ~/.kiro/settings/mcp.json, e il .kiro/settings/mcp.json di un progetto ha la precedenza sul file utente.

Documentazione MCP di Kiro CLI (Amazon Q Developer CLI) →

PyCharm

Incollalo in Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add, come configurazione JSON: 

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Questa configurazione usa il bridge @maguyva/mcp (richiede Node.js / npx). Una configurazione di connessione remota nativa per questo client non è stata verificata nell’ambito di questa guida; ciò non significa che il client non supporti le connessioni remote in modo nativo. Maguyva viene eseguito interamente da remoto — solo il bridge viene eseguito in locale.

Documentazione MCP di PyCharm →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Aggiungi alle tue impostazioni di Zed (~/.config/zed/settings.json):

settings.json 
{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Zed →

Documentazione MCP di Zed →

Trae

Attiva Enable Project MCP in Settings → MCP, poi aggiungilo a .trae/mcp.json nella root del progetto:

.trae/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Documentazione MCP di Trae →

OpenCode

Aggiungi a opencode.json nella radice del tuo progetto:

opencode.json 
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Cosa aggiunge Maguyva a OpenCode →

Documentazione MCP di OpenCode →

BoltAI

macOS: ~/.boltai/mcp.json

Aggiungi alla tua configurazione MCP di BoltAI:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Questa configurazione usa il bridge @maguyva/mcp (richiede Node.js / npx). Una configurazione di connessione remota nativa per questo client non è stata verificata nell’ambito di questa guida; ciò non significa che il client non supporti le connessioni remote in modo nativo. Maguyva viene eseguito interamente da remoto — solo il bridge viene eseguito in locale.

Documentazione MCP di BoltAI →

LibreChat

Aggiungilo a librechat.yaml e imposta MAGUYVA_API_KEY nell’ambiente del server LibreChat:

librechat.yaml 
mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

Questa configurazione legge la chiave dalla variabile d'ambiente MAGUYVA_API_KEY. Impostala con la tua chiave API di app.maguyva.ai nell'ambiente da cui si avvia il client.

Documentazione MCP di LibreChat →

Antigravity

macOS: ~/.gemini/config/mcp_config.json
Windows: %UserProfile%\.gemini\config\mcp_config.json
Linux: ~/.gemini/config/mcp_config.json

Aggiungi alla tua configurazione MCP di Antigravity:

mcp_config.json 
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Antigravity →

Documentazione MCP di Antigravity →

Claude Cowork

Claude Cowork non carica i server di claude_desktop_config.json; raggiunge i server remoti come connettori personalizzati. In Customize → Connectors, aggiungi un connettore personalizzato con l’URL https://maguyva.tools/mcp, scegli No sign-in e aggiungi un header di richiesta authorization il cui valore sia Bearer seguito dalla tua chiave API. Gli header di richiesta sono in beta per un numero limitato di organizzazioni; se la finestra non ha la sezione Request headers, Cowork non può ancora autenticarsi su Maguyva. Vedi la documentazione →

ChatGPT

ChatGPT supporta server MCP remoti sui piani Business, Enterprise e Edu tramite Impostazioni → App → Crea. È richiesto un endpoint HTTPS remoto — ChatGPT non supporta server stdio locali. Consulta la guida MCP di OpenAI per la configurazione. Vedi la documentazione →

Warp

Aggiungilo a ~/.warp/.mcp.json (o a .warp/.mcp.json in un progetto), oppure incollalo in Settings → Agents → MCP servers → + Add:

~/.warp/.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Sostituisci mgv_xxxx con la tua chiave API da app.maguyva.ai.

Cosa aggiunge Maguyva a Warp →

Documentazione MCP di Warp →

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

#

Correlati

Da leggere