Servidor MCP para la memoria de agentes: conecta Claude Code a HotKV

Un servidor MCP es la forma más sencilla de dar a un asistente de IA una memoria que dure más que un chat. Claude Code, Cursor y clientes similares pierden el contexto de un chat cuando termina. Darles acceso directo a una base de datos para arreglarlo es arriesgado. hotkv-mcp es nuestro servidor MCP de código abierto para HotKV. Da al asistente un conjunto fijo de herramientas para notas, historial de conversación, un registro de eventos, plantillas de prompts y búsqueda de documentos. No ofrece nada más.

En resumen. hotkv-mcp es un servidor MCP con licencia Apache-2.0 que conecta Claude Code, Cursor, VS Code o tu propio agente con un servidor HotKV mediante 28 herramientas fijas. No hay ninguna herramienta que ejecute un comando arbitrario, así que el asistente no puede vaciar datos ni cambiar la configuración. Un modo de solo lectura elimina todas las herramientas de escritura, y un espacio de nombres confina al agente a un prefijo de claves. Instálalo con pip install hotkv-mcp o ejecútalo con uvx.

Qué es el Model Context Protocol

El Model Context Protocol, o MCP, es un estándar abierto para conectar aplicaciones de IA con sistemas externos, como fuentes de datos, herramientas y flujos de trabajo. La introducción del proyecto lo compara con un puerto USB-C para aplicaciones de IA. En términos de MCP, la aplicación es el cliente, y cada sistema al que se conecta lo expone un servidor.

Para la memoria, eso significa que el asistente llama a una herramienta con nombre, como una que guarda una nota. El servidor decide qué puede hacer esa herramienta. El modelo nunca obtiene una conexión propia a la base de datos.

Qué expone el servidor MCP de HotKV

El servidor envuelve la memoria de agentes, el registro de prompts y la búsqueda de documentos de HotKV en 28 herramientas. Cada herramienta declara en sus anotaciones MCP si solo lee, escribe o elimina. Así, un cliente puede pedir aprobación antes de las destructivas.

Las herramientas de memoria se corresponden con los almacenes descritos en memoria de agentes de IA, a saber, el historial de conversación, las notas de trabajo y el registro de eventos. La recuperación semántica por embedding no se expone. rag_search ordena por relevancia de palabras clave, así que no la necesita.

Las herramientas de claves, hashes y listas funcionan con cualquier servidor HotKV. Las herramientas de memoria, prompts y búsqueda de documentos usan los motores de IA de HotKV, que necesitan una licencia que los incluya. Sin ella, esas herramientas devuelven un mensaje que dice que el servidor no tiene licencia para esa función. Las herramientas de claves siguen funcionando. Las instancias Performance y Scale de HotKV Cloud incluyen los motores de IA, como describe la página de IA.

Instalar y conectar

El servidor necesita Python 3.10 o posterior. Se escribió contra HotKV server 0.3.0 y el paquete oficial hotkv-client, y la versión 1.0.0 está en PyPI. Instálalo con pip, o ejecútalo sin instalar con uv.

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

Claude Code

Añádelo con un solo comando. El -- separa las opciones propias de Claude Code del comando que inicia el servidor, como describe la documentación de MCP de Claude Code.

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

Cursor y Claude Desktop

Los clientes que leen un archivo mcpServers aceptan el mismo servidor como una entrada JSON. Guarda la contraseña en la variable de entorno HOTKV_URL o en el almacén de secretos del cliente. Una línea de comandos es visible para otros usuarios de la máquina. Usa hotkvs:// para una conexión TLS.

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

Comprueba que funciona

Ejecuta claude mcp list para confirmar que el servidor está registrado. Luego pide al asistente que llame a la herramienta server_info. Devuelve la versión de HotKV y el uso de memoria, además del número de claves cuando no hay un espacio de nombres definido. También indica si el servidor es de solo lectura y a qué espacio de nombres está limitado. Eso confirma que tus salvaguardas han surtido efecto.

Mantén al agente dentro de límites seguros

Un modelo que puede llamar a herramientas también puede ser convencido de que las use mal, así que los límites importan más que las funciones.

Sin comandos arbitrarios

No hay ninguna herramienta que ejecute un comando en bruto. El asistente no puede vaciar una base de datos ni cambiar la configuración del servidor, porque ninguna de las 28 herramientas hace eso. Puede leer cualquier clave a la que lleguen las herramientas, y por eso importa el espacio de nombres de más abajo.

Modo de solo lectura

--read-only elimina todas las herramientas que escriben, entre ellas set, delete, hash_set, list_push, las herramientas de memoria que añaden o borran, prompt_save, rag_create y rag_ingest. El agente ni siquiera las ve. Úsalo con asistentes que deban consultar la memoria pero nunca cambiarla.

Espacios de nombres y límites de tamaño

--namespace PREFIX guarda todo bajo ese prefijo. El agente nunca ve el prefijo y no puede alcanzar otros nombres. Da a cada agente un prefijo que no sea el comienzo de otro. Usa agent-a y agent-b, no agent y agent:b, o el más corto podrá alcanzar los nombres del más largo.

Los resultados también tienen un tope. --max-value-bytes corta los valores largos y los marca como truncados, con un valor por defecto de 65.536 bytes. --max-items limita cuántas claves, elementos de lista o resultados devuelve una llamada, 200 por defecto. Así, un único valor enorme no puede inundar el contexto del modelo. La lectura de un hash completo no tiene límite de elementos, así que mantén los hashes grandes fuera del espacio de nombres de un agente.

El transporte HTTP no tiene inicio de sesión

El transporte stdio por defecto lo inicia el cliente como un subproceso. Para un uso compartido puedes ejecutar hotkv-mcp --transport streamable-http, que escucha en 127.0.0.1:8000 en /mcp. No autentica a quien llama. Mantenlo en localhost o ponlo detrás de un proxy inverso que sí lo haga, y dale su propio espacio de nombres.

Elegir una configuración para un equipo

Las banderas adecuadas dependen de para qué sirve cada agente. Todas las opciones de abajo son banderas de línea de comandos. --read-only y --namespace también tienen variables de entorno, HOTKV_MCP_READ_ONLY y HOTKV_MCP_NAMESPACE.

Empieza por la fila más restringida que haga el trabajo. Es fácil ampliar el acceso más tarde y difícil deshacer lo que un agente ya ha escrito.

Una primera sesión, paso a paso

Una prueba corta muestra qué hacen las salvaguardas antes de confiar al servidor notas reales. Usa un espacio de nombres desechable y un servidor HotKV local con licencia para los motores de IA, porque las herramientas de memoria no funcionan sin esa licencia.

1. Conecta con un espacio de nombres. Ejecuta claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Comprueba los límites. Pide al asistente que llame a server_info e informe del espacio de nombres y de si el servidor es de solo lectura. Debería decir trial y que no es de solo lectura.
3. Guarda una nota. Pídele que recuerde que el sitio de staging está en una dirección dada, bajo una nota con el nombre del sitio. El asistente llama a memory_set_note, y la sesión se crea en el primer uso.
4. Léela en un chat nuevo. Inicia una conversación nueva y pregunta qué notas existen para esa sesión. Llama a memory_list_notes y memory_get_note, y la nota sigue ahí.
5. Registra una decisión. Pídele que anote una decisión en el registro de eventos. Llama a memory_log_event, y memory_query_events la recupera más tarde.
6. Quítale el acceso de escritura. Elimina la entrada antigua, reconecta con --read-only y repite el paso 4. La lectura sigue funcionando, y las herramientas que escriben ya no se ofrecen.

Si el paso 6 se comporta como se describe, has visto los dos controles que más importan, el espacio de nombres y el modo de solo lectura.

Trata todo lo que el asistente guarda como texto no fiable cuando se lee de vuelta, como explica el artículo sobre memoria en tratar el texto guardado como no fiable. Las notas escritas a partir de páginas web pueden contener instrucciones.

Solución de problemas

• "This HotKV server is not licensed for that feature." Las herramientas de memoria, prompts y búsqueda de documentos necesitan una licencia de HotKV que incluya los motores de IA. Las herramientas de claves, hashes y listas siguen funcionando sin ella.
• La conexión falla. Comprueba el esquema de la URL. hotkv://, hotkvs:// (TLS), redis:// y rediss:// funcionan, y la contraseña va en la URL como hotkv://:password@host:6379.
• Un valor llega cortado. El resultado se marca como truncado cuando supera --max-value-bytes. Sube el límite o guarda valores más pequeños.
• Falta una herramienta de escritura. Busca --read-only en los argumentos del servidor o HOTKV_MCP_READ_ONLY en su entorno.
• El asistente no encuentra un nombre que guardó antes. Comprueba que haya usado el mismo nombre de sesión o de agente, y que el servidor se ejecute con el mismo espacio de nombres que antes.
• No se encuentra uvx. Instala uv, o instala el paquete con pip e inicia hotkv-mcp directamente.

Preguntas frecuentes