MCP-server voor agentgeheugen: verbind Claude Code met HotKV

Een MCP-server is de eenvoudigste manier om een AI-assistent een geheugen te geven dat langer meegaat dan één chat. Claude Code, Cursor en vergelijkbare clients verliezen de context van een chat wanneer die eindigt. Ze ruwe databasetoegang geven om dat op te lossen is riskant. hotkv-mcp is onze open-source MCP-server voor HotKV. Hij geeft een assistent een vaste set tools voor notities, gespreksgeschiedenis, een gebeurtenislogboek, prompttemplates en documentzoekfunctie. Meer biedt hij niet.

Kort samengevat. hotkv-mcp is een MCP-server onder Apache-2.0 die Claude Code, Cursor, VS Code of je eigen agent via 28 vaste tools met een HotKV-server verbindt. Er is geen tool die een willekeurig commando uitvoert, dus de assistent kan geen data wissen of configuratie wijzigen. Een alleen-lezenmodus verwijdert elke schrijftool en een namespace beperkt de agent tot één sleutelprefix. Installeer hem met pip install hotkv-mcp of draai hem met uvx.

Wat het Model Context Protocol is

Het Model Context Protocol, of MCP, is een open standaard om AI-toepassingen met externe systemen te verbinden, zoals databronnen, tools en workflows. De introductie van het project vergelijkt het met een USB-C-poort voor AI-toepassingen. In MCP-termen is de applicatie de client, en elk systeem waarmee hij verbinding maakt wordt door een server aangeboden.

Voor geheugen betekent dat dat de assistent een benoemde tool aanroept, zoals een tool die een notitie opslaat. De server bepaalt wat die tool mag doen. Het model krijgt nooit een eigen databaseverbinding.

Wat de HotKV MCP-server aanbiedt

De server verpakt het agentgeheugen, het promptregister en de documentzoekfunctie van HotKV in 28 tools. Elke tool geeft in zijn MCP-annotaties aan of hij alleen leest, schrijft of verwijdert. Een client kan dan om goedkeuring vragen voor de destructieve.

De geheugentools sluiten aan op de opslagen die in AI-agentgeheugen worden beschreven, namelijk gespreksgeschiedenis, werknotities en het gebeurtenislogboek. Semantische recall via embeddings wordt niet aangeboden. rag_search rangschikt op trefwoordrelevantie, dus daar is er geen voor nodig.

De tools voor sleutels, hashes en lijsten werken tegen elke HotKV-server. De tools voor geheugen, prompts en documentzoekfunctie gebruiken de AI-engines van HotKV, die een licentie vereisen die ze bevat. Zonder die licentie geven die tools een bericht terug dat de server niet is gelicentieerd voor de functie. De sleuteltools blijven werken. HotKV Cloud-instanties van Performance en Scale bevatten de AI-engines, zoals de AI-pagina beschrijft.

Installeren en verbinden

De server heeft Python 3.10 of nieuwer nodig. Hij is geschreven tegen HotKV-server 0.3.0 en het officiële pakket hotkv-client, en versie 1.0.0 staat op PyPI. Installeer hem met pip, of draai hem zonder installatie met uv.

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

Claude Code

Voeg hem toe met één commando. De -- scheidt de eigen opties van Claude Code van het commando dat de server start, zoals de MCP-documentatie van Claude Code beschrijft.

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

Cursor en Claude Desktop

Clients die een mcpServers-bestand lezen nemen dezelfde server op als JSON-vermelding. Houd het wachtwoord in de omgevingsvariabele HOTKV_URL of in de geheime opslag van de client. Een opdrachtregel is zichtbaar voor andere gebruikers van de machine. Gebruik hotkvs:// voor een TLS-verbinding.

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

Controleren of het werkt

Voer claude mcp list uit om te bevestigen dat de server is geregistreerd. Vraag de assistent daarna de tool server_info aan te roepen. Die geeft de HotKV-versie en het geheugengebruik terug, plus het aantal sleutels wanneer geen namespace is ingesteld. Hij meldt ook of de server alleen-lezen is en tot welke namespace hij beperkt is. Zo bevestig je dat je beveiligingen van kracht zijn.

Houd de agent binnen veilige grenzen

Een model dat tools kan aanroepen, kan ook worden overgehaald ze te misbruiken, dus de grenzen zijn belangrijker dan de functies.

Geen willekeurige commando's

Er is geen tool die een ruw commando uitvoert. De assistent kan geen database wissen of de configuratie van de server wijzigen, omdat geen van de 28 tools dat doet. Hij kan wel elke sleutel lezen die de tools bereiken, en daarom is de namespace hieronder belangrijk.

Alleen-lezenmodus

--read-only verwijdert elke tool die schrijft, waaronder set, delete, hash_set, list_push, de geheugentools die toevoegen of wissen, prompt_save, rag_create en rag_ingest. De agent kan ze niet eens zien. Gebruik het voor assistenten die het geheugen moeten raadplegen maar nooit moeten wijzigen.

Namespaces en groottelimieten

--namespace PREFIX slaat alles onder die prefix op. De agent ziet de prefix nooit en kan andere namen niet bereiken. Geef elke agent een prefix die niet het begin is van die van een ander. Gebruik agent-a en agent-b, niet agent en agent:b, anders kan de kortere de namen van de langere bereiken.

Ook resultaten zijn begrensd. --max-value-bytes knipt lange waarden af en markeert ze als afgekapt, met een standaard van 65.536 bytes. --max-items beperkt hoeveel sleutels, lijstitems of treffers een aanroep teruggeeft, standaard 200. Eén enorme waarde kan de context van het model dus niet overspoelen. Het lezen van een hele hash is niet begrensd op aantal items, dus houd grote hashes buiten de namespace van een agent.

Het HTTP-transport heeft geen login

Het standaard stdio-transport wordt door de client als subproces gestart. Voor gedeeld gebruik kun je hotkv-mcp --transport streamable-http draaien, dat luistert op 127.0.0.1:8000 bij /mcp. Het authenticeert aanroepers niet. Houd het op localhost of zet het achter een reverse proxy die dat wel doet, en geef het een eigen namespace.

Een setup kiezen voor een team

De juiste flags hangen af van waarvoor elke agent dient. Elke optie hieronder is een commandoregelflag. --read-only en --namespace hebben ook omgevingsvariabelen, HOTKV_MCP_READ_ONLY en HOTKV_MCP_NAMESPACE.

Begin bij de meest beperkte rij die de klus klaart. Toegang later verruimen is makkelijk, terugnemen wat een agent al heeft geschreven is moeilijk.

Een eerste sessie, stap voor stap

Een korte proef laat zien wat de beveiligingen doen voordat je de server met echte notities vertrouwt. Gebruik een wegwerpnamespace en een lokale HotKV-server die is gelicentieerd voor de AI-engines, omdat de geheugentools zonder die licentie niet werken.

1. Verbind met een namespace. Voer claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial uit.
2. Controleer de grenzen. Vraag de assistent server_info aan te roepen en de namespace te melden en of de server alleen-lezen is. Hij zou trial moeten zeggen en niet alleen-lezen.
3. Sla een notitie op. Vraag hem te onthouden dat de stagingsite op een bepaald adres staat, onder een notitie die naar de site is vernoemd. De assistent roept memory_set_note aan en de sessie wordt bij het eerste gebruik aangemaakt.
4. Lees hem terug in een nieuwe chat. Begin een nieuw gesprek en vraag welke notities er voor die sessie bestaan. Hij roept memory_list_notes en memory_get_note aan, en de notitie staat er nog.
5. Log een beslissing. Vraag hem een beslissing in het gebeurtenislogboek vast te leggen. Hij roept memory_log_event aan, en memory_query_events brengt hem later terug.
6. Verwijder zijn schrijftoegang. Verwijder de oude vermelding, verbind opnieuw met --read-only en herhaal stap 4. Lezen werkt nog steeds, en de tools die schrijven worden niet meer aangeboden.

Als stap 6 zich gedraagt zoals beschreven, heb je de twee belangrijkste controles gezien, de namespace en de alleen-lezenmodus.

Behandel wat de assistent opslaat als onbetrouwbare tekst wanneer die wordt teruggelezen, zoals het geheugenartikel uitlegt bij opgeslagen tekst als onbetrouwbaar behandelen. Notities die uit webpagina's zijn geschreven kunnen instructies bevatten.

Probleemoplossing

• "This HotKV server is not licensed for that feature." De tools voor geheugen, prompts en documentzoekfunctie hebben een HotKV-licentie nodig die de AI-engines bevat. De tools voor sleutels, hashes en lijsten blijven zonder werken.
• De verbinding mislukt. Controleer het URL-schema. hotkv://, hotkvs:// (TLS), redis:// en rediss:// werken allemaal, en een wachtwoord gaat in de URL als hotkv://:password@host:6379.
• Een waarde komt afgekapt terug. Het resultaat wordt als afgekapt gemarkeerd wanneer het --max-value-bytes overschrijdt. Verhoog de limiet of sla kleinere waarden op.
• Een schrijftool ontbreekt. Zoek naar --read-only in de argumenten van de server of HOTKV_MCP_READ_ONLY in zijn omgeving.
• De assistent kan een eerder opgeslagen naam niet vinden. Controleer of hij dezelfde sessie- of agentnaam heeft gebruikt en of de server met dezelfde namespace draait als voorheen.
• uvx wordt niet gevonden. Installeer uv, of installeer het pakket met pip en start hotkv-mcp rechtstreeks.

Veelgestelde vragen