PageLens MCP: your AI assistant, plugged into your audits

title: "PageLens MCP: your AI assistant, plugged into your audits" description: "We just shipped a Model Context Protocol server. Connect Claude Desktop, Cursor, or Codex to your PageLens scans and ask 'what should I fix this week?' from inside your editor. OAuth 2.1, read-only, free." date: "2026-04-16" author: "Richard Moore" category: "Product" readingTime: "5 min read"

If you've been following the dogfood loop posts (here for the back-story), you'll know the workflow we keep landing back on is: run a PageLens scan, download the Markdown export, paste it into Claude or Cursor, and ask the assistant which fix to ship first.

It works. It's also a little silly that the "paste it in" step exists at all.

So today we're shipping the PageLens MCP server: a Model Context Protocol endpoint that any MCP-compatible AI assistant — Claude Desktop, Cursor, Codex CLI, you name it — can connect to and read your scans directly.

What you can do with it

After a 30-second connect flow (one OAuth consent click), your assistant gets six read-only tools and two pinnable resources per scan:

list_scans — browse the most recent scans on your account, filtered by status, domain, or date.
get_scan — pull a single scan's headline data: score, grade, exec summary, top-5 findings, persona reviews.
list_findings — paged, filterable read of every finding for a scan (severity, persona, page URL, rule ID, …).
get_quick_wins — top-N quick-win findings, pre-ranked by the same Impact × Effort scorer the report's Quick Wins panel uses.
list_domains — the domains you've verified ownership of, with badge tier and current-scan anchor.
whoami — confirm whose account this connection is operating against. Useful in agent transcripts.

Plus two resources you can pin into context:

pagelensai://scan/{id}/markdown — the same agent-friendly Markdown export the report's "Download as .md" button produces.
pagelensai://scan/{id}/summary.json — a slim JSON dump: score, grade, severity counts, top findings.

The shape we've found genuinely useful in our own day-to-day: pin a scan's Markdown into your Claude project, then ask things like "given this audit, what's the smallest change I could ship this afternoon that would move the score the most?" The assistant has the full ranked finding list, the evidence, and the suggested fixes — it doesn't have to guess.

Why MCP, not a REST API?

A REST API would have been faster to ship. The reason we went with MCP first is that the workflow we actually want isn't "developer writes a Node script that hits our API." It's "PM-shaped person opens Claude, asks a question about their site, and the assistant just knows the answer."

MCP is the protocol that makes that work without a single line of glue code on the customer's side. The tool list is discovered automatically; the auth flow runs in a browser tab; the assistant figures out which tool to call from the user's natural-language question. That's the bar. We'll add a REST surface later for people who want to script against it — but the MCP server is the front door.

How we kept it safe

Read-only by design. There's no delete_scan, no start_scan, nothing that costs money or mutates state. v1 is purely about getting the audit signal into your assistant.

Other things worth calling out for the security-minded:

OAuth 2.1 with PKCE. No bearer tokens in your client config. Each connection runs the full authorization-code + PKCE flow, the access tokens are 1-hour-lived and refresh-rotated, and they're audience-bound to /api/mcp via RFC 8707 so a leaked token can't be replayed against any other resource we ever ship.
Hash-at-rest. Access tokens, refresh tokens, authorization codes, and client secrets are all SHA-256-hashed before they touch the database. The raw value is shown to your client exactly once, at mint time, and never again.
Per-token, per-user, per-client rate limits. Backed by Upstash Redis (sliding window). 60/min per token, 200/min per user, 1000/min per client. 429s come back with the standard Retry-After and X-RateLimit-* headers so a well-behaved client can back off without guessing.
One-click revoke. Settings → Integrations shows every connected client with a "Disconnect" button (and a per-token revoke for the cautious). Revocation is immediate — the next request fails 401.

If you want the full spec story: we follow MCP 2025-03-26, RFC 7591 Dynamic Client Registration, RFC 8414 Authorization Server Metadata, RFC 9728 Protected Resource Metadata, RFC 7009 Token Revocation, and RFC 8707 Resource Indicators. Your client doesn't have to hard-code anything PageLens-specific to discover and connect.

Try it now

Hit pagelensai.com/mcp.
Copy the config block for your assistant.
Restart, click through the consent screen, ask the assistant what it can see.

That's it. If you've already run a PageLens scan, you're 30 seconds away from "tell me what to fix" working in your editor.

What's next

A few things on the roadmap, in roughly this order:

start_scan (write tool, opt-in scope). The natural follow-up: an assistant noticing your verified domain hasn't been re-scanned in two months and offering to kick one off. Gated behind a separate write:scans scope so the read-only default stays read-only.
Streaming tool outputs. A long list_findings call on a Professional scan should stream results progressively rather than blocking on the full payload.
Webhook/notification subscriptions. "Tell my assistant when a new scan completes" — the right shape is probably MCP notifications driven by our existing scan-completion event.

If you've got a use case we haven't thought of, we'd love to hear it — drop us a line at the contact form or @ us wherever we hang out. The dogfood loop is the only thing that's ever shipped good MCP tooling, and the more shapes of "audit-meets-assistant" we hear about, the better v2 gets.