# Tune WordPress cache settings with Windsurf

> Tuning cache settings with Windsurf means asking its agent, from the editor, to read an xSpeed module on a WordPress site, propose a change and write it through xSpeed Hub once you approve the tool call.

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

You are in Windsurf with a theme open and a Lighthouse note that says your largest image loads late. The cause is common: lazy loading was applied to the hero image at the top of the page. You paste the note and name the site. The agent calls list_sites, then list_modules to find the lazy loading module, then get_settings for it, so it can read which kinds of media are lazy-loaded, how many top images load eagerly and which images are excluded.

What comes back is a specific edit instead of a general tip: add the hero image to the excluded images list, which holds a class or file name, and leave lazy loading on for the rest. The Hub tells the agent to briefly confirm intent before update_settings, so the agent shows the list as it is, the list as it would be, and asks. After your yes it calls update_settings and returns the stored list. If any key or value is wrong, the whole call is refused and nothing is stored, Pro-only modules are refused on a site without a licence, and credential fields are refused over the Hub.

What differs in Windsurf is that there are now two surfaces. Windsurf ships as Devin Desktop, with the Devin Local agent as its primary agent, and the older Cascade agent remains for existing conversations. Devin Local prompts before it calls any MCP tool by default, reads included, and lets you allow one tool or the whole xspeedhub server for the session or permanently. Smart mode lets a fast model run what it judges safe, and Bypass mode approves everything, so with either the Hub runs a write as soon as the connection allows it. Cascade caps the total tools across all servers at 100, and the 29 xSpeed tools take a share of that.

## Set up Windsurf 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 for the Devin Local agent

Run this in a terminal. Devin Local shares its MCP configuration with Devin CLI, and -s user saves the server to ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows) so it applies to every project. Without -s, the command saves to local scope, which is the current project only.

```bash
devin mcp add -s user xspeedhub https://app.xspeedcache.com/xspeed/mcp
```

### 3. Sign in

Run the login command and approve access on the xSpeed Hub page that opens in your browser. There is no token to paste, and the client keeps the credentials it receives. If the server later shows Needs auth in the Devin Local MCP list, click Authenticate, or run devin mcp logout and then login again.

```bash
devin mcp login xspeedhub
```

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

### 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. The Devin Local agent prompts for approval before it calls any MCP tool. In the prompt you can allow that one tool or every tool on the xspeedhub server, for this session or permanently, and permission rules such as mcp__xspeedhub__get_cache_status allow, deny or always ask for a named tool. Smart mode lets a fast model run what it judges safe without a prompt, and Bypass mode approves everything, so with either of those a write reaches the Hub as soon as your connection allows writes. xSpeed Hub has no confirmation step of its own.

## Prompts

- My hero image on shop loads late. Use xSpeed Hub to check the lazy loading settings and exempt it if that is the cause.
- Ask xSpeed Hub which images and embeds are lazy-loaded on blog and which are excluded.
- With xSpeed Hub, turn off lazy loading for background images on shop only, and tell me the setting before and after.

## Example session

```
You: Lighthouse says the hero image on shop is lazy-loaded and loads late. Using xSpeed Hub, is that xSpeed doing it?
  → get_settings(site: shop, module: lazy) [read-only]: lazy_images on, eager_first_n 1, excluded_images empty
Agent: Lazy-load images is on and only the first image on a page loads eagerly. Lighthouse shows the hero lazy-loaded, so another image comes before it and takes that slot. Adding the hero to the excluded images list exempts it without changing other images. Apply it to shop?
You: Yes, add hero-banner.jpg.
  → update_settings(site: shop, module: lazy, values: { excluded_images: hero-banner.jpg }) [changes site]: stored, 1 entry in excluded_images
Agent: Done. Purge the page cache, then run Lighthouse again, because the old cached HTML still marks the image as lazy.
```

## 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 Windsurf

Windsurf now ships as Devin Desktop, and setups differ between the Devin Local agent and the older Cascade agent, so confirm which one you are in before you follow a tutorial that names the other. Allow only the read tools, or add an ask rule for update_settings, because allowing the whole xspeedhub server, Smart mode or Bypass mode lets a write through without a prompt. Cascade has a hard cap of 100 tools across every MCP server, and if you are close to it, an xSpeed tool can go missing; disable a server you do not use and ask the agent to list its tools again.

## 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

### Is Windsurf the same as Devin Desktop for xSpeed?

Windsurf now ships as Devin Desktop. xSpeed Hub works the same through either agent, because both call the same remote MCP server. What differs is how each agent adds the server. Devin Local prompts before any MCP tool call by default, and in the prompt you can allow one tool or the whole server.

### What if Windsurf cannot see the update_settings tool?

Check whether you are over the tool cap, which is 100 across all servers in Cascade. Turn off servers you do not use, refresh the tool list and ask again. If the tool is listed but refuses, check whether the connection is read-only, meaning the connection token with Read-only everywhere on or a Viewer sign-in, because a read-only connection refuses every 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 Code](https://xspeedcache.com/agent/claude-code/cache-settings/) · [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/) · [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 Windsurf

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