MCP-server för agentminne: koppla Claude Code till HotKV

En MCP-server är det enklaste sättet att ge en AI-assistent ett minne som varar längre än en enda chatt. Claude Code, Cursor och liknande klienter förlorar chattens kontext när den tar slut. Att ge dem rå databasåtkomst för att åtgärda det är riskabelt. hotkv-mcp är vår MCP-server med öppen källkod för HotKV. Den ger en assistent en fast uppsättning verktyg för anteckningar, konversationshistorik, en händelselogg, promptmallar och dokumentsökning. Den erbjuder inget annat.

Kort sagt. hotkv-mcp är en MCP-server under Apache-2.0 som kopplar Claude Code, Cursor, VS Code eller din egen agent till en HotKV-server via 28 fasta verktyg. Det finns inget verktyg som kör ett godtyckligt kommando, så assistenten kan inte tömma data eller ändra konfigurationen. Ett skrivskyddat läge tar bort varje skrivverktyg, och en namnrymd håller agenten inom ett enda nyckelprefix. Installera den med pip install hotkv-mcp eller kör den med uvx.

Vad Model Context Protocol är

Model Context Protocol, eller MCP, är en öppen standard för att koppla AI-applikationer till externa system som datakällor, verktyg och arbetsflöden. Projektets introduktion jämför det med en USB-C-port för AI-applikationer. I MCP:s termer är applikationen klienten, och varje system den ansluter till exponeras av en server.

För minne innebär det att assistenten anropar ett namngivet verktyg, till exempel ett som sparar en anteckning. Servern avgör vad det verktyget får göra. Modellen får aldrig en databasanslutning av egen.

Vad HotKV:s MCP-server exponerar

Servern omsluter HotKV:s agentminne, promptregister och dokumentsökning i 28 verktyg. Varje verktyg anger i sina MCP-annotationer om det bara läser, skriver eller raderar. En klient kan då be om godkännande innan de destruktiva.

Minnesverktygen motsvarar de lager som beskrivs i Minne för AI-agenter, nämligen konversationshistorik, arbetsanteckningar och händelseloggen. Semantiskt återkallande via embedding exponeras inte. rag_search rangordnar efter nyckelordsrelevans och behöver därför ingen.

Verktygen för nycklar, hashar och listor fungerar mot vilken HotKV-server som helst. Verktygen för minne, prompter och dokumentsökning använder HotKV:s AI-motorer, som kräver en licens som innehåller dem. Utan en sådan returnerar de verktygen ett meddelande om att servern inte är licensierad för funktionen. Nyckelverktygen fortsätter fungera. Instanserna Performance och Scale på HotKV Cloud innehåller AI-motorerna, som AI-sidan beskriver.

Installera och anslut

Servern kräver Python 3.10 eller senare. Den skrevs mot HotKV-server 0.3.0 och det officiella paketet hotkv-client, och version 1.0.0 finns på PyPI. Installera den med pip, eller kör den utan installation med uv.

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

Claude Code

Lägg till den med ett kommando. -- skiljer Claude Codes egna alternativ från kommandot som startar servern, som dokumentationen för MCP i Claude Code beskriver.

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

Cursor och Claude Desktop

Klienter som läser en mcpServers-fil tar samma server som en JSON-post. Ha lösenordet i miljövariabeln HOTKV_URL eller klientens hemlighetslager. En kommandorad syns för andra användare på maskinen. Använd hotkvs:// för en TLS-anslutning.

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

Kontrollera att det fungerar

Kör claude mcp list för att bekräfta att servern är registrerad. Be sedan assistenten anropa verktyget server_info. Det returnerar HotKV-versionen och minnesanvändningen, plus antalet nycklar när ingen namnrymd är satt. Det anger också om servern är skrivskyddad och vilken namnrymd den är begränsad till. Det bekräftar att dina skyddsåtgärder gäller.

Håll agenten inom säkra gränser

En modell som kan anropa verktyg kan också bli övertalad att missbruka dem, så gränserna betyder mer än funktionerna.

Inga godtyckliga kommandon

Det finns inget verktyg som kör ett råkommando. Assistenten kan inte tömma en databas eller ändra serverns konfiguration, eftersom inget av de 28 verktygen gör det. Den kan läsa varje nyckel som verktygen når, och därför är namnrymden nedan viktig.

Skrivskyddat läge

--read-only tar bort varje verktyg som skriver, bland annat set, delete, hash_set, list_push, minnesverktygen som lägger till eller rensar, prompt_save, rag_create och rag_ingest. Agenten ser dem inte ens. Använd det för assistenter som ska konsultera minnet men aldrig ändra det.

Namnrymder och storlekstak

--namespace PREFIX lagrar allt under det prefixet. Agenten ser aldrig prefixet och kan inte nå andra namn. Ge varje agent ett prefix som inte är början på ett annat. Använd agent-a och agent-b, inte agent och agent:b, annars kan det kortare nå det längres namn.

Resultaten har också tak. --max-value-bytes kapar långa värden och flaggar dem som avkortade, med 65 536 byte som standard. --max-items begränsar hur många nycklar, listposter eller träffar ett anrop returnerar, 200 som standard. Ett enda enormt värde kan därför inte svämma över modellens kontext. Att läsa en hel hash har inget tak för antal poster, så håll stora hashar utanför en agents namnrymd.

HTTP-transporten har ingen inloggning

Standardtransporten stdio startas av klienten som en underprocess. För delad användning kan du köra hotkv-mcp --transport streamable-http, som lyssnar på 127.0.0.1:8000 på /mcp. Den autentiserar inte anropare. Håll den på localhost eller lägg den bakom en omvänd proxy som gör det, och ge den en egen namnrymd.

Välja en uppsättning för ett team

Rätt flaggor beror på vad varje agent ska användas till. Varje alternativ nedan är en kommandoradsflagga. --read-only och --namespace har också miljövariabler, HOTKV_MCP_READ_ONLY och HOTKV_MCP_NAMESPACE.

Utgå från den mest begränsade raden som gör jobbet. Det är lätt att vidga åtkomsten senare och svårt att ta tillbaka det en agent redan har skrivit.

En första session, steg för steg

En kort provkörning visar vad skyddsåtgärderna gör innan du litar på servern med riktiga anteckningar. Använd en tillfällig namnrymd och en lokal HotKV-server som är licensierad för AI-motorerna, eftersom minnesverktygen inte fungerar utan den licensen.

1. Anslut med en namnrymd. Kör claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Kontrollera gränserna. Be assistenten anropa server_info och redovisa namnrymden och om servern är skrivskyddad. Den bör svara trial och inte skrivskyddad.
3. Spara en anteckning. Be den komma ihåg att stagingsajten finns på en viss adress, under en anteckning uppkallad efter sajten. Assistenten anropar memory_set_note, och sessionen skapas vid första användningen.
4. Läs tillbaka i en ny chatt. Starta en ny konversation och fråga vilka anteckningar som finns för sessionen. Den anropar memory_list_notes och memory_get_note, och anteckningen finns kvar.
5. Logga ett beslut. Be den registrera ett beslut i händelseloggen. Den anropar memory_log_event, och memory_query_events hämtar tillbaka det senare.
6. Ta bort dess skrivåtkomst. Ta bort den gamla posten, anslut igen med --read-only och upprepa steg 4. Läsning fungerar fortfarande, och verktygen som skriver erbjuds inte längre.

Om steg 6 beter sig som beskrivet har du sett de två kontroller som betyder mest, namnrymden och skrivskyddat läge.

Behandla allt assistenten lagrar som opålitlig text när det läses tillbaka, som artikeln om minne förklarar under behandla lagrad text som opålitlig. Anteckningar som skrivits utifrån webbsidor kan bära instruktioner.

Felsökning

• ”This HotKV server is not licensed for that feature.” Verktygen för minne, prompter och dokumentsökning kräver en HotKV-licens som innehåller AI-motorerna. Verktygen för nycklar, hashar och listor fortsätter fungera utan en.
• Anslutningen misslyckas. Kontrollera URL-schemat. hotkv://, hotkvs:// (TLS), redis:// och rediss:// fungerar alla, och ett lösenord anges i URL:en som hotkv://:password@host:6379.
• Ett värde kommer tillbaka avkortat. Resultatet flaggas som avkortat när det passerar --max-value-bytes. Höj gränsen eller lagra mindre värden.
• Ett skrivverktyg saknas. Leta efter --read-only i serverns argument eller HOTKV_MCP_READ_ONLY i dess miljö.
• Assistenten hittar inte ett namn den sparade tidigare. Kontrollera att den använde samma sessions- eller agentnamn, och att servern körs med samma namnrymd som förut.
• uvx hittas inte. Installera uv, eller installera paketet med pip och starta hotkv-mcp direkt.

Vanliga frågor