# MCP server

> Let AI assistants and agents (Claude, Cursor, VS Code, your own) read and write keys, agent memory, prompts and documents in HotKV with the hotkv-mcp server.

URL: https://docs.hotkv.com/ai/mcp-server/


`hotkv-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
server for HotKV. It lets an AI assistant or agent work with your HotKV server
through a fixed set of tools: read and write keys, keep conversation memory
and notes, log events, store prompt templates and search documents.

It is open source (Apache-2.0):
[github.com/hotkv-ltd/hotkv-mcp](https://github.com/hotkv-ltd/hotkv-mcp).

There is no tool that runs an arbitrary command, so an agent cannot flush a
database, change the server's configuration or read another tenant's data.

## Install

```bash
pip install hotkv-mcp
```

Or run it without installing, with [uv](https://docs.astral.sh/uv/):

```bash
uvx hotkv-mcp --url hotkv://localhost:6379
```

It needs Python 3.10 or newer.

## Connect a client

The server speaks stdio by default, so a client starts it as a subprocess.

**Claude Code**

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

**Claude Desktop, Cursor and other clients that read an `mcpServers` file**

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

Keep the password in `HOTKV_URL` or in the client's secret store, not on the
command line, where other users of the machine can see it. Use `hotkvs://` for
a TLS connection.

## Options

| Option | Environment | Meaning |
| --- | --- | --- |
| `--url URL` | `HOTKV_URL` | Server to use. Default `hotkv://127.0.0.1:6379`. `hotkvs://`, `redis://` and `rediss://` also work. |
| `--read-only` | `HOTKV_MCP_READ_ONLY=1` | Offer read tools only. |
| `--namespace PREFIX` | `HOTKV_MCP_NAMESPACE` | Store everything under `PREFIX:`. The agent never sees the prefix and cannot reach other names. |
| `--max-value-bytes N` | `HOTKV_MCP_MAX_VALUE_BYTES` | Cut longer values. Default 65536. |
| `--max-items N` | `HOTKV_MCP_MAX_ITEMS` | Most keys, rows or hits per call. Default 200. |
| `--transport` | | `stdio` (default) or `streamable-http`. |
| `--host`, `--port` | | Bind address for `streamable-http`. Default `127.0.0.1:8000`, path `/mcp`. |

Command line options win over the environment.

Namespaces are plain prefixes. Give each agent a namespace that is not itself a
prefix of another (`agent-a` and `agent-b`, not `agent` and `agent:b`), or the
shorter one can reach the longer one's names.

## Tools

| Group | Tools |
| --- | --- |
| Server | `server_info` |
| Keys | `get`, `set`, `delete`, `key_info`, `scan` |
| Hashes | `hash_get`, `hash_set` |
| Lists | `list_range`, `list_push` |
| Conversation memory | `memory_append_message`, `memory_get_messages`, `memory_clear_messages` |
| Working notes | `memory_set_note`, `memory_get_note`, `memory_list_notes` |
| Event log | `memory_log_event`, `memory_query_events` |
| Rolling summary | `memory_set_summary`, `memory_get_summary` |
| Prompt registry | `prompt_save`, `prompt_get`, `prompt_versions`, `prompt_list` |
| Document search | `rag_create`, `rag_ingest`, `rag_search`, `rag_list` |

Each tool says in its annotations whether it only reads, writes or deletes, so
a client can ask for approval before the destructive ones. With `--read-only`
the tools that write are not registered at all, so the agent cannot see them.

Results are capped by `--max-value-bytes` and `--max-items`. A value that was
cut comes back with `truncated` set, so a huge value cannot flood the model's
context.

## Licensing

The key, hash and list tools work on any HotKV server. The memory, prompt
registry and document search tools use the AI engines of the server
([agent memory](https://docs.hotkv.com/ai-features/index.md#agent-memory-amem), the
[prompt registry](https://docs.hotkv.com/ai-features/index.md#also-included-prompt-registry) and
[RAG](https://docs.hotkv.com/ai-features/index.md#rag-pipeline-rag)), which need a license that includes
them. Without one, those tools answer "This HotKV server is not licensed for
that feature" and the others keep working.

`rag_search` ranks by keyword relevance, so it needs no embedding model.

## Running over HTTP

```bash
hotkv-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

> **Caution**
> The HTTP server does not authenticate callers. Keep it on localhost, or put it
> behind a reverse proxy that does, and give it its own `--namespace` and
> `--read-only` where you can. Starting it on another address prints a warning.

## Next steps

- [AI features guide](https://docs.hotkv.com/ai-features/index.md)
- [LangGraph checkpointer and store](https://docs.hotkv.com/ai/langgraph/index.md)
- [Caching gateway](https://docs.hotkv.com/ai/gateway/index.md)