xSpeed Cache Site MCP tool reference

This page covers xSpeed Cache Site MCP, the server built into each xSpeed Cache install. The xSpeed Hub MCP (https://app.xspeedcache.com/xspeed/mcp) has its own catalog of 29 tools, listed in AI agents: most share a name with a tool below, but site-scoped Hub tools take a site argument and the schemas can differ.

This page explains the tools used in a performance investigation. The connected server’s current tools/list response is authoritative: available tools and arguments vary with plugin version, registered modules, license and connection scope. This is not a frozen full catalog.

Set the connection up first. See xSpeed Cache Site MCP, or xSpeed Hub MCP to reach every site through one connection.

What this does

When an AI client connects, it asks the server for a tool list. xSpeed Cache answers with the current catalog. The table below is a guide to commonly used tools. 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_score	Write	Starts an external performance audit on Free or Pro. It can spend provider quota and persist a result; a keyless Hub-backed run may be queued.	target, strategy, provider, force (optional; inspect the current schema)
run_pagespeed	Write	Starts an external audit; uses the Pro engine when applicable, otherwise the Free score workflow. It is not Pro-only.	url, strategy, provider, force (optional)
get_score_history	Read	Reads stored audit runs, including failures; does not start a new measurement.	Inspect the current schema
get_site_info / get_health	Read	Establish the installed versions, capabilities and health before choosing a change.	Inspect the current schema
optimize_site	Write	Applies its own optimization plan one setting at a time with server-side HTML checks and per-step reversion. Read its applied, reverted, skipped, next_steps and unfixable results. It cannot import a scanner report or guarantee a score.	aggressiveness, dry_run, measure_score, target_score, max_rounds on the direct plugin tool; inspect the connected schema
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, invalid or constant-locked keys cause the MCP update to be refused before anything is written.	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
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 MCP path validates the whole proposed payload first. Unknown keys, invalid values or constant-locked keys return a refusal with nothing written. Read refused_unknown, refused_invalid and refused_locked, correct the request against list_modules / get_settings, and do not describe a refusal as a successful change. Credential fields also need a separate configure grant; never paste credentials into a report or AI brief.

run_pagespeed, url and strategy. url defaults to the site home page. strategy is either mobile or desktop, and defaults to mobile. run_score uses target for the requested page. Both are write-scoped because they can spend external audit quota and store results. A queued response is not a finished score: read get_score_history until the result is recorded, and preserve its provider, device and measurement time.

optimize_site: aggressiveness and dry_run. aggressiveness is safe, standard (the default), or aggressive, and decides which settings the run may touch. dry_run previews the settings plan and remains write-gated. On the direct plugin tool, measure_score: "always" may still run an external audit even during a dry run, spending quota and storing a result. auto, never and always control measurement policy; inspect the connected tool schema because the Hub wrapper does not currently expose this argument. Aggressive settings are never applied unless you ask for them: the tool reports them as next steps with the risk of each, and the assistant is instructed to ask you first.

Verification and rollback boundaries

The optimizer’s verified: true means its PHP HTML checks passed. Those checks do not execute JavaScript. Open every returned verify_urls page in a browser, inspect the console and exercise important interactions before reporting success. If browser checks cannot be completed, say what remains unverified.

A failing step can be reverted to its saved settings. That is not a full-site snapshot, database backup, transaction rollback or a guarantee that every visual/JavaScript regression is detected. Preserve a known-good baseline and review each proposed change. target_score is a requested stopping goal, not a promised outcome; retain stopped_because, score age and stale/replayed evidence.

Carry a scan into the fix workflow

Keep the exact report link, scan ID, requested and final URLs, selected device, measurement time and all evidence. The full machine-readable report is https://xspeedcache.com/scan/r/{scanId}.md. A public signal that xSpeed or its MCP endpoint exists does not prove the assistant has authenticated access.

The anonymous Scan MCP reads public reports; it does not configure WordPress. The authenticated Hub and direct plugin catalogs are separate. In Hub, resolve the intended site/workspace, inspect allowed tools and then read permitted current configuration before asking to apply a change. optimize_site accepts neither scan_id nor a report URL and does not automatically apply a report’s findings. See Connecting to xSpeed Hub.

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 generated from the installed plugin and active registered commands. Modules may contribute tools; inspect the current catalog instead of assuming a fixed tool count.

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 get_score_history are read tools. Starting an external audit with run_score or run_pagespeed requires write scope.

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

• xSpeed Cache Site MCP
• xSpeed Hub MCP: one AI connection for every site, the recommended way to connect
• How to connect Cloudflare
• How to clean up your database
• How to warm your cache ahead of visitors
• How to generate Critical CSS