MCP server for agent memory: connect Claude Code to HotKV

An MCP server is the simplest way to give an AI assistant a memory that lasts longer than one chat. Claude Code, Cursor and similar clients lose the context of a chat when it ends. Handing them raw database access to fix that is risky. hotkv-mcp is our open-source MCP server for HotKV. It gives an assistant a fixed set of tools for notes, conversation history, an event log, prompt templates and document search. It offers nothing else.

In short. hotkv-mcp is an Apache-2.0 MCP server that connects Claude Code, Cursor, VS Code or your own agent to a HotKV server through 28 fixed tools. There is no tool that runs an arbitrary command, so the assistant cannot flush data or change configuration. A read-only mode removes every write tool, and a namespace confines the agent to one key prefix. Install it with pip install hotkv-mcp or run it with uvx.

What the Model Context Protocol is

The Model Context Protocol, or MCP, is an open standard for connecting AI applications to external systems such as data sources, tools and workflows. The project's introduction compares it to a USB-C port for AI applications. In MCP terms the application is the client, and each system it connects to is exposed by a server.

For memory that means the assistant calls a named tool, such as one that saves a note. The server decides what that tool may do. The model never gets a database connection of its own.

What the HotKV MCP server exposes

The server wraps HotKV's agent memory, prompt registry and document search in 28 tools. Each tool declares in its MCP annotations whether it only reads, writes or deletes. A client can then ask for approval before the destructive ones.

The memory tools map onto the stores described in AI agent memory, namely conversation history, working notes and the event log. Semantic recall by embedding is not exposed. rag_search ranks by keyword relevance, so it needs none.

The key, hash and list tools work against any HotKV server. The memory, prompt and document search tools use HotKV's AI engines, which need a licence that includes them. Without one, those tools return a message that the server is not licensed for the feature. The key tools keep working. HotKV Cloud Performance and Scale instances include the AI engines, as the AI page describes.

Install and connect

The server needs Python 3.10 or newer. It was written against HotKV server 0.3.0 and the official hotkv-client package, and version 1.0.0 is on PyPI. Install it with pip, or run it without installing using uv.

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

Claude Code

Add it with one command. The -- separates Claude Code's own options from the command that starts the server, as the Claude Code MCP documentation describes.

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

Cursor and Claude Desktop

Clients that read an mcpServers file take the same server as a JSON entry. Keep the password in the HOTKV_URL environment variable or the client's secret store. A command line is visible to other users of the machine. Use hotkvs:// for a TLS connection.

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

Check that it works

Run claude mcp list to confirm the server is registered. Then ask the assistant to call the server_info tool. It returns the HotKV version and memory use, plus the key count when no namespace is set. It also reports whether the server is read-only and which namespace it is limited to. That confirms your safeguards took effect.

Keep the agent inside safe limits

A model that can call tools can also be talked into misusing them, so the limits matter more than the features.

No arbitrary commands

There is no tool that runs a raw command. The assistant cannot flush a database or change the server's configuration, because none of the 28 tools does those things. It can read any key the tools reach, which is why the namespace below matters.

Read-only mode

--read-only removes every tool that writes, including set, delete, hash_set, list_push, the memory tools that add or clear, prompt_save, rag_create and rag_ingest. The agent cannot even see them. Use it for assistants that should consult memory but never change it.

Namespaces and size caps

--namespace PREFIX stores everything under that prefix. The agent never sees the prefix and cannot reach other names. Give each agent a prefix that is not the start of another. Use agent-a and agent-b, not agent and agent:b, or the shorter one can reach the longer one's names.

Results are capped too. --max-value-bytes cuts long values and flags them as truncated, with a default of 65,536 bytes. --max-items limits how many keys, list items or hits a call returns, 200 by default. A single huge value therefore cannot flood the model's context. Reading a whole hash is not item-capped, so keep large hashes out of an agent's namespace.

The HTTP transport has no login

The default stdio transport is started by the client as a subprocess. For shared use you can run hotkv-mcp --transport streamable-http, which listens on 127.0.0.1:8000 at /mcp. It does not authenticate callers. Keep it on localhost or put it behind a reverse proxy that does, and give it its own namespace.

Choosing a setup for a team

The right flags depend on what each agent is for. Every option below is a command-line flag. --read-only and --namespace also have environment variables, HOTKV_MCP_READ_ONLY and HOTKV_MCP_NAMESPACE.

Start from the most restricted row that does the job. It is easy to widen access later, and hard to take back what an agent has already written.

A first session, step by step

A short trial shows what the safeguards do before you trust the server with real notes. Use a throwaway namespace and a local HotKV server that is licensed for the AI engines, because the memory tools do not work without that licence.

1. Connect with a namespace. Run claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Check the limits. Ask the assistant to call server_info and report the namespace and whether the server is read-only. It should say trial and not read-only.
3. Save a note. Ask it to remember that the staging site lives at a given address, under a note named after the site. The assistant calls memory_set_note, and the session is created on first use.
4. Read it back in a new chat. Start a fresh conversation and ask what notes exist for that session. It calls memory_list_notes and memory_get_note, and the note is still there.
5. Log a decision. Ask it to record a decision in the event log. It calls memory_log_event, and memory_query_events brings it back later.
6. Remove its write access. Remove the old entry, reconnect with --read-only and repeat step 4. Reading still works, and the tools that write are no longer offered.

If step 6 behaves as described, you have seen the two controls that matter most, the namespace and read-only mode.

Treat whatever the assistant stores as untrusted text when it is read back, as the memory article explains in treating stored text as untrusted. Notes written from web pages can carry instructions.

Troubleshooting

• "This HotKV server is not licensed for that feature." The memory, prompt and document search tools need a HotKV licence that includes the AI engines. The key, hash and list tools keep working without one.
• The connection fails. Check the URL scheme. hotkv://, hotkvs:// (TLS), redis:// and rediss:// all work, and a password goes in the URL as hotkv://:password@host:6379.
• A value comes back cut. The result is flagged as truncated when it passes --max-value-bytes. Raise the limit or store smaller values.
• A write tool is missing. Look for --read-only in the server's arguments or HOTKV_MCP_READ_ONLY in its environment.
• The assistant cannot find a name it saved earlier. Check that it used the same session or agent name, and that the server runs with the same namespace as before.
• uvx is not found. Install uv, or install the package with pip and start hotkv-mcp directly.

Frequently asked questions