Quickstart MCP

Este guia permite que você integre o Vectora com Claude Desktop via MCP em menos de 5 minutos.

Passo 1: Localizar o Arquivo de Configuração

macOS / Linux

# Arquivo de configuração do Claude Desktop
open ~/.claude/claude_desktop_config.json

# Se não existir, crie com:
mkdir -p ~/.claude
touch ~/.claude/claude_desktop_config.json

Windows

# Arquivo de configuração (WSL2 ou Windows)
"$env:APPDATA\Claude\claude_desktop_config.json"

# Se não existir, crie com:
New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force

Passo 2: Adicionar Vectora como MCP Server

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp-serve"],
      "env": {
        "GEMINI_API_KEY": "sk-xxx...",
        "VOYAGE_API_KEY": "pa-xxx...",
        "VECTORA_NAMESPACE": "my-project"
      }
    }
  }
}

Alternativa: Usar Variáveis de Ambiente do Sistema

Se já tiver GEMINI_API_KEY e VOYAGE_API_KEY definidas:

{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp-serve"]
    }
  }
}

Passo 3: Reiniciar Claude Desktop

# Feche completamente Claude Desktop e abra novamente
# Isso carrega a nova configuração MCP

Passo 4: Testar a Conexão

Via Claude Desktop Chat

Abra Claude Desktop e teste:

Me mostre os arquivos disponíveis usando o Vectora

Claude deve responder algo como:

I have access to Vectora, a code context engine. Let me check what files are available in your project.

[Vectora is now searching your codebase...]

Available files in namespace 'my-project':
- src/auth/jwt.ts (authentication)
- src/services/database.ts (database layer)
- docs/README.md (documentation)
...

Verificar Status do MCP

Se receber erro:

1. Abra MCP Inspector (no Claude Desktop: Menu → Configurações → Ferramentas do Desenvolvedor)
2. Procure por “vectora” na lista de servidores
3. Status deve ser “Connected”

Se não estiver conectado:

• Verifique que vectora --version funciona no terminal
• Confira o arquivo claude_desktop_config.json (sintaxe JSON)
• Reinicie Claude Desktop

Passo 5: Seu Primeiro Comando

Explorar o Codebase

Qual é a estrutura deste projeto? Liste os diretórios principais.

Claude usa file_list via Vectora.

Buscar Contexto

Como funciona a autenticação JWT neste projeto? Encontre a implementação.

Claude usa context_search para busca semântica.

Analisar Um Arquivo

Leia e explique o arquivo src/main.ts

Claude usa file_read para ler o arquivo.

Estrutura do Projeto

Depois de vectora init, você terá:

meu-projeto/
├── vectora.config.yaml # Configuração do projeto
├── AGENTS.md # Memória do agente (auto-gerado)
├── .vectora/ # Cache e índices locais
│ ├── embeddings/ # Cache de embeddings
│ └── index.json # Metadados do índice
├── src/ # Seu código
└── .env # Variáveis de ambiente (não commitar!)

Comandos MCP Disponíveis

Troubleshooting

Erro: Vectora MCP server not found

Causa: O binário vectora não está no PATH.

Solução: Verifique se a instalação via Winget ou script foi concluída e reinicie seu terminal.

Erro: Connection refused

Causa: Vectora não consegue conectar à API do Gemini/Voyage.

Solução: Verifique seu status de autenticação com vectora auth status ou faça login novamente com vectora auth login.

Erro: Project not found

Causa: Namespace não existe.

Solução:

# Inicialize o projeto
vectora init --name "Meu Projeto"

# Ou especifique em claude_desktop_config.json:
"VECTORA_NAMESPACE": "my-project"

Claude não usa Vectora automaticamente

Causa: Claude não detecta que a ferramenta é relevante.

Solução: Seja explícito:

Use o Vectora para buscar informações sobre autenticação neste projeto.

Próximos Passos

• Aprofundar: Leia Context Engine
• Integrar com Cursor: Cursor Integration
• Entender Segurança: Guardian & RBAC

FAQ

P: Posso usar Vectora com outros agentes além de Claude? R: Sim! Veja Gemini Integration e Custom Agents.

P: Vectora funciona offline? R: Parcialmente. Context search precisa de internet (Voyage API). File operations funcionam offline.

P: Como debugar conexões MCP? R: Use o MCP Inspector em Claude Desktop (Menu → Developer Tools → MCP Inspector).

Próximo: Aprenda sobre Troubleshooting.

External Linking

Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores