How do I troubleshoot 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

How do I troubleshoot 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

How do I troubleshoot problemas de conexão mcp?

Verifique se o npx está disponível no seu 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

Como faço para validar se minha configuração MCP do Maguyva está funcionando?

Depois de conectar, faça ao seu agente perguntas que exercitem diferentes modos de recuperação: "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.

Como especifico um repositório nas requisições MCP do Maguyva?

Omita o repositório 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, use "owner/repo" para o branch padrão (por exemplo, "owner/repository") ou "owner/repo:branch" para um branch específico (por exemplo, "owner/repository:develop").

Guia de Instalação

Comece a usar em menos de 5 minutos. Este guia inclui configuração para 24 clientes MCP, incluindo Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, e Windsurf, e mais.

Pré-requisitos: você vai precisar de uma chave de API de 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)#

# 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

Substitua mgv_xxxx pela sua chave de API real de app.maguyva.ai.

Configuração do Cliente#

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

Nota de compatibilidade: O Maguyva usa o MCP padrão. Qualquer cliente com suporte a MCP pode se conectar ao mesmo servidor, mesmo que ainda não tenhamos escrito um guia de configuração oficial para ele.

Claude Code

Instale o plugin do Maguyva pelo marketplace do Claude Code:

Adicione o marketplace do Maguyva e instale o plugin (rode cada comando dentro do Claude Code):

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

Instala para a sua conta de usuário. Para um time, adicione --scope project aos dois comandos para versionar o plugin no .claude/settings.json do repositório, para que os colegas de time já recebam ele automaticamente.

O plugin se autentica pela variável de ambiente MAGUYVA_API_KEY. Defina-a no seu shell:

export MAGUYVA_API_KEY=mgv_xxxx

O direnv (.envrc) por projeto é recomendado — as chaves são vinculadas ao repositório, então um valor por projeto corresponde ao acesso de cada projeto. Um export global no shell funciona se uma única chave cobrir todo o seu trabalho.

Manual (.mcp.json) — avançado

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do 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

Adicione ao seu arquivo de configuração do 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

O Claude Desktop só oferece suporte a servidores remotos como "conectores" OAuth via Settings, não como uma entrada autenticada por cabeçalho no claude_desktop_config.json, então isso usa a ponte mcp-remote (requer Node.js / npx).

Documentação MCP do Claude Desktop →

Cursor

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

Adicione ao .cursor/mcp.json na raiz do seu projeto:

.cursor/mcp.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Cursor →

VS Code / GitHub Copilot

Adicione ao .vscode/mcp.json do seu projeto (ou às configurações de usuário):

.vscode/mcp.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do VS Code / GitHub Copilot →

Windsurf

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

Adicione à sua configuração MCP do Windsurf:

mcp_config.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Windsurf →

Codex

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

Adicione à sua configuração do 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}"

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Codex →

GitHub Copilot CLI

Adicione ao .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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do GitHub Copilot CLI →

Gemini CLI

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

Adicione às suas configurações do Gemini CLI (~/.gemini/settings.json):

settings.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do 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

Adicione às suas configurações MCP do 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
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Esse cliente ainda não oferece suporte a um servidor MCP remoto com cabeçalho de autenticação personalizado, então a conexão passa pela ponte mcp-remote (requer Node.js / npx). O Maguyva roda inteiramente na nuvem — só a ponte roda localmente.

Documentação MCP do 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

Adicione às suas configurações MCP do Roo Code:

mcp_settings.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Roo Code →

Goose

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

Adicione à sua configuração do 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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Goose →

LM Studio

O LM Studio oferece suporte a servidores MCP pela sua configuração de Agent. Adicione um novo servidor MCP em Settings → Agent → MCP Servers usando o formato JSON padrão mcpServers. O LM Studio se conecta a servidores MCP via stdio. Ver documentação →

Continue

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

Adicione à sua configuração do 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Continue →

Amazon Q Developer

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

Adicione à sua configuração MCP do 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Amazon Q Developer →

PyCharm

Adicione ao .ai/mcp/mcp.json na raiz do seu projeto, ou cole em Settings > Tools > 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do PyCharm →

Zed

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

Adicione às suas configurações do Zed (~/.config/zed/settings.json):

settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Zed →

Trae

Adicione ao .trae/mcp.json na raiz do seu projeto:

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Trae →

OpenCode

Adicione ao opencode.json na raiz do seu projeto:

opencode.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do OpenCode →

BoltAI

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

Adicione à sua configuração MCP do 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do BoltAI →

LibreChat

Adicione à sua configuração do 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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do LibreChat →

Antigravity

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

Adicione à sua configuração MCP do Antigravity:

mcp_config.json

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

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Antigravity →

Claude Cowork

O Claude Cowork usa o mesmo formato MCP dos outros clientes da 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"
      }
    }
  }
}

Substitua mgv_xxxx pela sua chave de API de app.maguyva.ai.

Documentação MCP do Claude Cowork →

ChatGPT

O ChatGPT oferece suporte a servidores MCP remotos nos planos Business, Enterprise e Edu, via Settings → Apps → Create. É necessário um endpoint HTTPS remoto — o ChatGPT não oferece suporte a servidores stdio locais. Veja o guia de MCP da OpenAI para a configuração. Ver documentação →

Warp

O Warp oferece suporte a servidores MCP no Agent Mode. A configuração é gerenciada pela interface do Warp (Settings → Agent Mode → MCP Servers) e sincronizada via Warp Drive. Cole o JSON padrão mcpServers ao adicionar um servidor. Ver documentação →

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.24 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 section 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. O servidor v3 não mantém estado, então as substituições de repositório valem apenas para uma chamada.

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#

Verifique se o npx está disponível no seu 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