Test cache behavior with the MCP server
Ask a coding agent connected to the Azion MCP server to test the cache of a deployed site, then check the debug headers Azion returns with curl.
You can test the cache of a site deployed on Azion by asking a coding agent connected to the docs server of the Azion MCP servers to run the server’s cache test. You then confirm what the agent reports by reading the debug headers of a response with curl. To check one response without an agent, refer to Check the cache status of a response.
Prerequisites
- A site deployed on Azion, and its URL. Azion assigns each workload a domain in the format
xxxxxxxxx.map.azionedge.net. - A coding agent connected to the docs server,
https://docs-mcp.azion.com/mcp. To connect one, refer to MCP server quickstart. curlon your machine.
Run the cache test with your agent
The docs server carries the cache test as three guides, the resources under azion://guides/test-cache/. The agent follows them in order, and the report of each step is the input of the next. To run the test:
Give the agent the URL of the deployed site, and ask it to test the cache with the Azion docs MCP server. A client that supports MCP resources reads the three resources. A client without resource support calls the deploy_azion_static_site tool with action set to test-cache, which returns the same three steps.
In test-cache/step-0-preparation, the agent analyzes the cache configuration of the deployed site and prepares the test scenarios. It takes the site URL and writes a test preparation report.
In test-cache/step-1-execution, the agent runs cache tests for each static asset type, such as HTML pages, CSS files, and JavaScript files. The report gives the hit-miss ratio of each type.
In test-cache/step-2-validation, the agent validates the results, calculates the rate of cache hits, and writes the test report. The report counts the total, passed, and failed tests.
The agent ends with the validation report. When a report names a response header, compare it with the headers in Read the debug headers, which lists the names Azion returns. If the agent finds neither the resources nor the tool, refer to Troubleshoot the MCP server.
Check the debug headers with curl
The request header Pragma: azion-debug-cache makes Azion add its cache headers to the response. Start with the workload domain under map.azionedge.net, then repeat the request on your own domain. To request the headers of a page, replace the URL with yours:
The response below is cut to its cache headers. The page it requests is not cached, so every header except x-cache-config, x-cache-id, and x-cache-location carries -:
A - in x-cache means no status: the content is restricted from caching. For every status value, such as HIT and MISS, refer to Cache keys. Without Pragma: azion-debug-cache, the response carries none of these headers; of the Azion headers, only x-azion-request-id and x-azion-edge-location remain.
Run the same request twice to see whether the second response comes from the cache. Consecutive requests can reach different servers, and x-cache names the server that answered each one. Then repeat the request for a static asset, with a query string, or with a Cookie header, and compare x-cache-key. The key shows which query parameters and cookies vary the cache.
Read the debug headers
A response to a request with Pragma: azion-debug-cache carries ten cache headers. Under HTTP/2, the header names arrive in lowercase.
| Header | What it carries |
|---|---|
x-cache | The cache status, the IP address of the server that answered the request, and the protocol |
x-cache-key | The cache key the copy is stored under, which is the argument a cache key purge takes |
x-cache-file | The MD5 hash of the cache key |
x-cache-since | The Unix timestamp of when the copy was stored |
x-cache-expire | The Unix timestamp of when the copy expires |
x-cache-expires-in | The seconds left until the copy expires |
x-cache-valid | The TTL configured for the copy, in seconds |
x-cache-config | The ID of the Azion configuration that served the request |
x-cache-id | An identifier of the request, different on each response |
x-cache-location | Returned with the other debug headers |
When a copy stays stale, x-cache-valid and x-cache-expire show its TTL and when it expires. The TTL comes from the cache setting that applies to the request; for its fields, refer to Cache settings. To remove the copy before then, refer to Purge cached content. To follow cache behavior across many requests instead of one response, refer to Azion CLI logs.