Como Configurar o Servidor MCP do Geneziz com o Claude Code

Por Que Conectar o Geneziz ao Seu Assistente de IA?

Você passou horas curando bookmarks no X.com, dando estrelas em repos no GitHub e organizando tudo em uma base de conhecimento estruturada com o Geneziz. Mas quando você abre o IDE para escrever código, esse conhecimento fica invisível - trancado em um app separado.

O Model Context Protocol (MCP) muda isso. Ele permite que qualquer assistente de IA compatível com MCP consulte sua base de conhecimento do Geneziz em tempo real, direto do seu terminal ou interface de chat.

Este guia percorre a configuração do servidor MCP do Geneziz com o Claude Code (o assistente de IA compatível com MCP mais popular), mas os mesmos passos funcionam com Cursor, Windsurf ou qualquer outra ferramenta compatível com MCP.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. O Geneziz instalado com pelo menos uma sincronização concluída (geneziz fetch + geneziz process executados pelo menos uma vez)
2. Uma chave de licença válida (prefixo GNZ- ou GNZD- - toda licença inclui o servidor MCP)
3. Seu diretório de conhecimento populado com ferramentas, artigos ou bookmarks
4. Node.js 18+ (para rodar o servidor MCP)

Você pode verificar sua configuração executando:

geneziz status

Procure contagens maiores que zero em ferramentas, artigos ou bookmarks.

Passo 1: Inicie o Servidor MCP

O servidor MCP do Geneziz é embutido na CLI. Abra o terminal e execute:

geneziz mcp

Isso inicia o servidor MCP em stdio (entrada/saída padrão), que é como a maioria dos assistentes de IA se comunica com servidores MCP.

Você deverá ver uma saída como:

MCP server starting...
Listening on stdio...

O servidor expõe estas ferramentas ao seu assistente de IA:

Passo 2: Configure o Claude Code para MCP

O Claude Code tem suporte nativo a MCP. Você precisa adicionar o servidor do Geneziz à configuração dele.

Opção 0: geneziz mcp register (Recomendado)

Deixe o Geneziz fazer isso. Um único comando registra o servidor MCP em todos os clientes de IA que ele detectar na sua máquina - incluindo o Claude Code:

geneziz mcp register

Ele grava a entrada do servidor geneziz na configuração de cada cliente (no caso do Claude Code, ~/.claude.json) usando o caminho absoluto do executável do Geneziz mais um pin de ambiente GENEZIZ_DATA_DIR, para que o servidor inicie sem configuração de PATH e sempre encontre o seu diretório de dados. Somente a entrada do próprio Geneziz é alterada - outros servidores no mesmo arquivo permanecem como estão, e um backup único é gravado antes de qualquer mudança. Veja o que foi feito com:

geneziz mcp register --status

E desfaça quando quiser com geneziz mcp register --remove --all (apenas as entradas do Geneziz são removidas). Se você preferir ver ou posicionar a entrada você mesmo, use uma das opções manuais abaixo.

Opção A: Pelas Configurações do Claude Code

1. Abra o Claude Code
2. Pressione / para abrir a paleta de comandos
3. Digite MCP ou Manage MCP Servers
4. Clique em Add Server
5. Preencha:
   • Name: Geneziz
   • Command: geneziz mcp
   • Type: stdio
6. Clique em Save

Opção B: Via .claude/settings.json

Crie ou edite ~/.claude/settings.json no seu diretório home:

{
  "mcpServers": {
    "geneziz": {
      "command": "geneziz",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Passo 3: Teste a Conexão

Abra uma nova sessão do Claude Code (ou comece a conversar no Cursor/Windsurf) e tente:

"Pesquise na minha base de conhecimento por artigos sobre otimização de performance em React"

Se tudo estiver configurado corretamente, o assistente de IA vai chamar a ferramenta search_knowledge, consultar sua base de conhecimento local e retornar resultados relevantes - com títulos, categorias e trechos.

Experimente estas consultas de teste:

• "Quais ferramentas eu salvei na minha base de conhecimento?"
• "Mostre artigos recentes sobre Python"
• "Liste todas as categorias da minha base de conhecimento"

Como Funciona por Baixo dos Panos

Quando você faz uma pergunta que dispara uma chamada de ferramenta:

1. O Claude Code envia uma requisição JSON-RPC para o processo geneziz mcp
2. O servidor MCP lê seu viewer-index.json e os arquivos de conhecimento
3. Os resultados são retornados como dados estruturados (títulos, slugs, categorias, conteúdo)
4. O Claude Code sintetiza os resultados em uma resposta em linguagem natural

Tudo isso acontece localmente - seus dados nunca saem da sua máquina. O servidor MCP lê diretamente do seu diretório de conhecimento usando busca de texto completo SQLite FTS5 ou busca vetorial ChromaDB (ambos incluídos em toda licença).

Problemas Comuns

"Command not found: geneziz"

Certifique-se de que o app desktop do Geneziz está instalado - o instalador dele coloca a CLI geneziz no seu PATH. Se o comando ainda não existir, reinstale a partir do download mais recente e abra um terminal novo, depois verifique com:

geneziz --help

"No tools found"

Execute geneziz index primeiro para gerar o índice do visualizador:

geneziz index
geneziz status  # Verifique se ferramentas/artigos > 0

"License error: no active license"

O servidor MCP vem incluído em toda licença do Geneziz - tanto chaves GNZ- quanto GNZD- funcionam - mas exige uma licença válida e ativada. Certifique-se de que sua chave foi inserida e o dispositivo está ativado, depois verifique:

geneziz license --check GNZ-YOUR-KEY-HERE

Porta já em uso

Se outro processo geneziz mcp estiver rodando, encerre-o primeiro:

# Encontrar e encerrar o processo existente
pkill -f "geneziz mcp"
# Depois reinicie
geneziz mcp

Próximos Passos

Assim que o servidor MCP estiver rodando e conectado:

1. Adicione-o à configuração de inicialização do seu assistente de IA para que ele se conecte automaticamente a cada sessão
2. Experimente fazer perguntas sobre os seus próprios bookmarks - você vai se surpreender com o que vai encontrar
3. Combine com geneziz sync para manter sua base de conhecimento atualizada antes de cada sessão de código

Notas de Compartilhamento

Este post faz parte da série de blog do Geneziz. Se foi útil, compartilhe com um desenvolvedor que está se afogando em bookmarks.