Vai al contenuto

Guida all'installazione

Inizia a usarlo in meno di 5 minuti. Questa guida include la configurazione per 24 client MCP, tra cui Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, e 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/claude-code-plugin
/plugin install maguyva@maguyva

Installa per il tuo account utente. Per un team, aggiungi --scope project a entrambi i comandi per registrare il plugin nel file .claude/settings.json del repository, così i colleghi lo ottengono automaticamente.

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.

Manuale (.mcp.json) — avanzato
.mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

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",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Claude Desktop supporta i server remoti solo come "connettori" OAuth tramite Impostazioni, non come voce autenticata con header in claude_desktop_config.json, quindi qui si usa il bridge mcp-remote (richiede Node.js / npx).

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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

Documentazione MCP di Cursor →

VS Code / GitHub Copilot

Aggiungi a .vscode/mcp.json nel tuo progetto (o nelle impostazioni utente):

.vscode/mcp.json
{
  "servers": {
    "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.

Documentazione MCP di VS Code / GitHub Copilot →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

Aggiungi alla tua configurazione MCP di Windsurf:

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

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

Documentazione MCP di 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"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

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

Documentazione MCP di Codex →

GitHub Copilot CLI

Aggiungi a .copilot/mcp-config.json:

.copilot/mcp-config.json
{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

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}"
      }
    }
  }
}

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

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": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di Cline →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Aggiungi alle tue impostazioni MCP di Roo Code:

mcp_settings.json
{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

Documentazione MCP di Roo Code →

Goose

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

Aggiungi alla tua configurazione di Goose:

config.yaml
extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di Goose →

LM Studio

LM Studio supporta i server MCP tramite la sua configurazione Agent. Aggiungi un nuovo server MCP in Impostazioni → Agent → MCP Servers usando il formato JSON standard mcpServers. LM Studio si connette ai server MCP tramite stdio. Vedi la documentazione →

Continue

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

Aggiungi alla configurazione di Continue (~/.continue/config.json):

config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di Continue →

Amazon Q Developer

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

Aggiungi alla tua configurazione MCP di Amazon Q:

mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di Amazon Q Developer →

PyCharm

Aggiungi a .ai/mcp/mcp.json nella radice del tuo progetto, oppure incolla in Impostazioni > Strumenti > AI Assistant > MCP:

.ai/mcp/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira 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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

Documentazione MCP di Zed →

Trae

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

.trae/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

Documentazione MCP di OpenCode →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

Aggiungi alla tua configurazione MCP di BoltAI:

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di BoltAI →

LibreChat

Aggiungi alla tua configurazione di LibreChat:

librechat.yaml
mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

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

Questo client non supporta ancora un server MCP remoto con un header di autenticazione personalizzato, quindi si connette tramite il bridge mcp-remote (richiede Node.js / npx). Maguyva funziona interamente da remoto — solo il bridge gira in locale.

Documentazione MCP di LibreChat →

Antigravity

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

Aggiungi alla tua configurazione MCP di Antigravity:

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

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

Documentazione MCP di Antigravity →

Claude Cowork

Claude Cowork usa lo stesso formato MCP degli altri client Anthropic:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Documentazione MCP di Claude Cowork →

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

Warp supporta i server MCP in Agent Mode. La configurazione viene gestita tramite l'interfaccia di Warp (Impostazioni → Agent Mode → MCP Servers) e sincronizzata via Warp Drive. Incolla il JSON standard mcpServers quando aggiungi un server. Vedi la documentazione →

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

Verifica la tua configurazione#

Dopo aver collegato, 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="...") (azione "list" o "info") per verificare la risoluzione del repository. Il server v3 non conserva lo stato, quindi le sovrascritture del repository valgono per una singola chiamata.

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#

  • Verifica che npx sia disponibile nel tuo 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#