# Resolução de Problemas

Canonical source: https://maguyva.ai/pt-br/docs/troubleshooting

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

Resolva as falhas de configuração mais comuns do Maguyva: problemas de chave de API, questões com a bridge @maguyva/mcp, buscas de repositório e erros de conexão.

### Problemas com a chave de API

- Verifique se sua chave começa com o prefixo mgv_.
- Confira se você substituiu o placeholder mgv_xxxx dos exemplos de configuração pela sua chave real de app.maguyva.ai.
- Se sua configuração lê a chave de MAGUYVA_API_KEY, confirme que a variável está definida no ambiente de onde seu cliente realmente é iniciado. Exports de shell adicionados ao ~/.zshrc ou ~/.bashrc só valem depois de recarregar o shell, e apps com interface gráfica podem nem herdá-los. Na dúvida, escreva a chave diretamente na configuração: no header Authorization de uma configuração remota nativa (Bearer seguido da sua chave), ou no bloco env de uma configuração com a bridge @maguyva/mcp.
- Garanta que a chave não expirou nem foi revogada.

### Problemas com a bridge @maguyva/mcp

- Verifique se npx está disponível no seu PATH -- a bridge precisa de uma instalação funcional do Node.js. Rode npx -y @maguyva/mcp --help num terminal para confirmar que ela inicia.
- Confira a sintaxe da configuração MCP do seu cliente -- um JSON malformado falha silenciosamente em alguns clientes.
- Muitos clientes não precisam da bridge. O Claude Code usa o plugin do Maguyva (/plugin install maguyva@maguyva), e o Cursor, VS Code, Devin Desktop e Zed conectam ao servidor remoto nativamente com um header Bearer (Zed via context_servers). A bridge é para clientes que não conseguem enviar esse header pela configuração, como o Claude Desktop, cujo claude_desktop_config.json só inicia servidores locais. Os conectores personalizados do Claude Desktop podem enviar um header de requisição authorization, mas os headers de requisição estão em beta para um número limitado de organizações.

### Repositório não encontrado

- Verifique se o repositório está conectado e indexado em app.maguyva.ai.
- Confira o formato: "owner/repo" aponta para a branch padrão, "owner/repo:branch" aponta para uma branch específica (ex.: "owner/repository:develop").
- Garanta que sua conta tem acesso ao repositório.
- Use repository_context(action="info", repository="...") para verificar a resolução do repositório; omita o parâmetro de repositório somente quando o cliente MCP fornecer um padrão para a solicitação ou quando a chave puder acessar exatamente um repositório.

### Problemas de conexão MCP

- Teste a conectividade com https://maguyva.tools/mcp a partir da sua máquina -- proxies corporativos e firewalls costumam ser os culpados.
- Verifique se seu token de API é válido e não expirou.
- Reconfira a configuração do cliente comparando-a com o Guia de Instalação correspondente -- o local e o formato do arquivo de configuração variam por cliente.

### Verifique a correção

Depois de qualquer mudança, pergunte ao seu agente "Quais repositórios eu tenho conectados?" -- isso verifica a conexão de ponta a ponta. Depois faça uma pergunta real sobre seu repositório; você deve ver respostas com caminhos de arquivo e números de linha do seu repositório conectado.