Serveur MCP pour la mémoire d’agent : connecter Claude Code à HotKV

Un serveur MCP est le moyen le plus simple de donner à un assistant IA une mémoire qui dure plus longtemps qu’une seule discussion. Claude Code, Cursor et les clients similaires perdent le contexte d’une discussion quand elle se termine. Leur donner un accès brut à une base de données pour y remédier est risqué. hotkv-mcp est notre serveur MCP open source pour HotKV. Il donne à un assistant un ensemble fixe d’outils pour des notes, l’historique de conversation, un journal d’événements, des modèles de prompts et la recherche de documents. Il n’offre rien d’autre.

En bref. hotkv-mcp est un serveur MCP sous licence Apache-2.0 qui connecte Claude Code, Cursor, VS Code ou votre propre agent à un serveur HotKV par 28 outils fixes. Il n’existe aucun outil qui exécute une commande arbitraire, l’assistant ne peut donc pas vider les données ni modifier la configuration. Un mode lecture seule retire tous les outils d’écriture, et un espace de noms confine l’agent à un préfixe de clés. Installez-le avec pip install hotkv-mcp ou exécutez-le avec uvx.

Ce qu’est le Model Context Protocol

Le Model Context Protocol, ou MCP, est un standard ouvert pour connecter des applications d’IA à des systèmes externes comme des sources de données, des outils et des flux de travail. L’introduction du projet le compare à un port USB-C pour les applications d’IA. En termes MCP, l’application est le client, et chaque système auquel elle se connecte est exposé par un serveur.

Pour la mémoire, cela signifie que l’assistant appelle un outil nommé, comme celui qui enregistre une note. Le serveur décide de ce que cet outil a le droit de faire. Le modèle n’obtient jamais de connexion à la base de données qui lui soit propre.

Ce qu’expose le serveur MCP de HotKV

Le serveur enveloppe la mémoire d’agent, le registre de prompts et la recherche de documents de HotKV dans 28 outils. Chaque outil déclare dans ses annotations MCP s’il ne fait que lire, écrire ou supprimer. Un client peut alors demander une approbation avant les outils destructeurs.

Les outils de mémoire correspondent aux stockages décrits dans mémoire d’agent IA, à savoir l’historique de conversation, les notes de travail et le journal d’événements. Le rappel sémantique par embedding n’est pas exposé. rag_search classe par pertinence de mots-clés, il n’en a donc pas besoin.

Les outils de clés, de hashes et de listes fonctionnent avec n’importe quel serveur HotKV. Les outils de mémoire, de prompts et de recherche de documents utilisent les moteurs d’IA de HotKV, qui nécessitent une licence les incluant. Sans elle, ces outils renvoient un message indiquant que le serveur n’est pas sous licence pour cette fonction. Les outils de clés continuent de fonctionner. Les instances HotKV Cloud Performance et Scale incluent les moteurs d’IA, comme le décrit la page IA.

Installer et connecter

Le serveur nécessite Python 3.10 ou plus récent. Il a été écrit pour HotKV serveur 0.3.0 et le paquet officiel hotkv-client, et la version 1.0.0 est sur PyPI. Installez-le avec pip, ou exécutez-le sans l’installer avec uv.

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

Claude Code

Ajoutez-le avec une seule commande. Le -- sépare les options propres à Claude Code de la commande qui démarre le serveur, comme le décrit la documentation MCP de Claude Code.

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

Cursor et Claude Desktop

Les clients qui lisent un fichier mcpServers acceptent le même serveur sous forme d’entrée JSON. Gardez le mot de passe dans la variable d’environnement HOTKV_URL ou dans le stockage de secrets du client. Une ligne de commande est visible des autres utilisateurs de la machine. Utilisez hotkvs:// pour une connexion TLS.

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

Vérifier que cela fonctionne

Exécutez claude mcp list pour confirmer que le serveur est enregistré. Demandez ensuite à l’assistant d’appeler l’outil server_info. Il renvoie la version de HotKV et l’utilisation de la mémoire, ainsi que le nombre de clés lorsqu’aucun espace de noms n’est défini. Il indique aussi si le serveur est en lecture seule et à quel espace de noms il est limité. Cela confirme que vos garde-fous ont pris effet.

Garder l’agent dans des limites sûres

Un modèle qui peut appeler des outils peut aussi être amené à en faire mauvais usage, les limites comptent donc plus que les fonctions.

Aucune commande arbitraire

Aucun outil n’exécute de commande brute. L’assistant ne peut pas vider une base de données ni modifier la configuration du serveur, car aucun des 28 outils ne le fait. Il peut lire toute clé que les outils atteignent, ce qui explique l’importance de l’espace de noms ci-dessous.

Mode lecture seule

--read-only retire tous les outils qui écrivent, dont set, delete, hash_set, list_push, les outils de mémoire qui ajoutent ou effacent, prompt_save, rag_create et rag_ingest. L’agent ne peut même pas les voir. Utilisez-le pour les assistants qui doivent consulter la mémoire sans jamais la modifier.

Espaces de noms et plafonds de taille

--namespace PREFIX stocke tout sous ce préfixe. L’agent ne voit jamais le préfixe et ne peut atteindre aucun autre nom. Donnez à chaque agent un préfixe qui n’est pas le début d’un autre. Utilisez agent-a et agent-b, pas agent et agent:b, sinon le plus court peut atteindre les noms du plus long.

Les résultats sont aussi plafonnés. --max-value-bytes tronque les longues valeurs et les signale comme tronquées, avec 65 536 octets par défaut. --max-items limite le nombre de clés, d’éléments de liste ou de résultats qu’un appel renvoie, 200 par défaut. Une seule valeur énorme ne peut donc pas inonder le contexte du modèle. La lecture d’un hash entier n’est pas plafonnée en nombre d’éléments, gardez donc les gros hashes hors de l’espace de noms d’un agent.

Le transport HTTP n’a pas d’authentification

Le transport stdio par défaut est démarré par le client comme sous-processus. Pour un usage partagé, vous pouvez exécuter hotkv-mcp --transport streamable-http, qui écoute sur 127.0.0.1:8000 à l’adresse /mcp. Il n’authentifie pas les appelants. Gardez-le sur localhost ou placez-le derrière un reverse proxy qui le fait, et donnez-lui son propre espace de noms.

Choisir une configuration pour une équipe

Les bons paramètres dépendent de l’usage de chaque agent. Chaque option ci-dessous est un paramètre de ligne de commande. --read-only et --namespace ont aussi des variables d’environnement, HOTKV_MCP_READ_ONLY et HOTKV_MCP_NAMESPACE.

Partez de la ligne la plus restrictive qui fait le travail. Il est facile d’élargir l’accès plus tard, et difficile de reprendre ce qu’un agent a déjà écrit.

Une première session, pas à pas

Un court essai montre ce que font les garde-fous avant que vous ne confiiez de vraies notes au serveur. Utilisez un espace de noms jetable et un serveur HotKV local sous licence pour les moteurs d’IA, car les outils de mémoire ne fonctionnent pas sans cette licence.

1. Connectez-vous avec un espace de noms. Exécutez claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Vérifiez les limites. Demandez à l’assistant d’appeler server_info et d’indiquer l’espace de noms et si le serveur est en lecture seule. Il doit répondre trial et pas en lecture seule.
3. Enregistrez une note. Demandez-lui de retenir que le site de préproduction se trouve à une adresse donnée, dans une note nommée d’après le site. L’assistant appelle memory_set_note, et la session est créée au premier usage.
4. Relisez-la dans une nouvelle discussion. Démarrez une conversation neuve et demandez quelles notes existent pour cette session. Il appelle memory_list_notes et memory_get_note, et la note est toujours là.
5. Journalisez une décision. Demandez-lui d’enregistrer une décision dans le journal d’événements. Il appelle memory_log_event, et memory_query_events la ramène plus tard.
6. Retirez son accès en écriture. Supprimez l’ancienne entrée, reconnectez-vous avec --read-only et répétez l’étape 4. La lecture fonctionne toujours, et les outils qui écrivent ne sont plus proposés.

Si l’étape 6 se comporte comme décrit, vous avez vu les deux contrôles qui comptent le plus, l’espace de noms et le mode lecture seule.

Traitez tout ce que l’assistant stocke comme du texte non fiable quand il est relu, comme l’explique l’article sur la mémoire dans traitez le texte stocké comme non fiable. Les notes écrites à partir de pages web peuvent contenir des instructions.

Dépannage

• « This HotKV server is not licensed for that feature. » Les outils de mémoire, de prompts et de recherche de documents nécessitent une licence HotKV qui inclut les moteurs d’IA. Les outils de clés, de hashes et de listes continuent de fonctionner sans elle.
• La connexion échoue. Vérifiez le schéma de l’URL. hotkv://, hotkvs:// (TLS), redis:// et rediss:// fonctionnent tous, et un mot de passe se place dans l’URL sous la forme hotkv://:password@host:6379.
• Une valeur revient tronquée. Le résultat est signalé comme tronqué quand il dépasse --max-value-bytes. Augmentez la limite ou stockez des valeurs plus petites.
• Un outil d’écriture manque. Cherchez --read-only dans les arguments du serveur ou HOTKV_MCP_READ_ONLY dans son environnement.
• L’assistant ne retrouve pas un nom qu’il a enregistré plus tôt. Vérifiez qu’il a utilisé le même nom de session ou d’agent, et que le serveur tourne avec le même espace de noms qu’avant.
• uvx est introuvable. Installez uv, ou installez le paquet avec pip et démarrez hotkv-mcp directement.

Questions fréquentes