# AiroPages MCP server docs

> Connect Claude Code, Cursor or any MCP client to AiroPages. Setup snippets, the full tool list, plan access, guardrails and an example session.

Connect your coding agent to AiroPages so it can read grouped issues, fetch fix prompts, re-scan the pages it changed and compare before and after.

## Overview

Remote MCP server at https://mcp.airopages.com (Streamable HTTP). Authenticate with `Authorization: Bearer <KEY>`. A key only reaches the sites on its own account.

## Get an API key

1. Sign in and open API keys in the dashboard (https://app.airopages.com/settings/api-keys).
2. Create a key with read scope, or run scope (Pro and Agency) to allow re-scans.
3. Copy the key. The dashboard shows setup snippets with your key filled in.

## Claude Code

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

## Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

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

## Other clients

Any MCP client that supports remote Streamable HTTP servers with custom headers. URL https://mcp.airopages.com, name `airopage`, header `Authorization: Bearer <KEY>`.

## 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` response:

```json
{
  "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.

## Troubleshooting

- 401: key wrong, revoked or missing the Bearer prefix.
- 403 on run_audit: read-scoped key or read-only plan. Re-scans need Pro or Agency.
- 429: over 60 calls per minute or the key's daily scan cap.
- No URL scans left: call check_allowance. Allowances reset monthly.