xSpeed Cache MCP Tool Reference

This page lists every tool the xSpeed Cache MCP server exposes to a connected AI agent. Each tool has a name, a purpose, and a note on whether it changes anything on your site.

Set the connection up first. See Connecting AI Agents with the MCP Server.

What this does

When an AI client connects, it asks the server for a tool list. xSpeed Cache answers with the catalog below. The agent then calls a tool by name with the arguments that tool accepts.

Tools are split into two kinds:

• Read tools only look at your site. They are safe to run at any time.
• Write tools change something: they purge, toggle, clean, or save settings.

A read-only connection can call read tools only. If it tries a write tool, the call is refused with a message saying the connection is read-only.

Tool list

Tool	Type	What it does	Arguments
get_cache_status	Read	Cache status for the site: whether caching is on, cache stats (cached pages, size, hit ratio, last purge), and the detected web server.	None
list_modules	Read	Lists all xSpeed Cache modules (free and Pro) with their settings schema and status.	None
get_settings	Read	Reads the settings for one module. Returns schema-validated values.	module (required)
run_benchmark	Read	Runs a before/after cache benchmark on the home page and returns the timings.	None
get_pro_audit	Read	A list of Pro features that would benefit this site, based on its current settings and cache stats.	None
list_commands	Read	Lists every xSpeed Cache command that run_command can invoke, with name, description, module, and options.	None
scan_database	Read	Scans the database for bloat (post revisions, auto-drafts, trashed posts, spam comments, expired transients, orphaned meta). Deletes nothing.	None
run_pagespeed	Read	Runs a Google PageSpeed Insights audit and returns the performance score and Core Web Vitals. Pro.	url, strategy (both optional)
purge_cache	Write	Purges the site cache.	type (optional)
toggle_cache	Write	Turns page caching on or off. Installs or removes the cache drop-in and the WP_CACHE constant as needed.	enabled (required)
update_settings	Write	Updates settings for one module. Unknown keys are stripped and invalid values are rejected by the module schema.	module, values (both required)
purge_cloudflare	Write	Purges the Cloudflare edge cache for this site.	None
clean_database	Write	Cleans database bloat. Removes the categories currently enabled in the Database module settings.	None
flush_object_cache	Write	Flushes the persistent object cache (Redis or Memcached), if enabled.	None
start_preloader	Write	Starts the cache preloader, which crawls the sitemap to warm the page cache in the background.	None
generate_critical_css	Write	Generates above-the-fold Critical CSS for the site and stores the result. Pro.	None
run_command	Write	Runs any registered xSpeed Cache command. See the CLI bridge section below.	command (required), args, options

Note: run_command is always treated as a write tool, even when the command it runs only reads. It is a gateway to the full command surface, so a read-only connection cannot use it at all.

Tools that are not always present

Some tools only appear in the list when the command behind them is registered on your site. If the underlying module is not active, xSpeed Cache removes the tool from the catalog rather than offering one that would always fail.

Tool	Needs the command
purge_cloudflare	xspeed cf
scan_database	xspeed db
clean_database	xspeed db
flush_object_cache	xspeed objcache
start_preloader	xspeed preloader
run_pagespeed	xspeed psi (Pro)
generate_critical_css	xspeed ccss (Pro)

If a tool is missing from what your agent sees, that is why. The action may still be reachable through run_command when the command itself exists.

Arguments explained

purge_cache — type. Chooses what to purge. Accepted values are all, page, assets, object, and rest. Defaults to all. Any other value is rejected. The result reports what was purged, a count, and the updated stats.

toggle_cache — enabled. A boolean. true turns page caching on, false turns it off. This is required; there is no default.

get_settings / update_settings — module. The module slug, for example minify or gzip. Call list_modules first if you are not sure of a slug.

update_settings — values. An object mapping setting keys to new values. The module schema validates it, so unknown keys are dropped and bad values are rejected.

run_pagespeed — url and strategy. url defaults to the site home page. strategy is either mobile or desktop, and defaults to mobile.

Warning: clean_database deletes data. It removes whatever categories are enabled in the Database module settings. Run scan_database first to see what would be removed.

The CLI bridge: list_commands and run_command

xSpeed Cache has a large WP-CLI command set. Rather than write a separate MCP tool for every one, the MCP server includes a bridge that can run any registered xSpeed Cache command from an MCP call.

Two tools drive it:

1. list_commands returns the full catalog. Each entry has the command name, a short description, which module it belongs to, and its options. This is how the agent discovers what it can run.
2. run_command runs one of them.

run_command takes three arguments:

• command — the command name, for example cloudflare purge or database scan. The leading xspeed prefix is optional.
• args — an array of positional arguments, if the command takes any.
• options — an object of named options or flags, for example { "url": "https://site.com", "strategy": "mobile" }.

The bridge resolves the command name against the registered list. If a registered command is a prefix of what you passed, the trailing words become positional arguments. For example, xspeed db scan resolves to the command xspeed db with scan as the first argument.

The result comes back as a structured object with the resolved command name, an ok flag, the captured output as text, and the output split into lines. If the command reported a failure, an error message is included and ok is false.

Note: Because the bridge calls the exact same command callbacks that WP-CLI uses, the MCP surface can never fall behind the CLI. A new command is reachable from both at once.

Why the dedicated tools exist too. Several common actions have their own named tool (purge_cloudflare, scan_database, clean_database, flush_object_cache, start_preloader, run_pagespeed, generate_critical_css). These are thin wrappers over the same bridge. They exist so an agent can call the action directly, with typed arguments, instead of having to discover a command name first.

How results come back

Every tool returns its result as JSON text. If a tool fails, the failure is reported back to the agent as readable text rather than being swallowed by the transport, so the assistant can tell you what went wrong and why.

Common failure messages you may see relayed by your agent:

• Unknown tool. The tool name does not exist in the catalog.
• This MCP connection is read-only. The tool changes state and the connection does not allow that.
• Unknown command. run_command was given a name that is not registered. Call list_commands to see valid names.
• Invalid purge type. purge_cache was given a type outside the accepted list.
• The “module” parameter is required. A settings tool was called without a module slug.

Security notes

• Write tools are refused on a read-only connection. This is checked on the server, not in the client, so it holds no matter what the agent tries.
• run_command counts as a write tool in every case. If you want an agent that can only look, a read-only connection blocks the whole command surface.
• Access level applies to both connection types. A read-only pairing token and a read-scoped OAuth grant behave the same way.
• If you want to narrow what an agent can do, change the connection’s access level in the dashboard. There is no per-tool permission setting.

FAQ

How do I see exactly which tools my site exposes? Ask your agent to list the server’s tools, or open the MCP Server panel in the dashboard. The panel shows the same catalog the agent sees, including which tools write.

Can I add my own tools? The catalog is fixed in the plugin. However, any xSpeed Cache command registered by a module is automatically reachable through run_command.

Does an agent need write access to check my cache? No. get_cache_status, list_modules, get_settings, run_benchmark, get_pro_audit, scan_database, list_commands, and run_pagespeed are all read tools.

Why can’t the agent run run_command on my read-only connection even for a read command? The bridge can reach every command, including destructive ones, so it is blocked as a whole. Use the dedicated read tools instead.

Related

• Connecting AI Agents with the MCP Server
• Cloudflare Integration
• Cleaning and Optimizing Your Database
• Configuring the Cache Preloader
• Generating Critical CSS