Resolução de Problemas

A maioria das falhas de configuração cai em quatro grupos: a chave de API não está chegando ao servidor, a bridge mcp-remote não está iniciando, o repositório não pode ser resolvido, ou o cliente não consegue se conectar de jeito nenhum. Siga a seção que corresponde ao seu sintoma.

Problemas com a chave de API#

Toda requisição se autentica com sua chave de API, enviada como um header Authorization: Bearer. Se as chamadas de ferramenta forem rejeitadas:

• 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, coloque a chave no bloco env da configuração.
• Garanta que a chave não expirou nem foi revogada.

Problemas com a bridge mcp-remote#

A maioria das configurações de cliente documentadas inicia um processo local de bridge que encaminha o tráfego MCP via stdio para o servidor remoto:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

Se o servidor nunca aparece no seu cliente, ou aparece e desconecta na hora:

• Verifique se npx está disponível no seu PATH — a bridge precisa de uma instalação funcional do Node.js. Rode npx -y mcp-remote --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, Windsurf e Zed conectam ao servidor remoto nativamente com um header Bearer (Zed via context_servers). A bridge só é necessária para clientes sem suporte nativo a header remoto, como os conectores somente-OAuth do Claude Desktop.

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