Servidor MCP para memória de agentes: conecte o Claude Code ao HotKV

Um servidor MCP é a forma mais simples de dar a um assistente de IA uma memória que dure mais que uma conversa. O Claude Code, o Cursor e clientes parecidos perdem o contexto de uma conversa quando ela termina. Dar a eles acesso direto ao banco de dados para resolver isso é arriscado. O hotkv-mcp é o nosso servidor MCP de código aberto para o HotKV. Ele dá ao assistente um conjunto fixo de ferramentas para notas, histórico de conversa, um log de eventos, modelos de prompt e busca em documentos. Não oferece mais nada.

Em resumo. O hotkv-mcp é um servidor MCP Apache-2.0 que conecta o Claude Code, o Cursor, o VS Code ou o seu próprio agente a um servidor HotKV por meio de 28 ferramentas fixas. Não existe nenhuma ferramenta que execute um comando arbitrário, então o assistente não consegue apagar dados nem mudar a configuração. Um modo somente leitura remove todas as ferramentas de escrita, e um namespace confina o agente a um único prefixo de chaves. Instale com pip install hotkv-mcp ou execute com uvx.

O que é o Model Context Protocol

O Model Context Protocol, ou MCP, é um padrão aberto para conectar aplicações de IA a sistemas externos, como fontes de dados, ferramentas e fluxos de trabalho. A introdução do projeto o compara a uma porta USB-C para aplicações de IA. Em termos de MCP, a aplicação é o cliente, e cada sistema ao qual ela se conecta é exposto por um servidor.

No caso da memória, isso significa que o assistente chama uma ferramenta com nome, como uma que salva uma nota. O servidor decide o que essa ferramenta pode fazer. O modelo nunca recebe uma conexão própria com o banco de dados.

O que o servidor MCP do HotKV expõe

O servidor envolve a memória de agentes, o registro de prompts e a busca em documentos do HotKV em 28 ferramentas. Cada ferramenta declara, nas suas anotações MCP, se apenas lê, escreve ou apaga. Assim, um cliente pode pedir aprovação antes das destrutivas.

As ferramentas de memória correspondem aos armazenamentos descritos em memória de agentes de IA, a saber, o histórico de conversa, as notas de trabalho e o log de eventos. A recuperação semântica por embedding não é exposta. O rag_search classifica por relevância de palavras-chave, então não precisa dela.

As ferramentas de chaves, hashes e listas funcionam com qualquer servidor HotKV. As ferramentas de memória, de prompts e de busca em documentos usam os motores de IA do HotKV, que exigem uma licença que os inclua. Sem ela, essas ferramentas devolvem uma mensagem dizendo que o servidor não tem licença para o recurso. As ferramentas de chaves continuam funcionando. As instâncias HotKV Cloud Performance e Scale incluem os motores de IA, como descreve a página de IA.

Instalar e conectar

O servidor precisa do Python 3.10 ou mais recente. Ele foi escrito para o servidor HotKV 0.3.0 e para o pacote oficial hotkv-client, e a versão 1.0.0 está no PyPI. Instale com o pip ou execute sem instalar usando o uv.

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

Adicione com um único comando. O -- separa as opções do próprio Claude Code do comando que inicia o servidor, como descreve a documentação de MCP do Claude Code.

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor e Claude Desktop

Os clientes que leem um arquivo mcpServers aceitam o mesmo servidor como uma entrada JSON. Mantenha a senha na variável de ambiente HOTKV_URL ou no armazenamento de segredos do cliente. Uma linha de comando fica visível para os outros usuários da máquina. Use hotkvs:// para uma conexão TLS.

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

Verifique se funciona

Execute claude mcp list para confirmar que o servidor está registrado. Depois peça ao assistente que chame a ferramenta server_info. Ela devolve a versão do HotKV e o uso de memória, além da contagem de chaves quando nenhum namespace está definido. Também informa se o servidor está em modo somente leitura e a que namespace ele está limitado. Isso confirma que as suas salvaguardas entraram em vigor.

Mantenha o agente dentro de limites seguros

Um modelo que pode chamar ferramentas também pode ser convencido a usá-las mal, então os limites importam mais que os recursos.

Nenhum comando arbitrário

Não existe nenhuma ferramenta que execute um comando bruto. O assistente não consegue apagar um banco de dados nem mudar a configuração do servidor, porque nenhuma das 28 ferramentas faz isso. Ele pode ler qualquer chave que as ferramentas alcançam, e é por isso que o namespace abaixo importa.

Modo somente leitura

O --read-only remove toda ferramenta que escreve, incluindo set, delete, hash_set, list_push, as ferramentas de memória que adicionam ou limpam, prompt_save, rag_create e rag_ingest. O agente nem chega a vê-las. Use-o em assistentes que devem consultar a memória, mas nunca alterá-la.

Namespaces e limites de tamanho

O --namespace PREFIX guarda tudo sob esse prefixo. O agente nunca vê o prefixo e não consegue alcançar outros nomes. Dê a cada agente um prefixo que não seja o início de outro. Use agent-a e agent-b, não agent e agent:b, ou o mais curto consegue alcançar os nomes do mais longo.

Os resultados também têm limite. O --max-value-bytes corta valores longos e os sinaliza como truncados, com um padrão de 65.536 bytes. O --max-items limita quantas chaves, itens de lista ou resultados uma chamada devolve, 200 por padrão. Assim, um único valor enorme não consegue inundar o contexto do modelo. A leitura de um hash inteiro não tem limite de itens, então mantenha hashes grandes fora do namespace de um agente.

O transporte HTTP não tem login

O transporte stdio padrão é iniciado pelo cliente como um subprocesso. Para uso compartilhado, você pode executar hotkv-mcp --transport streamable-http, que escuta em 127.0.0.1:8000 no caminho /mcp. Ele não autentica quem chama. Mantenha-o no localhost ou coloque-o atrás de um proxy reverso que autentique, e dê a ele o seu próprio namespace.

Escolhendo uma configuração para uma equipe

As flags certas dependem da finalidade de cada agente. Toda opção abaixo é uma flag de linha de comando. O --read-only e o --namespace também têm variáveis de ambiente, HOTKV_MCP_READ_ONLY e HOTKV_MCP_NAMESPACE.

Parta da linha mais restrita que resolva o problema. É fácil ampliar o acesso depois e difícil desfazer o que um agente já escreveu.

Uma primeira sessão, passo a passo

Um teste curto mostra o que as salvaguardas fazem antes de você confiar ao servidor notas de verdade. Use um namespace descartável e um servidor HotKV local com licença para os motores de IA, porque as ferramentas de memória não funcionam sem essa licença.

1. Conecte com um namespace. Execute claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Verifique os limites. Peça ao assistente que chame server_info e informe o namespace e se o servidor está em modo somente leitura. Ele deve dizer trial e não somente leitura.
3. Salve uma nota. Peça a ele que lembre que o site de staging fica em um determinado endereço, em uma nota com o nome do site. O assistente chama memory_set_note, e a sessão é criada no primeiro uso.
4. Leia de volta em uma nova conversa. Inicie uma conversa nova e pergunte quais notas existem para essa sessão. Ele chama memory_list_notes e memory_get_note, e a nota continua lá.
5. Registre uma decisão. Peça a ele que registre uma decisão no log de eventos. Ele chama memory_log_event, e o memory_query_events a traz de volta mais tarde.
6. Retire o acesso de escrita. Remova a entrada antiga, reconecte com --read-only e repita o passo 4. A leitura continua funcionando, e as ferramentas que escrevem deixam de ser oferecidas.

Se o passo 6 se comportar como descrito, você viu os dois controles que mais importam, o namespace e o modo somente leitura.

Trate tudo o que o assistente guarda como texto não confiável quando for lido de volta, como explica o artigo sobre memória em tratar o texto armazenado como não confiável. Notas escritas a partir de páginas da web podem carregar instruções.

Solução de problemas

• "This HotKV server is not licensed for that feature." As ferramentas de memória, de prompts e de busca em documentos exigem uma licença do HotKV que inclua os motores de IA. As ferramentas de chaves, hashes e listas continuam funcionando sem ela.
• A conexão falha. Verifique o esquema da URL. hotkv://, hotkvs:// (TLS), redis:// e rediss:// funcionam, e a senha vai na URL como hotkv://:password@host:6379.
• Um valor volta cortado. O resultado é sinalizado como truncado quando passa de --max-value-bytes. Aumente o limite ou guarde valores menores.
• Falta uma ferramenta de escrita. Procure --read-only nos argumentos do servidor ou HOTKV_MCP_READ_ONLY no ambiente dele.
• O assistente não encontra um nome que salvou antes. Confira se ele usou o mesmo nome de sessão ou de agente e se o servidor roda com o mesmo namespace de antes.
• O uvx não é encontrado. Instale o uv ou instale o pacote com o pip e inicie o hotkv-mcp diretamente.

Perguntas frequentes