> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hadoseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> Every tool the Hado SEO MCP server exposes, with parameters

> [!NOTE]
>
> The MCP server is currently in **beta**. Tools and response shapes are
> subject to change.

The server exposes **19 tools**. Each maps to a [REST API](https://docs.hadoseo.com/api-reference/introduction.md) endpoint and behaves identically — same validation, same permissions, same responses.

Conventions used below:

* **domainId** is the domain's UUID from `list_domains`.
* **Windows** are a rolling `period` (`"7d"`, `"30d"`, `"90d"`, `"365d"`) *or* an explicit `startDate`/`endDate` (`YYYY-MM-DD`, UTC).
* Tools marked **write** require a key with the `write` scope and the `owner` or `manager` role on the domain.

## Analytics tools (read)

### `list_domains`

Lists every domain the account can access — owned and shared — with each domain's UUID and your role. Takes no arguments. Agents should call this first; most other tools need the UUID.

### `get_crawl_summary`

Daily crawler-visit rollups: totals per domain and per bot (Googlebot, GPTBot, …) with verification tiers and bot intents. Equivalent to [Export Crawl Analytics](https://docs.hadoseo.com/api-reference/endpoint/export-crawl-analytics.md).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `period` / `startDate` / `endDate` | string | No | Window, up to 365 days. Defaults to the last 30 days. |
| `domainId` | string | No | Limit to one domain; omit for account-wide. |

### `get_page_analytics`

Per-path crawl counts for one domain — which pages bots visit and how often. Equivalent to [Export Page Analytics](https://docs.hadoseo.com/api-reference/endpoint/export-page-analytics.md).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domainId` | string | Yes | |
| `period` / `startDate` / `endDate` | string | No | Window, up to 365 days. |
| `sortBy` | string | No | Path ordering; default `total` (most-crawled first). |
| `pageSize` | integer | No | Rows per page. |
| `cursor` | string | No | Opaque cursor from the previous page. |
| `series` | boolean | No | Include a per-day time series per path. |

### `get_ai_referrals`

Daily counts of human visits referred by AI assistants (ChatGPT, Perplexity, …). Equivalent to [Export AI Referrals](https://docs.hadoseo.com/api-reference/endpoint/export-ai-referrals.md).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `period` / `startDate` / `endDate` | string | No | Window, up to 365 days. |
| `domainId` | string | No | Limit to one domain; omit for account-wide. |

### `export_crawl_logs`

Raw per-request crawl log events for one domain: timestamp, path, bot, verification verdict, what was served, and status. Equivalent to [Export Crawl Logs](https://docs.hadoseo.com/api-reference/endpoint/export-crawl-logs.md).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domainId` | string | Yes | |
| `period` / `startDate` / `endDate` | string | No | Window, up to **31 days** for raw logs. |
| `format` | string | No | `json` (default), `csv`, or `parquet`. Parquet returns presigned download URLs instead of rows — prefer it for bulk analysis. |
| `pageSize` | integer | No | Rows per page, up to 2,000. |
| `cursor` | string | No | Opaque cursor from the previous page. |

### `get_bot_definitions`

The bot taxonomy used in analytics responses: operators, bot IDs, categories, intents, and the published definitions version. Equivalent to [Bot Definitions](https://docs.hadoseo.com/api-reference/endpoint/bot-definitions.md).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `version` | string | No | A published snapshot like `"1.0"`; omit for the current one. |

## Cache rule tools

Cache rules set how often pages matching a path pattern are re-rendered in the background. Rule creation requires **Pro or above** on the domain owner's plan; the number of rules and the fastest allowed refresh depend on the plan.

### `list_cache_rules` (read)

| Parameter | Type | Required |
| - | - | - |
| `domainId` | string | Yes |

Returns the rules plus the plan's rule `limit` and `minFreshHours` — the fastest refresh cadence the plan allows.

### `create_cache_rule` (write)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domainId` | string | Yes | |
| `pathPattern` | string | Yes | Exact path (`/pricing`) or prefix wildcard (`/blog/*`). |
| `freshHours` | integer | Yes | Refresh cadence in hours — at least the plan's `minFreshHours`, at most 720. |
| `isActive` | boolean | No | Default `true`. |
| `notes` | string | No | Up to 2,000 characters. |

Matching priority is derived from pattern specificity automatically (the most specific pattern wins); it can't be set by hand.

### `update_cache_rule` (write)

Same fields as create, all optional; plus `ruleId` (required). Only the fields you pass change.

### `delete_cache_rule` (write)

Takes `domainId` and `ruleId`. Matching pages fall back to the domain's default freshness.

## Blocked path tools

Blocked paths are excluded from prerendering, with optional per-path robots directives.

### `list_blocked_paths` (read)

| Parameter | Type | Required |
| - | - | - |
| `domainId` | string | Yes |

### `create_blocked_path` (write)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domainId` | string | Yes | |
| `pathPattern` | string | Yes | Path to block, starting with `/`. |
| `isActive` | boolean | No | Default `true`. |
| `noindex` | boolean | No | Send `X-Robots-Tag: noindex` for matching paths. Default `false`. |
| `nofollow` | boolean | No | Send `X-Robots-Tag: nofollow` for matching paths. Default `false`. |
| `notes` | string | No | Up to 2,000 characters. |

### `update_blocked_path` (write)

Same fields as create, all optional; plus `blockedPathId` (required).

### `delete_blocked_path` (write)

Takes `domainId` and `blockedPathId`. Matching pages become eligible for prerendering again.

## Routing rule tools

Redirects and proxies on your **live domain** — these affect real visitor traffic, not just bots. The tools mirror the [routing rules endpoints](https://docs.hadoseo.com/api-reference/endpoint/create-routing-rule.md), including [source path patterns](https://docs.hadoseo.com/api-reference/endpoint/create-routing-rule.md#source-path-patterns) and target rules.

### `list_routing_rules` (read)

| Parameter | Type | Required |
| - | - | - |
| `domainId` | string | Yes |

### `create_routing_rule` (write)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domainId` | string | Yes | |
| `sourcePath` | string | Yes | Path to match, e.g. `/old-page` or `/docs/*`. |
| `targetUrl` | string | Yes | Redirect: a path or absolute http(s) URL. Proxy: an absolute http(s) URL. |
| `ruleType` | string | No | `redirect` (default) or `proxy`. |
| `redirectCode` | integer | No | `301` (default) or `302`; redirects only. |
| `priority` | integer | No | Higher is checked first. Default `0`. |
| `isActive` | boolean | No | Default `true`. |
| `notes` | string | No | Up to 2,000 characters. |

### `update_routing_rule` (write)

Same fields as create, all optional; plus `ruleId` (required).

### `delete_routing_rule` (write)

Takes `domainId` and `ruleId`. Traffic matching `sourcePath` stops being redirected or proxied immediately.

## Actions

### `purge_cache` (write)

Re-renders one page or an entire site right now, spending the account's render budget. Equivalent to [Purge Cache](https://docs.hadoseo.com/api-reference/endpoint/purge-cache.md). Note this tool takes the **hostname**, not a UUID.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `domain` | string | Yes | Hostname as shown in `list_domains`, e.g. `example.com`. |
| `path` | string | No | Page to purge, e.g. `/pricing`. Required unless `scope` is `site`. |
| `scope` | string | No | Pass `site` to purge every page — prefer a single `path` where possible. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.