---
name: azion-test-cache-behavior-with-the-mcp-server
description: >-
  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.
---

# Test cache behavior with the MCP server

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](/en/documentation/devtools/mcp/) 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](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time/).

---

## 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](/en/documentation/devtools/mcp/quickstart/).
- `curl` on 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:

1. **Ask your agent to test the cache of the site**

   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.

2. **Review the preparation report**

   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.

3. **Review the test execution 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.

4. **Review the validation report**

   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](#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](/en/documentation/devtools/mcp/troubleshooting/).

---

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

```bash
curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/
```

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 `-`:

```text
cache-control: max-age=0, no-cache, no-store
x-cache: - from 192.0.2.10 with HTTP/2.0
x-cache-key: -
x-cache-file: -
x-cache-since: -
x-cache-expire: -
x-cache-expires-in: -
x-cache-valid: -
x-cache-config: 1234567890123u
x-cache-id: 0123456789abcdef0123456789abcdef
x-cache-location: /
```

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](/en/documentation/platform/applications/cache/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](/en/documentation/platform/applications/cache/cache-settings/). To remove the copy before then, refer to [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content/). To follow cache behavior across many requests instead of one response, refer to [Azion CLI logs](/en/documentation/devtools/cli/logs/).

---

## Next steps

- [Cache keys](/en/documentation/platform/applications/cache/cache-keys.md): The key format, the variations a key can carry, and every cache status value.
- [Create a cache setting](/en/documentation/guides/application-performance/cache-and-purge/tune-cache-settings.md): Set the TTL and variations, and the rule that applies the setting to requests.
- [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content.md): Remove a stored copy by URL, wildcard, or cache key before its TTL ends.
- [Troubleshoot Applications](/en/documentation/platform/applications/troubleshooting.md#cache): What to check when responses stay MISS or report a dash on every request.