# mcp-headers

**An [MCP](https://modelcontextprotocol.io) server that lets Claude scan a website's HTTP security headers and grade them A–F.**

Add it to Claude Desktop or Claude Code, then just ask:

> "How are example.com's security headers?"

Claude calls the `scan_security_headers` tool, which fetches the site server-side, checks it against the OWASP secure-headers set, and hands back a grade plus the exact header to add for anything that's missing — so the model isn't guessing.

```
Security-header grade for https://example.com/: D (64/100)

❌ Content-Security-Policy — No CSP; nothing constrains where scripts load from.
    fix: Content-Security-Policy: default-src 'self'; object-src 'none'; base-uri 'self'
✅ Strict-Transport-Security — HSTS enforced (730 days).
❌ X-Frame-Options — Missing; page can be framed for clickjacking.
    fix: X-Frame-Options: SAMEORIGIN
...
```

## Why

Language models are confidently wrong about live sites — they'll "remember" a CSP that isn't there. This server makes that one thing checkable: it reads the *actual* response and grades it deterministically, so Claude can give a real answer instead of a plausible one. It's a small, focused example of the pattern I like — give the model a narrow, reliable tool instead of asking it to know everything.

## The tool

| Tool | Input | Returns |
|---|---|---|
| `scan_security_headers` | `url` (string) | An A–F grade, per-header pass/warn/fail, and a copy-paste fix for each gap |

It grades seven headers (CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy), penalises stack-disclosing headers (`X-Powered-By`, versioned `Server`), follows redirects, and times out after 10 seconds.

## Install

```bash
npm install
npm run build
```

Then point your MCP client at the built server.

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "headers": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-headers/dist/index.js"]
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add headers node /absolute/path/to/mcp-headers/dist/index.js
```

Restart the client and ask it to scan a site.

## How it's built

- **TypeScript**, ESM, no framework — just the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) and `zod` for the tool schema.
- One tool, one file (`src/index.ts`). The grading logic is a pure function so it's easy to read and extend.
- Talks stdio, so it runs anywhere an MCP client can spawn a process.

## License

MIT © Sa'ood Williams