# Scan a website for speed problems with Hermes Agent

> Scanning site speed with Hermes Agent means asking the always-on agent to read xSpeed Scan history on a cron job and run a fresh graded scan only when the latest report is out of date.

Page: https://xspeedcache.com/agent/hermes-agent/speed-scan/
Last updated: October 2026

Hermes Agent stays running and has cron jobs, so it can keep an eye on a site's speed without you starting anything. The efficient pattern splits the work in two. A daily job calls get_speed_scan for each site in xSpeed Hub, which returns the scan history and the latest report summary and starts nothing, and writes one line if the grade on a device dropped. A weekly job then calls run_speed_scan with a fresh scan, so the history keeps getting a new point.

The split matters because the two calls are not equal. get_speed_scan is a read and spends nothing. run_speed_scan is classed as a write tool on the Hub, since each scan spends the shared speed-test allowance, so you want it to run on purpose and not every time the cron fires.

When you compare two reports, make sure they graded the same device and the same amount of the rubric. The headline is the desktop run, a scan that lost its Lighthouse run grades less and cannot be compared with a full one, and older reports were graded on mobile. For a competitor or prospect that is not in your Hub, the no-account Scan MCP does the same job read-only, at four scans per caller per ten minutes.

## Set up Hermes Agent once

### 1. Put your sites in xSpeed Hub

Sign in at app.xspeedcache.com with Google or email; the Hub is free and has no site cap. Then connect each WordPress site from its own dashboard: click Connect Hub in the xSpeed Cache top bar, then Connect via xSpeed Hub. Each site needs the free xSpeed Cache plugin.

### 2. Add xSpeed Hub to config.yaml

Add this entry under mcp_servers. auth: oauth tells Hermes to handle discovery, dynamic client registration, PKCE and token refresh itself. If you edit the file from inside a running session, Hermes reloads its MCP connections with a 30 second timeout, which is too short for a browser sign-in, so finish the entry and then run the login in the next step.

File: `~/.hermes/config.yaml`

```yaml
mcp_servers:
  xspeedhub:
    url: "https://app.xspeedcache.com/xspeed/mcp"
    auth: oauth
```

### 3. Sign in with hermes mcp login

Run this once. Hermes prints an authorization URL, opens your browser where it can, and waits for the callback on a local loopback port. Sign in to xSpeed Hub and approve. There is no token to paste; Hermes caches the credentials it receives under ~/.hermes/mcp-tokens. On a remote host, paste the redirect URL back into the terminal when Hermes asks, or forward the callback port over SSH.

```bash
hermes mcp login xspeedhub
hermes mcp test xspeedhub
```

### 4. Add the xSpeed Scan MCP for sites you do not run

Prompts that scan a public URL use the xSpeed Scan MCP, a separate server from the Hub. Add it to Hermes Agent the same way as the Hub above, as a second server (xspeedscan, for example) with the URL https://xspeedcache.com/scan/mcp, and leave out any sign-in setting, such as an OAuth or auth option or an Authorization header, because the Scan MCP needs no account, token or sign-in. On a plan that allows one custom connector, add whichever server the prompts you use need.

```
https://xspeedcache.com/scan/mcp
```

Full setup: https://xspeedcache.com/agent/hermes-agent/

### Before you send a prompt that changes something

Reads change nothing on your sites, though contact_support emails xSpeed support. Writes run once your connection allows them, so your client's approval prompt and a read-only connection (the token's Read-only everywhere switch, or a Viewer sign-in) are the gates that matter. A Hermes server entry has a trust setting. The default, full, adds no approval prompt for that server's tools, and the approvals setting covers dangerous shell commands, not MCP tools. Set trust: untrusted on the xspeedhub entry and Hermes asks before every call to a tool that lacks a readOnlyHint of true. The Hub does not mark its tools that way, so with untrusted every Hub call asks, reads included. To remove writes instead of prompting, set tools.include on the entry to the read tools; the filter takes globs and include wins over exclude. The Hub itself has no confirmation step.

## Prompts

- Every morning, read the xSpeed Hub scan history for each of my sites and message me only if a grade dropped.
- Every Sunday, use xSpeed Hub to run a fresh scan on shop and add the desktop and mobile grades to my running summary.
- With xSpeed Hub, compare the last two scans for blog and tell me if they are comparable before you tell me what changed.

## Example session

```
You: Use xSpeed Hub to check the speed history for shop and tell me if it is time for a new scan.
  → get_speed_scan(site: shop) [read-only]: Latest scan is 9 days old: desktop grade B, mobile grade C. 6 scans in history.
Agent: The last report is over a week old. Run a fresh one now?
You: Yes.
  → run_speed_scan(site: shop, fresh: true, strategy: both) [uses quota]: Desktop grade B, mobile grade B. Report link included.
Agent: Mobile moved from C to B and desktop held at B.
```

## How it works

1. **Check what the site already scored**: get_speed_scan without a scan id returns the site's scan history, newest first, plus a summary of the latest report. It starts nothing and spends nothing, so the Hub tells the agent to read it first when you ask what a site scored.
2. **Start a scan**: run_speed_scan runs the full scan on a site you connected to the Hub. strategy is both (the default), desktop or mobile; one device alone costs half the engine's quota. The scan takes 20 to 60 seconds. The Hub waits about 50 seconds and, if the scan is still running, hands back a scan id.
3. **Poll if it is still running**: Call get_speed_scan with scan_id. While the scan runs it returns the running status and a note to ask again in about 20 seconds. The report page is live from the start and refreshes itself.
4. **Read the result**: The summary carries the grade, the four dimension scores, what was measured and the top fixes ranked by points recoverable, each with the xSpeed feature that fixes it. The headline grade is the desktop run. The mobile run is graded alongside it, so the agent should mention both when they differ.
5. **Scan a site you do not run**: For any other public URL, the agent uses the Scan MCP at https://xspeedcache.com/scan/mcp. There is no account and no sign-in. It takes a url, returns the same graded report and a link at xspeedcache.com/scan/r/<id>, and is limited to 4 scans per caller per 10 minutes.
6. **Fix, wait, re-scan**: After a change, wait several minutes and scan again with fresh: true. Without it, the scan service reuses any report from the last 10 minutes and the agent will show you the old number.

## Reference

| | |
| --- | --- |
| Hub route | run_speed_scan, then get_speed_scan with scan_id; only for sites connected to your Hub |
| Scan MCP route | https://xspeedcache.com/scan/mcp, no account, 5 tools, read-only, any public URL |
| Scan MCP limit | 4 scans per caller per 10 minutes |
| Why run_speed_scan is a write | It spends a shared scan allowance and stores a report; it changes nothing on the site |
| Read-only Hub connection | run_speed_scan is refused; get_speed_scan still works. Applies to the connection token with Read-only everywhere on and to a Viewer sign-in; an OAuth sign-in gets the scopes the client asks for |
| Duration | 20 to 60 seconds; the Hub waits about 50 seconds, then returns a scan id |
| Poll argument | scan_id on the Hub tool, scanId on the Scan MCP tool |
| strategy | both (default), desktop or mobile; one device costs half the quota and becomes the headline |
| fresh | true forces a new measurement; otherwise a report from the last 10 minutes is reused |
| Report link | xspeedcache.com/scan/r/<id>; add .md for a Markdown twin an agent can read |
| Report visibility | Hub scans are filed unlisted; Scan MCP scans are public in the scan directory by default |

## Rules

- Read before you spend. Ask for the scan history first; start a new scan only when you want a fresh measurement or something changed.
- A report link is not private. An unlisted report is kept out of the scan directory and search, but anyone with the URL can open it. A scan started through the Scan MCP is public by default.
- run_speed_scan changes nothing on your site, but the Hub classes it a write, so a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) refuses it and your client may prompt for it. Use get_speed_scan, or the Scan MCP for a public URL, when you want a strictly read-only route.
- Compare like with like. A scan that lost its Lighthouse run is marked partial and is not comparable with a full one, and the lab grade is not the same as real-visitor Core Web Vitals, which the report shows separately.
- A scan cannot reach private, local or password-protected sites, and a site behind a bot challenge returns a report that says its server checks were not measured.

## Good to know with Hermes Agent

A cron job that calls run_speed_scan unattended spends the shared speed-test allowance each time it fires, and nothing on the Hub stops it except your connection scope and your prompt. Hermes adds no prompt of its own for a server marked trust full, which is the default. With trust set to untrusted it asks before every Hub call, get_speed_scan included, because the Hub marks no tool read-only, and a scheduled run has nobody to answer. So list only get_speed_scan under tools include for the daily job, and put a rule in the job itself, such as scan only if the latest report is older than seven days. Use a read-only Hub connection (the connection token with Read-only everywhere on) for any job that should never start a scan.

## More prompts for this job

Prompts about your own sites work in any client connected to xSpeed Hub. A prompt that scans a site you do not run, or names the scan server, needs the xSpeed Scan MCP from the setup above.

- Using xSpeed Hub, what did the shop site score on its last speed scan? Do not start a new one.
- Use xSpeed Hub to run a speed scan on blog and give me the three fixes that recover the most points, plus the report link.
- With xSpeed Hub, scan only the mobile view of shop and tell me the grade.
- I changed the theme this morning. Use xSpeed Hub to run a fresh scan on docs and compare it with the previous report.
- Use the xSpeed Scan MCP to grade [competitor URL] and tell me what its biggest weaknesses are.
- The speed scan on shop is still running. Ask xSpeed Hub to check it again and tell me when it finishes.

## Frequently asked questions

### Should a Hermes cron job run a scan every day?

Usually not. Read the history daily with get_speed_scan, which spends nothing, and start a fresh run_speed_scan weekly or after a known change. Each scan on the Hub spends the shared speed-test allowance.

### How do I know two scans in the history are comparable?

Check that both graded the same device and graded the full rubric. A scan that lost its Lighthouse run grades far less and is not comparable with a full one, and reports from before the desktop headline change were graded on mobile.

### What is the difference between run_speed_scan and run_speed_test?

run_speed_scan runs the full xSpeed Scan: server probes plus Lighthouse, a 0 to 100 grade across four dimensions, the fix for every failing check and a shareable report link. run_speed_test returns a raw PageSpeed Insights score with Core Web Vitals and no graded report.

### Can an agent scan a site that is not in my Hub?

Yes, through the xSpeed Scan MCP at https://xspeedcache.com/scan/mcp. It needs no account and no sign-in, accepts any public URL and is read-only. The Hub route only scans sites you connected to your own workspace.

### How many scans can I run?

The Scan MCP allows 4 scans per caller per 10 minutes. Scanning the same URL again within 10 minutes returns the existing report unless the agent passes fresh: true. A Hub scan spends a shared allowance of the scan service, which is why the Hub treats it as a write tool.

### Is my scan report public?

Reports started from the Hub are filed as unlisted, which keeps them out of the public scan directory and search results, but the link itself still opens for anyone who has it. Reports started through the Scan MCP are public by default.

### Which score does the scan headline show, desktop or mobile?

The headline grade is the desktop run, because it is the one you can reproduce in your own browser. The mobile run is graded on the same rubric and returned alongside it. Google ranks on mobile, so when the two differ the agent should tell you both.

## Scan a site's speed with other agents

[Claude Code](https://xspeedcache.com/agent/claude-code/speed-scan/) · [Claude](https://xspeedcache.com/agent/claude/speed-scan/) · [Claude Cowork](https://xspeedcache.com/agent/claude-cowork/speed-scan/) · [ChatGPT](https://xspeedcache.com/agent/chatgpt/speed-scan/) · [Codex](https://xspeedcache.com/agent/codex/speed-scan/) · [Cursor](https://xspeedcache.com/agent/cursor/speed-scan/) · [GitHub Copilot in VS Code](https://xspeedcache.com/agent/github-copilot/speed-scan/) · [Windsurf](https://xspeedcache.com/agent/windsurf/speed-scan/) · [Gemini CLI](https://xspeedcache.com/agent/gemini-cli/speed-scan/) · [Antigravity](https://xspeedcache.com/agent/antigravity/speed-scan/) · [Zed](https://xspeedcache.com/agent/zed/speed-scan/) · [Kiro](https://xspeedcache.com/agent/kiro/speed-scan/) · [OpenCode](https://xspeedcache.com/agent/opencode/speed-scan/) · [OpenClaw](https://xspeedcache.com/agent/openclaw/speed-scan/) · [Grok Build](https://xspeedcache.com/agent/grok-build/speed-scan/) · [ChatGPT dots](https://xspeedcache.com/agent/chatgpt-dots/speed-scan/) · [Grok](https://xspeedcache.com/agent/grok/speed-scan/) · [Grok Bot](https://xspeedcache.com/agent/grok-bot/speed-scan/) · [Muse](https://xspeedcache.com/agent/muse/speed-scan/) · [Manus](https://xspeedcache.com/agent/manus/speed-scan/) · [Kimi Code](https://xspeedcache.com/agent/kimi/speed-scan/) · [Paperclip](https://xspeedcache.com/agent/paperclip/speed-scan/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/speed-scan/)

## More with Hermes Agent

- [Purge the WordPress cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/purge-cache/)
- [Find out why WordPress pages are not cached with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/troubleshoot-cache/)
- [Run and track PageSpeed tests with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/optimize-site/)
- [Tune WordPress cache settings with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cache-settings/)
- [Warm the WordPress cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/preload-cache/)
- [Set up the Redis object cache with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/object-cache/)
- [Manage Cloudflare caching with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cloudflare/)
- [Manage every WordPress site at once with Hermes Agent](https://xspeedcache.com/agent/hermes-agent/fleet/)

## Documentation

- xSpeed Scan: free website speed test: https://xspeedcache.com/docs/speed-scan/
- xSpeed Scan MCP: speed-test any site from your AI assistant: https://xspeedcache.com/docs/scan-mcp/
- How to run a full site scan: https://xspeedcache.com/docs/scan/
- Running speed tests in xSpeed Hub: https://xspeedcache.com/docs/hub-speed-tests-and-notifications/