# Connect via MCP — CacheBoost Docs

> Drive cache warming from Claude Desktop, Claude Code, or Cursor with the CacheBoost MCP server.

Source: https://www.cache-boost.com/support/mcp/overview.md
Language: en

---



Drive CacheBoost cache warming from an AI agent — Claude Desktop, Claude Code, or Cursor — using the CacheBoost MCP server.

The CacheBoost MCP server exposes cache warming and run monitoring as Model Context Protocol tools. An agent connected to the server can warm your critical URLs after a deployment and report back when the cache is hot — in natural language, without writing API calls by hand.

## Endpoint

The server is a single remote Streamable HTTP endpoint:

```
https://api.cache-boost.com/mcp
```

It runs on the same host as the REST API. The protocol is session-based: your MCP client performs the `initialize` handshake, receives an `Mcp-Session-Id` header, and replays it on every subsequent tool call. Compliant clients handle this automatically.

## Authentication

The MCP server uses your existing CacheBoost API key — there is no separate MCP credential. Create a key in the app under Profile → API Keys, grant it the scopes for the tools you intend to use (see the table below), then send it in the `X-API-Key` header:

```http
X-API-Key: cb_live_YOUR_KEY
```

`Authorization: Bearer cb_live_YOUR_KEY` is also accepted (and takes precedence when both are present), but `X-API-Key` works with every MCP client, including the Claude custom connector.

A missing or invalid key is rejected with `401`. The key's scopes and its optional site restriction apply exactly as they do on the REST API: a tool called without the required scope returns an explicit tool error (never a silent success), and a site outside the key's access is reported as not found.

## Add the server to your client

CacheBoost is listed in the official MCP registry (https://registry.modelcontextprotocol.io) as `com.cache-boost/cacheboost`. If your client can browse the registry, that is the short path; everything below it is the manual equivalent.

### From your client's server directory

Search for **CacheBoost** in your client's MCP directory, add it, and paste your `cb_live_…` key when it asks for `X-API-Key`. The endpoint and transport come from the listing — there is nothing else to configure.

If your client has no directory, register CacheBoost by hand as a remote (Streamable HTTP) MCP server with an `X-API-Key` header.

### Claude Code (CLI)

```bash
claude mcp add --transport http cacheboost https://api.cache-boost.com/mcp \
  --header "X-API-Key: cb_live_YOUR_KEY"
```

### Claude Desktop / Cursor

Add an entry to the MCP servers configuration:

```json
{
  "mcpServers": {
    "cacheboost": {
      "type": "http",
      "url": "https://api.cache-boost.com/mcp",
      "headers": {
        "X-API-Key": "cb_live_YOUR_KEY"
      }
    }
  }
}
```

### Claude (custom connector)

In Claude, open Settings → Connectors → Add custom connector and enter `https://api.cache-boost.com/mcp`. Then:

- **Authentication**: choose **No authentication** (CacheBoost uses an API key, not OAuth).
- **Request headers**: add `X-API-Key` with your key `cb_live_YOUR_KEY`. Do not use `Authorization` here: the connector does not send it.

## Available tools

Each tool mirrors the scope of its REST counterpart. Grant the API key only the scopes for the tools you need.

| Tool | Required scope | Description |
|------|----------------|-------------|
| `whoami` | — | Return the identity of the API key (user, scopes, site access). Useful to validate the connection. |
| `warm_site` | `boosts:write` | Warm a list of same-origin URLs for a site, create a run, and return its `run_id`. |
| `list_warm_runs` | `boosts:read` | List a site's on-demand warm runs to poll status after `warm_site`. |
| `get_run` | `runs:read` | Retrieve a single run with its status and cache-hit statistics. |
| `list_sites` | `sites:read` | List every site the key can access. |
| `get_site` | `sites:read` | Retrieve a single site by ID. |
| `list_runs` | `runs:read` | List runs across all of the key's sites. |

`warm_site` keeps the same business rules as the REST API: URLs must be same-origin with the site, at most 5000 URLs per call, duplicates are removed, quota is pre-checked, and a `409` is returned if a run is already in progress for the site.

## Example: warm critical URLs after a deploy

Once the server is connected, ask your agent in natural language, for example:

```
Warm the critical URLs of my site after this deploy and tell me when the cache is hot.
```

The agent calls the tools in sequence:

1. `warm_site(site_id, urls)` returns `{ run_id, url_count, status: "pending" }`.
2. `get_run(run_id)` (or `list_warm_runs(site_id)`) is polled until `status` is `done` or `failed`, then reports the cache-hit results.

## Compatibility

The server targets the stateful MCP protocol lineage up to `2025-11-25`. The newer stateless `2026-07-28` protocol is not yet supported; clients negotiate down to a supported version automatically.



---

**CacheBoost** — Automatic cache warming for faster websites.

- Website: https://www.cache-boost.com
- Full content (all pages): https://www.cache-boost.com/llms-full.txt
- LLM index: https://www.cache-boost.com/llms.txt
- Documentation: https://www.cache-boost.com/support/getting-started/introduction
- Start free: https://www.cache-boost.com/try