# Find out why WordPress pages are not cached with Cursor

> Finding out why pages are not cached with Cursor means asking its agent, from the editor where you work on the theme, to read xSpeed health checks and a benchmark through xSpeed Hub and say what holds the cache back.

Page: https://xspeedcache.com/agent/cursor/troubleshoot-cache/
Last updated: October 2026

You are in the theme folder in Cursor, and the site is slower than a cache should allow. A cached request is quick but not instant, so you want to know which path serves it. You ask the agent in chat: are the pages on shop really cached, and what serves them?

Cursor shows each xSpeed call as it runs. get_health reports the static-file rewrite, which is what lets nginx or Apache hand out a cached file without starting PHP. If nginx is detected but not yet routing to the cache, hits still work, only through PHP, and the benchmark shows a hit that costs more than it should. The agent says so and points at the server snippet in xSpeed's Health panel, which is a server edit you make outside the editor. It can then call get_pro_audit, a read that lists the Pro features that would suit the site's settings and stats.

Whether Cursor asks before it runs an MCP tool depends on the Run Mode, under Settings, Agents, Approvals and Execution. Since Cursor 3.6 the recommended default is Auto-review, which sends calls that are not on the allowlist to a classifier, not to you. Allowlist mode runs only what you listed and asks about the rest, and Run Everything asks nothing. You can expand a call to see its arguments. Diagnosis calls only read, so listing them is reasonable. To be asked about anything else, switch to Allowlist mode. That choice is Cursor's and changes nothing about what the Hub does. You can keep working while it checks. Cursor runs the calls in the chat panel, so you can leave the theme file you were editing open and come back to a short answer: what serves the pages, what the benchmark measured, and whether anything is worth acting on. Ask for the verdict in three lines if that is all you want.

## Set up Cursor 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 mcp.json

Add the server to ~/.cursor/mcp.json to have it in every project, or to .cursor/mcp.json inside a project to scope it there. The entry is just a name and a url.

File: `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "xspeedhub": {
      "url": "https://app.xspeedcache.com/xspeed/mcp"
    }
  }
}
```

### 3. Enable it and sign in

Open Customize in the sidebar, find xspeedhub and make sure it is switched on. When Cursor starts the OAuth sign-in, approve access on the xSpeed Hub page. There is no token to paste. If the server shows an error, open the Output panel with Cmd+Shift+U and pick MCP Logs.

```
Customize  >  xspeedhub  (on)
```

Full setup: https://xspeedcache.com/agent/cursor/

### 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. Cursor decides how to treat an MCP tool call by its Run Mode, and you can expand a call to see its arguments. MCP follows the same Run Modes as terminal commands, set under Settings > Agents > Approvals & Execution. The recommended default, Auto-review, runs allowlisted calls at once and sends the rest to a classifier, not to you. Allowlist runs only what you listed, and with an empty list it asks you every time. Run Everything runs every tool call without asking. xSpeed Hub has no confirmation step of its own, so a tool you allowlist, or any call under Run Everything, writes as soon as your connection allows writes. Auto-review is a model, and Cursor says it is not a security boundary.

## Prompts

- Using xSpeed Hub, which path serves cached pages on shop: nginx, Apache or PHP? Check the health report and run the benchmark.
- My cached pages take around 90 ms. Ask xSpeed Hub whether the server rewrite is active on shop.
- With xSpeed Hub, run the Pro audit on shop and list what it suggests, without changing anything.

## Example session

```
You: Shop pages are cached but not as fast as I expected. Use xSpeed Hub to find out what serves them.
  → get_health(site: shop) [read-only]: nginx detected but not yet routing to the cache; other checks pass
  → run_benchmark(site: shop) [read-only]: home page: 560 ms uncached, 92 ms cached, cached request was a hit
Agent: Caching works, but nginx still starts PHP for every hit. Adding xSpeed's nginx snippet to the server block removes that step. That is a server edit, and the Hub cannot make it. Want to see which Pro features suit this site?
You: Yes.
  → get_pro_audit(site: shop) [read-only]: 2 suggestions: critical CSS for render-blocking stylesheets, scheduled prewarming
Agent: Those are suggestions only. Nothing on shop was changed.
```

## How it works

1. **Start with the quick summary**: get_cache_status returns whether page caching is on, the stats (cached pages, size, hit ratio, last purge) and the web server xSpeed detected. It is a glance. If caching is off, or the hit ratio is far below what you expect, the agent moves on to the diagnostic.
2. **Run the diagnostic**: get_health is the tool for troubleshooting. It returns the environment checks with pass or warn tones (the advanced-cache.php drop-in, the WP_CACHE constant, rewrite rules, PHP and WordPress versions, caching plugin conflicts), the cache stats, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use it, not get_cache_status, when you are troubleshooting rather than glancing.
3. **Time cached against uncached**: run_benchmark requests the home page once with the cache bypassed and once normally, after a warm-up request, and returns the timings. If the second request still is not a cache hit, the page cache is not serving the home page, and the result says so. It measures xSpeed's own response time. It does not return a Lighthouse score.
4. **Read what the checks mean**: A warn is a lead, not always a fault. A static-file rewrite warning, for example, can mean the nginx snippet is not in your server config yet, or that xSpeed could not verify it, which is not evidence the config is wrong. The agent reads the detail line and tells you which one it is.
5. **Fix it or hand it over**: If caching is simply off, toggle_cache turns it on. If another caching plugin owns the drop-in, the site refuses to enable xSpeed and says why; removing the other plugin is yours to do. If nothing explains it, contact_support emails xSpeed support with the agent's summary, after the agent has confirmed the message with you.

## Reference

| | |
| --- | --- |
| Quick check | get_cache_status (read): cache on or off, stats, detected web server |
| Diagnostic | get_health (read): environment checks, 24 hourly buckets, 30-day hit-ratio series, recent activity |
| One site per call | get_health does not accept site: "all"; call it for each site you care about |
| Benchmark | run_benchmark (read): home page only, cache bypassed against cache served, timings in milliseconds |
| Benchmark on every site | run_benchmark accepts site: "all" or a list of handles, one result per site |
| Benchmark history | get_benchmark_history reads past runs and the settings changes on the same timeline |
| Pro suggestions | get_pro_audit (read): which Pro features would help this site, from its settings and stats |
| Hit ratio scope | Counts requests that reach your server; pages answered by a CDN or Cloudflare edge are not counted |
| Support | contact_support emails xSpeed support with your account email and site list attached; classed read |
| Turning caching on | toggle_cache (write); refused by the site when another plugin owns the cache drop-in |

## Rules

- Diagnose with the read tools first. get_cache_status, get_health, run_benchmark and get_pro_audit change nothing on the site, so a read-only connection can run all of them. For clients that send the connection token, that means Read-only everywhere on; an OAuth sign-in gets the scopes the client asks for, unless the member is a Viewer.
- Do not answer a PageSpeed question with run_benchmark. It measures cached against uncached response time and returns no Lighthouse score; for a score, use the speed test or scan jobs.
- toggle_cache is a write. It runs as soon as your connection allows writes, and the Hub tells the agent to confirm the target site first. That is guidance to the agent, so your client's approval prompt is the gate that matters.
- contact_support sends a real email. The Hub tells the agent to confirm the message with you before sending, but the tool is classed read, so even a read-only connection can send one.
- The agent cannot edit your server configuration or another plugin's settings. When a check needs an nginx snippet or a conflicting plugin removed, it tells you what to do and you do it.

## Good to know with Cursor

If contact_support is on your allowlist, or you use Run Everything, it sends an email to xSpeed support with no Cursor prompt in between. The Hub only tells the agent to confirm the message with you. That is an instruction to the model, not a lock, and Cursor says Auto-review is a classifier and not a security boundary, so switch Run Mode to Allowlist, list the read tools, and leave contact_support off so it asks. get_pro_audit is a list of ideas for the site, not a fix, and acting on one means a change you ask for separately.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Using xSpeed Hub, why is the cache hit ratio so low on shop? Run the full health check and tell me the most likely cause.
- Using xSpeed Hub, is page caching actually working on blog? Benchmark cached against uncached and tell me if the second request was a hit.
- xSpeed Hub's get_health on docs shows a warning about the static-file rewrite. What does it mean and do I need to act?
- Use xSpeed Hub to check whether another caching plugin is conflicting with xSpeed on shop.
- Caching looks off on the staging site. Use xSpeed Hub to turn it on and tell me if the site refuses.
- Using xSpeed Hub, which Pro features would help the shop site, based on how it is set up now?
- With xSpeed Hub, compare the last few benchmark runs on blog and tell me whether my settings changes helped.

## Frequently asked questions

### Can Cursor tell me why my WordPress cache is slower than it should be?

Yes. It reads the health checks and a benchmark through xSpeed Hub, and can say whether hits are served as static files by nginx or Apache, or through PHP. The server snippet that changes this is a server edit, so Cursor describes it and you apply it.

### Will Cursor ask before it calls the xSpeed tools?

It depends on your Run Mode. Under the default Auto-review, allowlisted tools run at once and a classifier, not you, decides the rest. In Allowlist mode (Settings, Agents, Approvals and Execution) Cursor asks about anything not listed, and Run Everything asks nothing. The Hub itself has no confirmation step, so for tools that change the site, Cursor's prompt is the check.

### Why are my WordPress pages not being cached?

The common causes are that page caching is switched off, the advanced-cache.php drop-in or the WP_CACHE constant in wp-config.php is missing, another caching plugin owns the drop-in, or the pages set cookies or headers that make them uncacheable. An agent can read all of these from get_health through xSpeed Hub and tell you which one applies to your site.

### What is the difference between get_cache_status and get_health?

get_cache_status is a quick summary: whether caching is on, the stats and the detected web server. get_health is the diagnostic. It adds the environment checks with pass or warn tones, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use get_health when you are troubleshooting.

### Does run_benchmark give me a PageSpeed score?

No. run_benchmark measures how fast your own cache answers compared with an uncached request for the home page. For a Lighthouse score, ask for a speed test or a speed scan instead.

### Can the agent check every site at once?

Only partly. run_benchmark accepts every site in one call. get_cache_status and get_health take one site per call, and get_health does not accept site: "all", so for a fleet the agent calls them site by site or you use the Hub dashboard for the rollup.

### Will troubleshooting change anything on my site?

Not with the diagnostic tools. They are read tools and change nothing. Changes only happen if the agent calls a write tool such as toggle_cache, which runs once your connection allows writes, so your AI 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.

## Find out why pages are not cached with other agents

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

## More with Cursor

- [Purge the WordPress cache with Cursor](https://xspeedcache.com/agent/cursor/purge-cache/)
- [Scan a website for speed problems with Cursor](https://xspeedcache.com/agent/cursor/speed-scan/)
- [Run and track PageSpeed tests with Cursor](https://xspeedcache.com/agent/cursor/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Cursor](https://xspeedcache.com/agent/cursor/optimize-site/)
- [Tune WordPress cache settings with Cursor](https://xspeedcache.com/agent/cursor/cache-settings/)
- [Warm the WordPress cache with Cursor](https://xspeedcache.com/agent/cursor/preload-cache/)
- [Set up the Redis object cache with Cursor](https://xspeedcache.com/agent/cursor/object-cache/)
- [Manage Cloudflare caching with Cursor](https://xspeedcache.com/agent/cursor/cloudflare/)
- [Manage every WordPress site at once with Cursor](https://xspeedcache.com/agent/cursor/fleet/)

## Documentation

- How to read your cache diagnostics: https://xspeedcache.com/docs/cache-diagnostics/
- Understanding cache hits and misses: https://xspeedcache.com/docs/hits-and-misses/
- How to check your site health: https://xspeedcache.com/docs/health/
- Common problems and troubleshooting: https://xspeedcache.com/docs/common-problems-and-troubleshooting/
- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/