> For the complete documentation index, see [llms.txt](https://docs.mozilla.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozilla.ai/mcpd/configuration/caching.md).

# Registry Caching

`mcpd` includes a built-in caching system to improve performance when working with remote MCP server registries. The caching system stores registry manifests locally to avoid repeated network requests.

## Cache Directory

All commands that access remote registries ([add](/mcpd/cli-reference/mcpd_add.md) and [search](/mcpd/cli-reference/mcpd_search.md)) support optional parameters to configure caching behavior.

You can specify the cache directory in multiple ways:

* CLI flag: `--cache-dir <path>`
* Default: `~/.cache/mcpd/registries/`

{% hint style="info" %}
**XDG\_CACHE\_HOME environment variable**

`mcpd` honors the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/), respecting the `XDG_CACHE_HOME` environment variable. This forms the base directory where `mcpd` will create a cache folder for registry manifests.
{% endhint %}

## Cache Time-to-Live (TTL)

You can configure how long cached registry manifests remain valid:

* CLI flag: `--cache-ttl <duration>`
* Default: `24h`

The duration format accepts values like:

* `1h` (1 hour)
* `30m` (30 minutes)
* `24h` (24 hours)
* `1h30m` (1 hour 30 minutes)

## Caching Control

### Disabling Cache

To disable caching entirely and always fetch fresh data:

```bash
mcpd add my-server --no-cache
mcpd search my-query --no-cache
```

### Refreshing Cache

To force refresh cached manifests (ignoring TTL):

```bash
mcpd add my-server --refresh-cache
mcpd search my-query --refresh-cache
```

## Cache Behavior

### When Caching is Enabled (Default)

1. **First Request**: Downloads registry manifest from remote URL and stores it in the cache directory
2. **Subsequent Requests**: Uses cached file if it exists and hasn't expired (based on TTL)
3. **Expired Cache**: Automatically downloads fresh manifest when TTL expires
4. **Cache Miss**: Falls back to remote URL if cache file is corrupted or missing

### When Caching is Disabled

1. **No Directory Creation**: Cache directory is never created on the filesystem
2. **Always Remote**: All requests go directly to remote registry URLs
3. **No Storage**: No files are written to disk

### Cache File Naming

Cache files are stored using SHA-256 hashes of the registry URLs:

```
~/.cache/mcpd/registries/
├── a1b2c3d4e5f6...1234.json  # mcpm registry manifest
└── ...
```

## Examples

### Basic Usage with Custom Cache Directory

```bash
# Use temporary cache directory
mcpd add github-mcp --cache-dir /tmp/mcpd-cache

# Set custom TTL to 1 hour
mcpd search database --cache-ttl 1h
```

### Combining Cache Options

```bash
# Custom directory with forced refresh
mcpd search api --cache-dir ./project-cache --refresh-cache

# Disable caching but specify directory (directory won't be created)
mcpd add server --no-cache --cache-dir /unused/path
```

## Common Issues

If registry results look stale, retry with `--refresh-cache` or bypass cache once with `--no-cache`.

If cache directory creation fails, ensure:

* Parent directory is writable
* Sufficient disk space is available
* No conflicting file already exists at the cache path

For step-by-step diagnosis of registry lookup or cache problems, see [Troubleshooting](/mcpd/troubleshooting.md).

{% hint style="success" %}
**Performance**

Caching significantly improves performance for repeated operations. The default 24-hour TTL provides a good balance between freshness and performance for most use cases.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mozilla.ai/mcpd/configuration/caching.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.