> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Claude to Cache-Pot using the built-in MCP server

> Cache-Pot includes a built-in MCP server. Add it to Claude Desktop or Claude Code so your AI agent can get, set, search, and remember values directly.

Cache-Pot includes a native [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Run `cache-pot mcp` to expose your running Cache-Pot instance as an MCP tool provider — AI agents like Claude can then read, write, search, and remember data directly through natural language, with no adapter layer or custom wrapper service in between.

## Prerequisites

Before configuring the MCP integration, make sure you have the following in place:

* A running Cache-Pot server (default address: `localhost:6379`)
* The `cache-pot` binary available on your `PATH`
* Claude Desktop or Claude Code for the configuration examples below

## Starting the MCP server

The MCP server runs as a subprocess and communicates with its host (Claude Desktop or Claude Code) over stdin/stdout using JSON-RPC 2.0. It connects to your Cache-Pot server over the standard RESP2 protocol.

```bash theme={null}
cache-pot mcp --addr localhost:6379
```

The `--addr` flag accepts any `host:port` that resolves to a running Cache-Pot server. You can also set it via the `CACHEPOT_MCP_ADDR` environment variable. The default is `localhost:6379`.

<Info>
  You do not run this command manually in normal usage — your MCP host (Claude Desktop, Claude Code) launches it as a subprocess and manages its lifecycle automatically.
</Info>

You can verify the bridge works without a full MCP client by driving it over stdin directly:

```bash theme={null}
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | cache-pot mcp --addr localhost:6379
```

You should see an `initialize` result followed by the tool catalogue listing all five tools.

## Claude Desktop integration

<Steps>
  <Step title="Find your Claude Desktop config file">
    The configuration file location depends on your operating system:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    Create the file if it does not exist.
  </Step>

  <Step title="Add the Cache-Pot MCP server">
    Add the following entry to your `claude_desktop_config.json`. If the file already has an `mcpServers` object, add the `cache-pot` key alongside your existing entries.

    ```json theme={null}
    {
      "mcpServers": {
        "cache-pot": {
          "command": "cache-pot",
          "args": ["mcp", "--addr", "localhost:6379"]
        }
      }
    }
    ```

    <Tip>
      If `cache-pot` is not on your system `PATH`, replace `"command": "cache-pot"` with the absolute path to the binary, for example `"command": "/usr/local/bin/cache-pot"`.
    </Tip>
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen Claude Desktop so it picks up the updated configuration. Claude reads the MCP server list once on startup.
  </Step>

  <Step title="Confirm the tools appear">
    Open a new Claude conversation. The Cache-Pot tools now appear in Claude's tool list. You can ask Claude to use them directly in natural language — for example: *"Set the key `deploy:status` to `green`."*
  </Step>
</Steps>

## Claude Code integration

Add Cache-Pot to Claude Code with a single command:

```bash theme={null}
claude mcp add cache-pot -- cache-pot mcp --addr localhost:6379
```

Then use the tools conversationally in any Claude Code session:

```
> set the key "deploy:status" to "green"
> what's stored at deploy:status?
> remember in session "proj-x" that the owner is Alice
> recall everything you know about session "proj-x"
```

## Available MCP tools

Cache-Pot exposes five tools over MCP. Each tool maps directly to one or more Cache-Pot commands.

| Tool       | Parameters                                                       | Description                                                                                             |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `get`      | `key` (required)                                                 | Retrieve a string value by key. Maps to `GET`.                                                          |
| `set`      | `key`, `value` (required); `ttl_seconds` (optional)              | Store a string value with an optional expiry. Maps to `SET ... EX`.                                     |
| `search`   | `prompt` (required); `threshold` float (optional, default `0.9`) | Semantic search — returns a cached response if a stored prompt is similar enough. Maps to `SCACHE.GET`. |
| `remember` | `session`, `key`, `value` (required)                             | Store a named fact under a session namespace. Maps to `REMEMBER`.                                       |
| `recall`   | `session` (required); `key` (optional)                           | Retrieve one field or all memory fields for a session. Maps to `RECALL`.                                |

<Note>
  The `search` tool requires `CACHEPOT_EMBED_URL` to be configured on the Cache-Pot server. The `get`, `set`, `remember`, and `recall` tools work without any embeddings configuration.
</Note>

## Example agent workflow

Give Claude a natural-language instruction and it will automatically select and call the appropriate tools. For example, try this prompt:

> "Remember that the user's name is Alice and that she prefers Python code examples. Then recall everything you know about this session."

Claude will call `remember` twice — once for `user_name` and once for `code_preference` — and then call `recall` to read back the full session and confirm what it stored.

A more realistic session might look like this:

> "Check whether you have a cached answer for 'what is the difference between TCP and UDP'. If not, I'll tell you the answer and you should cache it."

Claude will call `search` with the prompt, see a cache miss, ask you for the answer, and then call `set` or `remember` to persist it for next time.

<Tip>
  Combine the MCP tools with Cache-Pot's RESP2 commands in the same deployment. Your application code can write vectors and session memory over RESP2 while Claude reads and updates that same data through MCP — they share the same in-memory store.
</Tip>