Inspect and clear POM Cache

The smallest tool group, and the one you will use most often — because almost every other workflow in this chapter ends with "purge the cache".

Requirements

• POM Cache active, or the tools are not registered.
• mcp:read to read the status; mcp:write to clear.

Note what is not required: there is no dedicated cache write gate. Clearing the cache is governed by the mcp:write scope alone. That is proportionate — purging a cache destroys derived files, not content — but it does mean a token with write scope can clear the cache even when every content gate is closed.

The two tools

Check the status first

Show me the current cache status.

pom_cache_get_status reports whether POM Cache is available and what the cache currently holds. It is read-only and free to call.

Useful beyond curiosity: a cache that is empty when you expected it full, or full when you expected it empty, tells you something about the site before you start changing content.

Clearing

Clear the site cache.

pom_cache_clear_site_cache deletes the current site's HTML cache. It also clears the progressive JSON cache by default; pass include_json as false to keep it.

The tool is marked destructive, and it supports dry_run:

Use a dry run and show me what would be deleted.

On a large site that is worth doing once, so you know the scale of what a purge rebuilds.

When to clear

After any change that alters what a visitor sees:

• publishing or updating a post or page;
• taxonomy changes, which affect archive pages;
• menu changes, which appear on every page;
• theme settings, CSS or template changes;
• product, price or coupon changes;
• option changes such as the site title or posts per page.

The pattern is: make the change, verify the stored record, then purge, then look at the rendered page. Verifying before purging tells you the data is right; looking after purging tells you the site is right.

It clears one site

The tool clears the current site's cache. On multisite, each site is a separate MCP server with its own cache, so clearing one does nothing for the others.

If a change affected several sites of a network, purge on each.

What it does not do

• It does not invalidate a CDN. Origin cache and edge cache are different copies. After purging the origin, purge the CDN separately or the edge keeps serving the old page.
• It does not disable caching. The cache rebuilds on the next request.
• It does not clear other caches — object caches, plugin caches, browser caches.

The CDN point is the one that catches people. A correct change, a purged origin and a stale edge looks exactly like a failed change.

Clearing is cheap; a full purge is not free

Deleting the cache means every subsequent visitor triggers a fresh page generation until it refills. On a busy site, purging everything during peak traffic produces a load spike.

For a change affecting a single page, consider whether a full purge is warranted at all, or whether the page will refresh on its own schedule.

Common problems

Related

• Cache tools
• The POM Cache documentation for the caching model itself