Skip to content
MachiOnCoffee
Vectora
Reference
MCP Reference

MCP Reference

PT | EN

Referência técnica completa da implementação MCP de Vectora: tools, autenticação, transporte, tratamento de erros e exemplos.

Server Info 

{
  "name": "vectora",
  "version": "0.8.0",
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

Tools Disponíveis

Vectora oferece 12 tools via MCP para busca, análise, indexação e monitoramento de código.

Para referência completa de todas as tools com parâmetros e exemplos: → MCP Tools Reference

Autenticação

Método 1: Bearer Token (Recomendado) 

Authorization: Bearer sk-proj-vectora-abc123...

Token gerado via:

vectora auth token create --name "Claude Code"

Token expira em 30 dias (configurável).

Método 2: API Key 

X-API-Key: sk-...

Menos recomendado (não expira automaticamente).

Método 3: BYOK (Bring Your Own Key)

Para planos Free:

Authorization: Bearer {GEMINI_API_KEY}

Vectora não armazena, apenas forwarda.

Transport

STDIO (Padrão para IDE) 

# Em .claude/claude_desktop_config.json
{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp", "--stdio"],
      "env": {
        "VECTORA_TOKEN": "sk-proj-..."
      }
    }
  }
}

Ideal para: Claude Code, Cursor, Zed (local, <10ms latência)

HTTP (Para Remote) 

POST https://api.vectora.app/mcp
Authorization: Bearer sk-proj-...

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_context",
    "arguments": {"query": "..."}
  }
}

Ideal para: Servidores remotos, CI/CD

Error Handling

Erros retornam no padrão JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "error_code": "INVALID_QUERY",
      "detail": "Query deve ter 3-10000 chars"
    }
  }
}

Códigos de Erro MCP

CódigoSignificadoHTTP
-32700Parse error400
-32600Invalid request400
-32602Invalid params400
-32601Method not found404
-32603Internal error500

Vectora retorna também error_code customizado (ex: NAMESPACE_NOT_FOUND).

Streaming (Respostas Grandes)

Para queries que retornam muitos chunks:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Chunk 1...",
        "partial": true
      },
      {
        "type": "text",
        "text": "Chunk 2...",
        "partial": true
      },
      {
        "type": "text",
        "text": "Chunk 3...",
        "partial": false
      }
    ]
  }
}

Suporta streaming progressivo até 30s timeout.

Caching

MCP suporta caching automático via cache_control:

{
  "type": "text",
  "text": "resultado",
  "cache_control": { "type": "ephemeral" } // TTL 5min
}

Economiza latência em queries repetidas.

Capabilities 

tools:
  listChanged: true # Avisar quando tools mudam
  implementation: 12 # Número de tools

logging:
  enabled: true # Log de todas calls
  level: info # info, debug, warn

performance:
  latency_p95: 250ms # 95th percentile
  timeout: 30000ms # 30s máximo

Exemplo Completo: Fluxo MCP 

# 1. IDE inicia Vectora MCP
vectora mcp --stdio

# 2. IDE envia initialize
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"claude-code"}}}

# 3. Vectora responde
< {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"vectora"}}}

# 4. IDE lista tools
> {"jsonrpc":"2.0","id":2,"method":"tools/list"}

# 5. Vectora retorna
< {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

# 6. IDE chama tool
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_context","arguments":{"query":"Como validar JWT?"}}}

# 7. Vectora retorna resultado
< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Encontrei 5 chunks..."}]}}

Debug

Habilitar logs detalhados:

VECTORA_DEBUG=true VECTORA_LOG_LEVEL=debug vectora mcp --stdio 2> ~/.vectora/mcp-debug.log

Logs mostram todos os messages JSON trocados.

Especificação completa: Model Context Protocol Spec

CLI