# HeaderGuard

> Free website security-headers scanner for developers and site owners: HTTPS redirect, HSTS, Content-Security-Policy, X-Frame-Options / frame-ancestors, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP/CORP/COEP, cookie flags and version leaks. Returns a 0–100 score, an A+–F grade, per-header findings and copy-paste fixes. Public JSON API plus a remote MCP server for AI agents.

HeaderGuard only sends ordinary GET requests to the site you name (following up to 10 redirects, each safety-checked) and reads response headers, never page bodies. Only public http(s) hosts on ports 80, 443, 8080 and 8443 can be scanned. If the site blocks or challenges the scanner, no grade is given. Results are kept in memory for 2 minutes; scanned URLs are not stored.

## For AI agents

- [MCP server](https://headerguard.mike-tusa.workers.dev/mcp): remote MCP over Streamable HTTP at `https://headerguard.mike-tusa.workers.dev/mcp` (POST only, stateless, JSON responses, no sessions). Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 (2026-07-28 per-request `_meta`; older versions use `initialize`). One tool: `scan_headers` with `url` (required) and `include_raw` (optional). Read-only. Client config (most MCP clients accept this; some use a different format, for example VS Code uses a `servers` key): `{"mcpServers":{"headerguard":{"type":"http","url":"https://headerguard.mike-tusa.workers.dev/mcp"}}}`
- [OpenAPI 3.1 spec](https://headerguard.mike-tusa.workers.dev/openapi.json): machine-readable description of the JSON API
- [MCP server card](https://headerguard.mike-tusa.workers.dev/.well-known/mcp/server-card.json): static description of the MCP server and its tool
- [API docs](https://headerguard.mike-tusa.workers.dev/docs): human-readable API reference, scoring table and examples

## JSON API

- `GET https://headerguard.mike-tusa.workers.dev/api/scan?url=example.com` (`domain=` is an alias): full scan as JSON (`score`, `grade`, `gradeWithheld`, `reliability`, `findings[]` each with `id`, `status`, `points`, `max`, `notes`, plus `fixes`, `redirects`, `httpCheck`, `headers`, `plan`). CORS enabled.
- `POST https://headerguard.mike-tusa.workers.dev/api/scan/batch` with `{ "urls": [...] }` (HeaderGuard Pro only, at most 5 URLs): `{ "plan": "pro", "count", "results": [...] }`
- `GET https://headerguard.mike-tusa.workers.dev/badge/<host>.svg`: embeddable grade badge (SVG, always HTTP 200; graded badges cached about 24 hours, errors about 1 hour)
- `GET https://headerguard.mike-tusa.workers.dev/api/health`: `{ "ok": true, "service": "headerguard", "version": "0.4.0", ... }`
- Errors: `{ "error": { "code", "message", "plan" } }` with HTTP 400 `invalid_url`/`invalid_scheme`, 401 `license_invalid`/`pro_required`, 403 `blocked_target`/`blocked_port`/`license_expired`/`license_revoked`/`license_inactive`/`license_wrong_product`, 422 `dns_not_found`, 429 `rate_limited` (see `Retry-After`), 502 `fetch_failed`/`dns_error`/`too_many_redirects`/`redirect_loop`/`bad_redirect`/`budget_exceeded`, 504 `timeout`.

## Limits, keys and pricing

- No key: about 30 scans per minute per IP (IPv6 counted per /64). Uncached badges: about 30 per minute per IP.
- HeaderGuard Pro, $9/mo via Polar: about 120 scans per minute per license, plus batch scans of up to 5 URLs. Send `Authorization: Bearer HDRG-…` or `X-License-Key: HDRG-…`. [Get Pro](https://buy.polar.sh/polar_cl_isRRVJTATDI60ftjw6GnmlDneRdw46fI2cQcm0n6pnD)
- The MCP endpoint uses the same keys and the same counters: each `tools/call` is one scan. `initialize`, `tools/list` and other non-scan messages don't count as scans, but have a light cap of about 120 per minute per IP (over it: HTTP 429 with `Retry-After`). Over a limit, the tool result has `isError: true` with the reason and `retryAfterSeconds`. A key that is not a valid HeaderGuard Pro license returns HTTP 401 (or 403 when expired, revoked or for another product). Results are cached for 2 minutes and cache hits don't count.
- MCP request caps: 65,536-byte body, JSON-RPC batches (legacy versions only) of at most 10 messages with at most one `tools/call`.

## Optional

- [Homepage and scanner](https://headerguard.mike-tusa.workers.dev/)
- [HeaderGuard Pro](https://headerguard.mike-tusa.workers.dev/docs#pro)
- [Badge docs](https://headerguard.mike-tusa.workers.dev/docs#badge)
- [Privacy](https://headerguard.mike-tusa.workers.dev/#privacy)
- Contact: digitalpromohub.support@gmail.com