> ## 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 Setup

> Connect Claude, Claude Code, Cursor, or any MCP client to Hado SEO

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

Connecting any client takes the same three ingredients:

* **Server URL:** `https://api.hadoseo.com/functions/v1/mcp`
* **Transport:** HTTP (sometimes labeled "Streamable HTTP")
* **Header:** `Authorization: Bearer hado_sk_your_key_here`

## Step 1 — Create an API key

**1. Open API Keys**

In the [dashboard](https://hadoseo.com/dashboard), go to **Settings → API
Keys**. Available on every plan — your plan sets the
[monthly call quota](https://docs.hadoseo.com/api-reference/authentication.md#plan-limits).

**2. Create a key for the agent**

Create a dedicated key per agent (so you can revoke one without breaking
the others). Under **Permissions**, choose **Read-only** unless the agent
should change configuration — see
[key scopes](https://docs.hadoseo.com/api-reference/mcp/overview.md#key-scopes).

**3. Copy it once**

The full `hado_sk_...` key is shown only at creation time. Store it like a
password.

> [!WARNING]
>
> MCP keys live in agent config files (for example `.mcp.json`), which are easy
> to commit or share by accident. Never put a key in a repository, and revoke
> any key you suspect has leaked — revocation is immediate.

## Step 2 — Connect your client

### Claude Code

```sh theme={null}
claude mcp add --transport http hadoseo \
  https://api.hadoseo.com/functions/v1/mcp \
  --header "Authorization: Bearer hado_sk_your_key_here"
```

Then verify with `/mcp` inside a session — you should see the `hadoseo` server with 19 tools.

### Claude (claude.ai and desktop)

1. Go to **Settings → Connectors → Add custom connector**.
2. Enter the server URL, and add the `Authorization` header with your key.
3. Enable the connector in a chat, then ask Claude to *"list my Hado SEO domains"*.

### Cursor

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

```json theme={null}
{
  "mcpServers": {
    "hadoseo": {
      "url": "https://api.hadoseo.com/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer hado_sk_your_key_here"
      }
    }
  }
}
```

### Other MCP clients

Any client that supports the HTTP transport with custom headers works the same way. For a quick interactive check outside any agent, use the MCP Inspector:

```sh theme={null}
npx @modelcontextprotocol/inspector
```

Choose **Streamable HTTP**, enter the URL, and add the `Authorization` header.

## Step 3 — Verify

Ask your agent to list your domains, or test from the command line:

```sh theme={null}
curl -s -X POST https://api.hadoseo.com/functions/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_domains","arguments":{}}}'
```

A working setup returns your domains with their IDs and your role on each.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| `plan_upgrade_required` | The agent tried a feature the domain owner's plan doesn't include (for example, cache rules on Starter). The MCP server itself works on every plan. |
| `insufficient_scope` | The key is read-only and the agent tried a write tool. Create a key with the `write` scope if that's intended. |
| `invalid_api_key` (401) | The header is missing or the key is wrong or revoked. Check the client is actually sending the `Authorization` header. |
| `rate_limit_minute` / `rate_limit_month` (429) | The key hit 60 requests/minute or its monthly quota. Agents retrying in a loop burn through this fast — stop the loop first. |
| `domain_not_found` on a real domain | The key's account doesn't own that domain and has no active share for it. Run `list_domains` to see what the key can reach. |


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