# Guia de Instalação

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

Comece a usar em menos de 5 minutos. Este guia inclui configuração para 23 clientes MCP, incluindo 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 mais.

**Pré-requisitos**: você vai precisar de uma chave de API de [app.maguyva.ai](https://app.maguyva.ai) e de um repositório GitHub conectado.

## Configuração do Ambiente

Primeiro, defina sua chave de API em uma variável de ambiente. Omita `repository` quando o cliente MCP fornecer um padrão para a solicitação ou quando a chave puder acessar exatamente um repositório; caso contrário, informe-o explicitamente.

### 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
```

Substitua `mgv_xxxx` pela sua chave de API real de [app.maguyva.ai](https://app.maguyva.ai).

## Configuração do Cliente

Escolha seu cliente MCP abaixo para instruções de configuração específicas.

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

O Maguyva usa o MCP padrão. Qualquer cliente que suporte o protocolo pode se conectar — mesmo que não haja um guia oficial acima. 23 clientes documentados, com mais sendo adicionados regularmente.

## Valide Sua Configuração

Depois de conectar, tente fazer algumas perguntas ao seu agente:

- "Quais repositórios eu tenho conectados?" — verifica se a conexão está funcionando
- "Como a autenticação é tratada nesta base de código?" — testa a busca semântica
- "Encontre todas as funções que chamam o banco de dados" — testa a busca de dependências
- "De que a classe UserService depende?" — testa a busca de símbolos

Você deve ver resultados com caminhos de arquivo e números de linha do seu repositório conectado. Caso contrário, consulte [troubleshooting](https://maguyva.ai/pt-br/docs/troubleshooting) abaixo.

## Formato do Repositório

Ao especificar repositórios:

- Com branch: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- Branch padrão: `"owner/repo"`

**Dica**: use `repository_context(action="info", repository="...")` para verificar a resolução do repositório. Uma substituição explícita do repositório vale apenas para a chamada atual.

## Solução de Problemas

### Problemas com a chave de API

- Verifique se sua chave começa com o prefixo mgv_
- Verifique se a chave está configurada corretamente no seu ambiente
- Certifique-se de que a chave não expirou

### Repositório não encontrado

- Verifique se o repositório está conectado em app.maguyva.ai
- Verifique se o formato owner/repo está correto
- Certifique-se de que você tem acesso ao repositório

### Problemas de conexão MCP

- Se o cliente usa a bridge @maguyva/mcp, verifique se npx está disponível no PATH
- Verifique se o seu token de API é válido e não expirou
- Teste a conectividade com https://maguyva.tools/mcp
- Verifique a sintaxe de configuração MCP do seu cliente

## Próximos Passos

- Referência da API MCP: Documentação completa da API
- Como Funciona: Entenda a otimização de contexto
- Solução de Problemas: Corrija problemas de configuração e conexão