Pular para o conteúdo

Guia de Instalação

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 / GitHub Copilot, e Devin Desktop (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/agent-plugins
/plugin install maguyva@maguyva

/plugin install abre os detalhes do plugin, onde você escolhe o escopo da instalação: só você (user), todos que trabalham neste repositório (project) ou só você neste repositório (local). Esses comandos dentro da sessão não aceitam a flag --scope.

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.

Para uma equipe, você também pode rodar a forma de shell dos dois comandos na raiz do repositório, fora do Claude Code:

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

O escopo project registra o plugin no .claude/settings.json do repositório, que você commita. Isso ativa o plugin para a equipe, mas não faz o download, então cada colega roda o comando de instalação uma vez.

Manual (.mcp.json) — avançado
claude mcp add 
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'
.mcp.json 
{
  "mcpServers": {
    "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.

O que o Maguyva acrescenta ao Claude Code →

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",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

O claude_desktop_config.json só inicia servidores locais, então esta configuração usa a bridge @maguyva/mcp (requer Node.js / npx). O Claude Desktop também pode alcançar o Maguyva como conector personalizado (Customize → Connectors) com um cabeçalho de requisição authorization, mas os cabeçalhos de requisição estão em beta para um número limitado de organizações.

O que o Maguyva acrescenta ao Claude Desktop →

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

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O que o Maguyva acrescenta ao Cursor →

Documentação MCP do Cursor →

VS Code / GitHub Copilot

Adicione ao .vscode/mcp.json do seu projeto ou ao mcp.json do seu perfil (rode MCP: Open User Configuration):

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

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

Este é o formato do VS Code (chave servers). O VS Code resolve a referência a MAGUYVA_API_KEY a partir do ambiente em que inicia. O fluxo Add Server agora prefere o .mcp.json portátil (chave mcpServers), que o GitHub Copilot CLI também lê; esse arquivo não aceita as variáveis de entrada nem os arquivos de ambiente do VS Code.

O que o Maguyva acrescenta ao VS Code / GitHub Copilot →

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

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

O Windsurf agora é o Devin Desktop. Adicione ao arquivo de configuração MCP dele:

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

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O Devin Local, agente padrão, lê este arquivo a partir da versão 3.6; versões anteriores guardavam os servidores no arquivo de configuração principal e os movem para cá ao iniciar. O agente legado Cascade, com o qual as novas conversas não começam, lê o mesmo arquivo. O Devin Desktop resolve a referência a MAGUYVA_API_KEY a partir do ambiente em que inicia.

O que o Maguyva acrescenta ao Devin Desktop (Windsurf) →

Documentação MCP do Devin Desktop (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"
bearer_token_env_var = "MAGUYVA_API_KEY"

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O que o Maguyva acrescenta ao Codex →

Documentação MCP do Codex →

GitHub Copilot CLI

Adicione ao ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
copilot mcp add 
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

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

O que o Maguyva acrescenta ao GitHub Copilot CLI →

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

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O que o Maguyva acrescenta ao Gemini CLI →

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": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

O que o Maguyva acrescenta ao Cline →

Documentação MCP do Cline →

Goose

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

Adicione à sua configuração do Goose:

config.yaml 
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

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

O que o Maguyva acrescenta ao Goose →

Documentação MCP do Goose →

LM Studio

No LM Studio, abra a aba Program na barra lateral direita, escolha Install → Edit mcp.json e adicione:

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

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

Documentação MCP do LM Studio →

Continue

Salve como .continue/mcpServers/maguyva.yaml no seu workspace (ou adicione a entrada mcpServers ao ~/.continue/config.yaml) e defina MAGUYVA_API_KEY em ~/.continue/.env:

.continue/mcpServers/maguyva.yaml 
name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O Continue só usa servidores MCP no modo agente. Ele procura o segredo em ~/.continue/.env, depois em .continue/.env e .env do workspace e, por fim, no ambiente do processo.

O que o Maguyva acrescenta ao Continue →

Documentação MCP do Continue →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

Adicione à configuração MCP do Kiro CLI (~/.kiro/settings/mcp.json, ou .kiro/settings/mcp.json de um projeto):

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

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

O Kiro CLI substituiu o Amazon Q Developer CLI. Na instalação, ele copia seus servidores uma única vez de ~/.aws/amazonq/mcp.json para ~/.kiro/settings/mcp.json, e o .kiro/settings/mcp.json de um projeto tem prioridade sobre o arquivo do usuário.

Documentação MCP do Kiro CLI (Amazon Q Developer CLI) →

PyCharm

Cole em Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add, como configuração JSON: 

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Esta configuração usa a bridge @maguyva/mcp (requer Node.js / npx). Uma configuração de conexão remota nativa para este cliente ainda não foi verificada neste guia; isso não significa que o cliente não ofereça suporte nativo a conexões remotas. O Maguyva é executado inteiramente de forma remota — apenas a bridge é executada localmente.

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

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

O que o Maguyva acrescenta ao Zed →

Documentação MCP do Zed →

Trae

Ative Enable Project MCP em Settings → MCP e depois adicione ao .trae/mcp.json na raiz do projeto:

.trae/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer 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 {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

O que o Maguyva acrescenta ao OpenCode →

Documentação MCP do OpenCode →

BoltAI

macOS: ~/.boltai/mcp.json

Adicione à sua configuração MCP do BoltAI:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Esta configuração usa a bridge @maguyva/mcp (requer Node.js / npx). Uma configuração de conexão remota nativa para este cliente ainda não foi verificada neste guia; isso não significa que o cliente não ofereça suporte nativo a conexões remotas. O Maguyva é executado inteiramente de forma remota — apenas a bridge é executada localmente.

Documentação MCP do BoltAI →

LibreChat

Adicione ao librechat.yaml e defina MAGUYVA_API_KEY no ambiente do servidor do LibreChat:

librechat.yaml 
mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

Esta configuração lê sua chave da variável de ambiente MAGUYVA_API_KEY. Defina-a com sua chave de API do app.maguyva.ai no ambiente de onde seu cliente é iniciado.

Documentação MCP do LibreChat →

Antigravity

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

Adicione à sua configuração MCP do Antigravity:

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

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

O que o Maguyva acrescenta ao Antigravity →

Documentação MCP do Antigravity →

Claude Cowork

O Claude Cowork não carrega servidores do claude_desktop_config.json; ele alcança servidores remotos como conectores personalizados. Em Customize → Connectors, adicione um conector personalizado com a URL https://maguyva.tools/mcp, escolha No sign-in e adicione um cabeçalho de requisição authorization cujo valor seja Bearer seguido da sua chave de API. Os cabeçalhos de requisição estão em beta para um número limitado de organizações; se a janela não tiver a seção Request headers, o Cowork ainda não consegue se autenticar no Maguyva. Ver documentação →

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

Adicione ao ~/.warp/.mcp.json (ou ao .warp/.mcp.json de um projeto), ou cole em Settings → Agents → MCP servers → + Add:

~/.warp/.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

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

O que o Maguyva acrescenta ao Warp →

Documentação MCP do Warp →

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

#

Relacionados

Leia a seguir