MCP server documentation.

Overview

AiroPages runs a remote MCP server at https://mcp.airopages.com using the Streamable HTTP transport. Authenticate with an API key in the Authorization: Bearer <KEY> header. Chat apps that can’t send headers (Claude, ChatGPT) use a private connector URL with the key in it instead. A key only reaches the sites on its own account.

Get an API key

1. Sign in and open API keys in the dashboard.
2. Create a key. Choose read scope to let the agent read results, or run scope (Pro and Agency) to let it start re-scans.
3. Copy the key. The dashboard shows ready-made setup snippets with your key filled in.

Claude (claude.ai, desktop and mobile)

No code needed. It takes about a minute.

1. In API keys, create a key and copy your private connector URL. It looks like https://mcp.airopages.com/k/<KEY>/mcp.
2. In Claude, open Customize → Connectors.
3. Click + Add, then Add custom connector.
4. Name it AiroPages, paste the URL and click Add. No sign-in step: the URL holds your key.
5. In a new chat, turn on AiroPages from the + (tools) menu and ask “Which pages on my site need the most work?”

Free Claude accounts can add one custom connector. On Team and Enterprise, an owner adds it under Organization settings → Connectors and members connect it.

ChatGPT

Custom MCP apps are available on ChatGPT Business, Enterprise and Edu, and on some personal plans through developer mode.

1. Copy your private connector URL from API keys, as above.
2. In ChatGPT, open Settings → Apps (on some accounts it’s called Plugins or Connectors). If there’s no create option, turn on Developer mode under Advanced settings.
3. Choose Create (or + → Add custom MCP server), name it AiroPages and paste the URL.
4. Set Authentication to No authentication, tick I understand and want to continue, and create it.
5. In a new chat, pick AiroPages from the + menu and ask “Summarize my site’s biggest performance issues.”

Treat the connector URL like a password. Revoke the key in the dashboard to switch it off.

Chat apps vs Claude Code

The tools are the same; what the assistant can do with them is not.

• Claude and ChatGPT (chat): ask about your scores in plain words, get each issue explained with the fix written out, and re-scan a page after you fix it (Pro and Agency). They can’t change your site’s code. Best for owners, marketers and anyone who doesn’t code.
• Claude Code, Cursor and other coding agents: everything above, plus they work inside your codebase. They find the files behind an issue, make the fix, and re-scan to prove it worked.

Claude Code

Run this once in your terminal, replacing <KEY> with your API key:

claude mcp add --transport http airopage https://mcp.airopages.com --header "Authorization: Bearer <KEY>"

Then start claude in your project and ask it to list the grouped issues for your site.

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it everywhere:

{
  "mcpServers": {
    "airopage": {
      "url": "https://mcp.airopages.com",
      "headers": {
        "Authorization": "Bearer <KEY>"
      }
    }
  }
}

Other clients

Any MCP client that supports remote servers over Streamable HTTP with custom headers can connect. Use the server URL https://mcp.airopages.com, the name airopage, and the header Authorization: Bearer <KEY>. Most clients accept the same JSON shape as Cursor.

Tools

Tool	Purpose	Uses URL scans
list_sites	Sites on the account	No
get_site_summary	Scores, trends and top issues for a site	No
list_issues	Grouped issues, filtered by site, device, category or template	No
get_issue	Evidence, resources and affected URLs for one issue	No
get_page_report	Lighthouse results for one URL and device	No
get_fix_prompt	The same output as the "Copy for coding agent" button	No
run_audit	Re-scan URLs (mobile and desktop). Returns job_id, eta, allowance_left and a hint	Yes
get_audit_status	Progress, partial results and ETA	No
wait_for_audit	Blocks up to 5 minutes, then returns status	No
compare_runs	Before and after diff for a site or URLs	No
check_allowance	Remaining URL scans this month	No

run_audit returns immediately:

{
  "job_id": "job_8f2k",
  "scans": 6,
  "eta_seconds": 90,
  "status": "queued",
  "allowance_left": 4210,
  "hint": "Call wait_for_audit for jobs under 5 min."
}

Access by plan

Plan	MCP access
One-time scan	Read-only, for 30 days
Starter	Read-only
Pro	Read + run_audit
Agency	Read + run_audit + multiple keys

Guardrails

• Each key has a daily scan cap (200 by default).
• MCP re-scans draw from the same monthly URL scan allowance as the dashboard.
• Every scan uses PageSpeed Insights settings on each device.
• Keys are scoped (read or run) and revocable, and only reach your own sites.
• Rate limit: 60 calls per minute per key.
• MCP-triggered jobs still send in-app and email notifications.

Example session

You: Fix the top performance issue on example.com and prove it worked.

Agent → list_issues { site: "example.com", device: "mobile", category: "performance" }
Agent → get_fix_prompt { issue_id: "iss_31" }
Agent   edits 2 files in the blog template
Agent → run_audit { urls: ["https://example.com/blog/a", "..."] }
{
  "job_id": "job_8f2k",
  "scans": 6,
  "eta_seconds": 90,
  "status": "queued",
  "allowance_left": 4210,
  "hint": "Call wait_for_audit for jobs under 5 min."
}
Agent → wait_for_audit { job_id: "job_8f2k" }
Agent → compare_runs { job_id: "job_8f2k" }
Agent: LCP fell from 4.1 s to 1.9 s on 6 URLs. Performance 62 → 94.

Troubleshooting

• 401 Unauthorized: the key is wrong, revoked, or missing the Bearer prefix.
• 403 Forbidden on run_audit: the key has read scope, or your plan is read-only. Re-scans need Pro or Agency and a run-scoped key.
• 429 Too Many Requests: the key passed 60 calls per minute or its daily scan cap. Wait, or raise the cap in the dashboard.
• No URL scans left: call check_allowance. Allowances reset monthly.

Still stuck? Contact us.