aeogeo.site

← Docs

Connect an MCP client the right way for your plan, scan your own domain for free, then read a rule with its evidence and verify a fix with a Pro key.

First run (15 minutes)

Two journeys from one URL. Free (steps 1–2, 4): connect without a key, scan your own domain, install the hook. Pro (steps 3 and 5): read rules with their evidence and verify a fix. The examples below are trimmed from real output (ruleset v25).

1. Connect the MCP server

There are two addresses and two ways to authenticate. Pick the one your client supports:

If your client says the server "connects without auth" or lists only six tools, you added the bare address. That is the free tier: switch the entry to /mcp to sign in, or add the key header. Details and header notes are on /docs/mcp.

Cursor: add to .cursor/mcp.json. Drop the headers block to stay on the free tier:

{
  "mcpServers": {
    "aeogeo": {
      "url": "https://mcp.aeogeo.site",
      "headers": {
        "Authorization": "Bearer ${env:AEOGEO_API_KEY}"
      }
    }
  }
}

Claude Code: run the CLI command (drop --header for the free tier):

claude mcp add --transport http aeogeo https://mcp.aeogeo.site \
  --header "Authorization: Bearer $AEOGEO_API_KEY"

Claude Desktop: Settings → Connectors → Add custom connector with https://mcp.aeogeo.site/mcp, then sign in. Toolport: add the server with https://mcp.aeogeo.site/mcp and complete the sign-in it offers.

Codex: codex mcp add aeogeo --url https://mcp.aeogeo.site/mcp opens your browser to sign in; with a key, use --url https://mcp.aeogeo.site --bearer-token-env-var AEOGEO_API_KEY (details).

Expected output: refresh the tool list. Free callers see the six tools above. Signed-in or keyed callers also see lint_html, lint_text, audit_schema, fetch_rules, search_rules, get_changelog, set_retention_webhook, get_insights, scan_site and get_site_scan.

2. Scan your own domain (free)

Run scan_url on your own live page:

scan_url https://example.com
(use your own public domain, not example.com)

Expected output (free, no key): the shape below, with your page's findings:

{
  "overall": { "grade": "B", "failed": 2, "total": 20, "skipped": 4 },
  "findings": [
    {
      "check_id": "chk-fresh-visible-date",
      "group": "freshness",
      "level": 2,
      "message": "No visible last-updated date.",
      "fix": "Add a visible <time datetime="YYYY-MM-DD"> with the date the page was last updated (machine-readable datetime is recommended even when the visible text is a date)."
    },
    {
      "check_id": "chk-blf-001",
      "group": "answerability",
      "level": 3,
      "advisory": true,
      "message": "First 2 sentences do not state a measured quantity with a verb.",
      "fix": "Lead with a number plus a unit or time span and a verb in sentence 1–2."
    }
  ]
}

Free output shows per-group grades plus every failed fundamental (levels L0–L3) with an executable fix. It does not include rule IDs, evidence, or severity: those need a key. A finding marked advisory is a heuristic, is reported with its fix, and never changes the grade. A grade is automated compliance with the ruleset, not AI visibility or a citation.

3. Read a rule with its evidence (Pro)

A signed-in or keyed caller fetches the full rule text. Rule categories are not the scanner's check groups: the BLUF rule behind chk-blf-001 is in content_template. Use list_categories for the names. 

fetch_rules category: content_template

Expected output (Pro, one rule shown):

{
  "category": "content_template",
  "rules": [
    {
      "id": "aeo-001",
      "source": "https://ahrefs.com/blog/on-page-aeo/",
      "rule": "Open every page with a direct answer to the implied buyer question in the first two sentences (BLUF).",
      "confidence": "hypothesis",
      "causality": "not_established",
      "evaluation_mode": "hybrid",
      "level": 3,
      "checks": ["chk-blf-001", "chk-text-paragraph-length"],
      "evidence": [{ "type": "practitioner_article", "publisher": "Ahrefs (Ryan Law)", "url": "https://ahrefs.com/blog/on-page-aeo/" }]
    }
  ]
}

Read confidence and causality before you rely on a rule: this one is a hypothesis and not_established, so treat it as an experiment, not a guaranteed fix. Free callers get teaser samples without evidence from fetch_sample_rules.

4. Install the hook (free)

get_hook_snippet needs a client: agents_md, cursor or claude. 

get_hook_snippet client: claude
(client is required: agents_md, cursor or claude)

Paste the result where the client reads instructions. The snippet ends with a "To remove:" block, so removal is reversible (/docs/mcp/remove).

5. Apply one fix and verify it (Pro)

Take the first non-advisory fix from step 2, apply it, deploy it, then run scan_url again. A keyed scan always fetches fresh: 

scan_url https://example.com
(use your own public domain, not example.com)

Expected output: the fixed finding is gone; an advisory one can remain without moving the grade:

{
  "overall": { "grade": "A", "failed": 0, "total": 20, "skipped": 4 },
  "findings": [
    {
      "check_id": "chk-blf-001",
      "group": "answerability",
      "level": 3,
      "advisory": true,
      "message": "First 2 sentences do not state a measured quantity with a verb."
    }
  ]
}

The scan checks the mechanics. Whether the page is accurate, original and useful is still for you or your agent to judge: call plan_audit for the full audit steps. If a step stops working, every error includes an executable fix.

Updated