# Tune WordPress cache settings with Claude Code

> Tuning cache settings with Claude Code means asking it, from the terminal, to read an xSpeed module's current values on a WordPress site, propose a change, and write it through xSpeed Hub once you agree.

Page: https://xspeedcache.com/agent/claude-code/cache-settings/
Last updated: October 2026

You are in the repository for a content site, and pages that should stay cached for days keep getting rebuilt after a few hours. Instead of opening wp-admin, you type what you want in plain words: keep cached pages for three days on shop, and leave the checkout out of the cache. Claude Code calls list_sites to match the name, then list_modules to see which modules the site has and what settings each one exposes, then get_settings for the cache module so it starts from the real current values.

What comes back is a proposal, not a write. Claude Code shows the current cache expiry in hours, the number it wants instead, and the exclusion it would add, and the Hub tells it to briefly confirm intent before calling update_settings. Once you agree, the call runs and returns the module's settings as stored. Each site checks values against its own schema, so one bad key or value refuses the whole call with a reason and nothing is written, and a setting that belongs to a Pro module is refused on a site without a licence. Credential fields, such as a Cloudflare token or a Redis password, are refused over the Hub and stay in the dashboard.

What differs in Claude Code is where the check lives. Every xSpeed tool has its own name, so a permission rule such as mcp__xspeedhub__get_* can allow the tools whose names start with get_ and leave update_settings and toggle_cache on the prompt. The Hub's request to confirm is guidance to the model, not a lock; your Claude Code prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates. For several sites in one go, the agent passes site: "all" and the Hub tells it to say "this will touch all N sites" first.

## Set up Claude Code once

### 1. Put your sites in xSpeed Hub

Sign in at app.xspeedcache.com with Google or email; the Hub is free and has no site cap. Then connect each WordPress site from its own dashboard: click Connect Hub in the xSpeed Cache top bar, then Connect via xSpeed Hub. Each site needs the free xSpeed Cache plugin.

### 2. Add xSpeed Hub to Claude Code

Run this once. --scope user makes the server available in every project; leave it off and it applies to the current project only, which is Claude Code's default.

```bash
claude mcp add --transport http --scope user xspeedhub https://app.xspeedcache.com/xspeed/mcp
```

### 3. Sign in with /mcp

Start Claude Code, run /mcp, pick xspeedhub and finish the sign-in in your browser. You approve access on an xSpeed Hub page; there is no token to paste, and Claude Code keeps the credentials it receives and refreshes them.

```
/mcp
```

Full setup: https://xspeedcache.com/agent/claude-code/

### Before you send a prompt that changes something

Reads change nothing on your sites, though contact_support emails xSpeed support. Writes run once your connection allows them, so your client's approval prompt and a read-only connection (the token's Read-only everywhere switch, or a Viewer sign-in) are the gates that matter. Claude Code asks before it runs an MCP tool unless a permission rule already allows it, or you work in auto mode, where a classifier reviews actions instead of you, or in bypassPermissions mode, which skips prompts. A rule such as mcp__xspeedhub__get_cache_status allows one tool, and mcp__xspeedhub__get_* allows every read whose name starts with get_. Keep purge_cache, update_settings, toggle_cache and the other write tools on the prompt, because the Hub itself runs a write as soon as your connection allows it.

## Prompts

- Use xSpeed Hub to list the modules on shop, then show me the cache expiry and exclusions and tell me which look wrong for a store that updates once a day.
- With xSpeed Hub, set the page cache lifetime to 72 hours on blog only. Read the current value first and tell me the change before you write it.
- Ask xSpeed Hub to turn page caching back on for staging, then confirm with get_cache_status that it is on.

## Example session

```
You: Pages on shop get rebuilt too often. Use xSpeed Hub to keep them cached for three days.
  → get_settings(site: shop, module: cache) [read-only]: cache expiry 24 hours, 4 excluded URLs
Agent: Expiry is 24 hours. Three days is 72. I would change only that value and leave the exclusions as they are. Apply it to shop?
You: Yes.
  → update_settings(site: shop, module: cache, values: { cache_expiry: 72 }) [changes site]: stored, cache expiry now 72 hours
Agent: Done. Pages already cached keep their old age until they expire or you purge; ask and I will purge the shop cache.
```

## How it works

1. **List the modules**: list_modules returns every Free and Pro module available on one site, with its settings schema and status. It tells the agent which module slugs exist, such as minify or gzip, and what each setting accepts.
2. **Read the current settings**: get_settings takes a module slug and returns its settings. Credential fields come back masked, so an agent cannot read a stored API token or password back in plain text.
3. **Change them**: update_settings takes the module and a values object of setting keys. The site checks the whole object first. If any key is unknown, any value is outside the schema, or a field is pinned by a constant in wp-config.php, it refuses the write, writes nothing and says which keys and why, sometimes with a "did you mean" hint.
4. **Turn page caching on or off**: Page caching has its own tool, toggle_cache, because it installs or removes the cache drop-in and the WP_CACHE constant. Asking update_settings to set cache_enabled does not work and is refused. If another caching plugin owns the drop-in, the site declines to enable xSpeed and returns blocked: true with the reason.
5. **Check the effect**: The result of a settings write is the stored settings. A module can add a warning when a setting is saved but has no effect on this server, for example Brotli on a server without the module for it, and the agent should pass that on. run_benchmark then times cached against uncached to see whether the change helped.
6. **Apply to many sites only after reading one**: update_settings and toggle_cache accept site: "all" or a list of handles. Each site validates against its own schema and answers in its own row, so a module missing on one site fails that row and the others still apply. Read one site first, then apply.

## Reference

| | |
| --- | --- |
| Discover | list_modules (read): Free and Pro modules, settings schema, status, per site |
| Read settings | get_settings (read): argument module; credential fields masked |
| Change settings | update_settings (write): arguments module and values; validated by the site |
| Bad input | The whole write is refused and nothing is written; the error names the keys and reasons |
| Page cache on or off | toggle_cache (write): argument enabled; cache_enabled in update_settings is refused |
| Blocked by another plugin | toggle_cache returns blocked: true with blocked_reason when another plugin owns the cache drop-in |
| Every site at once | update_settings and toggle_cache accept site: "all" or a list of handles, one result per site |
| Pro modules | A Pro module on a site without an active licence cannot be read or written; the site refuses |
| Credential fields | Refused by default over MCP; set them in the xSpeed dashboard, not through the agent |
| Read-only connection | The connection token with Read-only everywhere on, or a Viewer member's sign-in: update_settings and toggle_cache are refused; list_modules and get_settings still work. An OAuth sign-in gets the scopes the client asks for, read and write by default, clamped to the member's role |
| Confirmation | None on the Hub; the Hub tells the agent to briefly confirm intent for these two, and your client's prompt is the gate |

## Rules

- Read before you write. Ask for list_modules and get_settings first, so the agent changes real keys with valid values instead of guessing.
- update_settings and toggle_cache change how a live site behaves. They run as soon as your connection allows writes. The Hub tells the agent to briefly confirm intent first, which is guidance to the agent, so your client's approval prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates. The switch does not limit an OAuth sign-in.
- For site: "all", the Hub tells the agent to confirm once with "this will touch all N sites", then make one call. The result is per site, and some sites failing is a partial result to report, not a blanket success or failure.
- Do not ask an agent to set credentials such as a Cloudflare token or Redis password. The site refuses those writes by default, and they belong in the xSpeed dashboard.
- If a settings result says a value is saved but inactive on this server, relay that. Do not tell the user the feature is enabled.

## Good to know with Claude Code

If you allowed mcp__xspeedhub__* in your permission rules, update_settings and toggle_cache stop prompting, and the Hub's request to confirm intent becomes the only check. Auto mode, where a classifier reviews actions instead of you, and bypassPermissions mode, which asks nothing, skip the prompt too. Allow the read tools by name, such as list_modules and get_settings, and keep the two write tools on the prompt. A server added without the user scope also vanishes in other projects, so a settings change may fail only because you started Claude Code in a different folder.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Use xSpeed Hub to list the modules on shop and tell me which ones are off.
- Ask xSpeed Hub for the current minify settings on blog.
- With xSpeed Hub, turn on HTML minification on blog, then benchmark the cache and tell me if it helped.
- Use xSpeed Hub to turn page caching off on staging while I debug, and tell me when it is off.
- Using xSpeed Hub, read the gzip settings on shop first, then enable the same options on every site.
- Use xSpeed Hub to set the page cache lifespan on docs to 30 days, and if the site refuses it, tell me why.

## Frequently asked questions

### Can Claude Code change a cache setting and undo it?

Yes, by writing the old value back. Ask Claude Code to read the setting with get_settings before it changes anything, so the previous value is in the session. The Hub keeps no undo, so the value Claude Code read is your way back.

### Will Claude Code stop before changing a setting on every site?

The Hub tells it to confirm once before a write across every site, and Claude Code prompts for the tool call unless a permission rule allows it or you run auto mode or bypassPermissions mode. The prompt is the dependable check. If update_settings is allowed in your rules, or one of those modes is on, only the model's own habit stands between your prompt and the write.

### How does an agent know which settings exist?

It calls list_modules for the site, which returns every available module with its settings schema and status, then get_settings for the one module it wants to change. The schema says which keys exist and what values each accepts.

### What happens if the agent sends a wrong setting key?

The site refuses the whole update and writes nothing. The error names the keys it rejected and why, such as an unknown key, a value outside the allowed range, or a field fixed by a constant in wp-config.php, and it can suggest the nearest valid key.

### How do I turn page caching on or off with an agent?

Use toggle_cache with enabled set to true or false. It installs or removes the cache drop-in and the WP_CACHE constant. Setting cache_enabled through update_settings does not work. If another caching plugin already owns the drop-in, the site will not enable xSpeed and says why.

### Can one prompt change settings on all of my sites?

Yes. update_settings and toggle_cache accept site: "all", and the Hub runs the sites one after another with a one-second pause and returns a result per site. Each site checks the values against its own schema, so a site that lacks the module fails its own row while the others apply.

### Can the agent change my Cloudflare or Redis credentials?

Not by default. Writing credential fields over MCP is off unless the site owner allows it, and the site refuses the write and names the fields. Set credentials in the xSpeed dashboard. Credential values also come back masked when an agent reads settings.

## Tune cache settings with other agents

[Claude](https://xspeedcache.com/agent/claude/cache-settings/) · [Claude Cowork](https://xspeedcache.com/agent/claude-cowork/cache-settings/) · [ChatGPT](https://xspeedcache.com/agent/chatgpt/cache-settings/) · [Codex](https://xspeedcache.com/agent/codex/cache-settings/) · [Cursor](https://xspeedcache.com/agent/cursor/cache-settings/) · [GitHub Copilot in VS Code](https://xspeedcache.com/agent/github-copilot/cache-settings/) · [Windsurf](https://xspeedcache.com/agent/windsurf/cache-settings/) · [Gemini CLI](https://xspeedcache.com/agent/gemini-cli/cache-settings/) · [Antigravity](https://xspeedcache.com/agent/antigravity/cache-settings/) · [Zed](https://xspeedcache.com/agent/zed/cache-settings/) · [Kiro](https://xspeedcache.com/agent/kiro/cache-settings/) · [OpenCode](https://xspeedcache.com/agent/opencode/cache-settings/) · [OpenClaw](https://xspeedcache.com/agent/openclaw/cache-settings/) · [Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cache-settings/) · [Grok Build](https://xspeedcache.com/agent/grok-build/cache-settings/) · [ChatGPT dots](https://xspeedcache.com/agent/chatgpt-dots/cache-settings/) · [Grok](https://xspeedcache.com/agent/grok/cache-settings/) · [Grok Bot](https://xspeedcache.com/agent/grok-bot/cache-settings/) · [Muse](https://xspeedcache.com/agent/muse/cache-settings/) · [Manus](https://xspeedcache.com/agent/manus/cache-settings/) · [Kimi Code](https://xspeedcache.com/agent/kimi/cache-settings/) · [Paperclip](https://xspeedcache.com/agent/paperclip/cache-settings/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/cache-settings/)

## More with Claude Code

- [Purge the WordPress cache with Claude Code](https://xspeedcache.com/agent/claude-code/purge-cache/)
- [Find out why WordPress pages are not cached with Claude Code](https://xspeedcache.com/agent/claude-code/troubleshoot-cache/)
- [Scan a website for speed problems with Claude Code](https://xspeedcache.com/agent/claude-code/speed-scan/)
- [Run and track PageSpeed tests with Claude Code](https://xspeedcache.com/agent/claude-code/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Claude Code](https://xspeedcache.com/agent/claude-code/optimize-site/)
- [Warm the WordPress cache with Claude Code](https://xspeedcache.com/agent/claude-code/preload-cache/)
- [Set up the Redis object cache with Claude Code](https://xspeedcache.com/agent/claude-code/object-cache/)
- [Manage Cloudflare caching with Claude Code](https://xspeedcache.com/agent/claude-code/cloudflare/)
- [Manage every WordPress site at once with Claude Code](https://xspeedcache.com/agent/claude-code/fleet/)

## Documentation

- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/
- How to minify CSS and JavaScript: https://xspeedcache.com/docs/minify/
- How to add cache rules and bypasses: https://xspeedcache.com/docs/rules-and-bypass/
- Site MCP tool reference: https://xspeedcache.com/docs/mcp-tool-reference/