> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://gethookdai.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# MCP

Connect Gethookd to your favorite AI assistant over the **Model Context Protocol (MCP)** — an open standard. Once connected, you can ask your AI agent things like *“Save the top ad from this brand to my Swipe File”* or *“Generate three variations of this ad with a holiday theme”* and it will run the action straight against your Gethookd account.

Because MCP is an open standard, **Gethookd isn’t tied to a single assistant** — any MCP-compatible client can connect to the same endpoint. Claude is the quickest to set up (it offers a one-click OAuth login), but Cursor, other AI agents, and your own scripts work just as well.

The MCP server exposes **27 tools across six surfaces** — Explore, Brand Spy, Swipe File, Boards, Saved Searches, and Clone Ads — so an AI agent can do nearly everything a logged-in user can do, including create, update, and delete actions.

All connections target the same MCP endpoint:

```text
https://app.gethookd.ai/api/mcp/v1
```

This page covers how to connect:

1. [**One-click setup (recommended — works for any supported client)**](#one-click-setup-the-fastest-way) — paste one message into your AI agent and it connects itself
2. [Claude.ai web (manual)](#claudeai-web-manual-setup) — OAuth login, step by step
3. [Claude Desktop (manual)](#claude-desktop-manual-setup) — for the macOS / Windows / Linux app
4. [Claude Code (manual)](#claude-code-manual-setup) — for the Claude Code CLI / IDE harness
5. [Any other MCP client (Cursor, custom agents, curl)](#other-mcp-clients)

---

## Before You Start

You’ll need:

* A plan that includes MCP — **every annual plan** (Starter, Pro, Team or Agency), plus the **monthly Team and Agency** plans. Monthly Starter and Pro don't include it.
* The **API & MCP page** open in your Gethookd account (left sidebar → **API & MCP**). This is where you’ll find the values you need to paste into Claude.

Depending on which client you’re using, you’ll either need:

* An **OAuth Client ID** — for Claude.ai web (recommended path). No API token, no copy-paste of secrets.
* A **Public API token** — for Claude Desktop, Claude Code, Cursor, or any other MCP client.

Both are available on the same **API & MCP** page.

---

## One-Click Setup (The Fastest Way)

Most people don't need to copy a URL or paste a token by hand at all. Gethookd can hand your AI agent everything it needs in one message.

### Step 1 — Open the Onboarding Button

From your Gethookd account, go to the left sidebar → **API & MCP**, then click **Onboard your AI agent**.

### Step 2 — Pick Your Client

A small window opens with a tile for each supported client: **Claude Code, Claude Desktop, Claude.ai, Codex, ChatGPT, Cursor, Windsurf, Clawbot, Hermes**, or **Other agent** if yours isn't listed.

Click the tile for the client you use. That's the whole choice — nothing else to fill in.

### Step 3 — Paste It Into Your Agent

Gethookd copies a ready-to-use message to your clipboard and the window closes. Open your AI agent and paste the message as a chat message.

* For **Claude Code, Codex, Cursor, Windsurf, Clawbot, Hermes,** and **Other agent** — the message includes a fresh, private API key. Your agent reads the message, fetches the setup steps on its own, and configures the connection for you. You don't touch a config file.
* For **Claude Desktop, Claude.ai,** and **ChatGPT** — these three sign in with your Gethookd account instead of a key. The pasted message gives your agent the exact values (server URL and OAuth Client ID) and tells it to walk you through your app's own **Connectors** (or **Plugins**) screen, already filled in — you just click through and sign in.

### Step 4 — Watch It Connect

Leave the **API & MCP** page open. Once your agent finishes the handshake — or you finish signing in, for the three OAuth clients above — the page flips to **Connected** on its own. No separate "test it" step needed.

|| TIP: Each API key this creates is tied to one specific client. If you click **Onboard your AI agent** again later and pick the same client, Gethookd reuses that same key instead of creating a new one — so reconnecting never leaves old, unused keys behind.

Prefer to do it by hand, or your client isn't in the list? The manual walkthroughs below cover Claude.ai, Claude Desktop, and Claude Code step by step, and any other MCP client can connect with plain HTTP — see [Other MCP Clients](#other-mcp-clients).

---

## Claude.ai Web (Manual Setup)

Prefer to do this yourself instead of the one-click flow above? Here's the manual path — you sign in with OAuth, pick the workspace you want Claude to access, and you’re done. No API token, no JSON config files.

### What You’ll Need

From your Gethookd account → **API & MCP** page → **Connect to AI agents (MCP)** card, copy these two values:

* **MCP endpoint URL:** `https://app.gethookd.ai/api/mcp/v1`
* **OAuth Client ID** (in the *Claude Custom Connector* sub-section) — looks like a long alphanumeric string

Keep both handy — you’ll paste them in Claude.

### Step 1 — Open the Customize Panel in Claude

Go to [claude.ai/customize](https://claude.ai/customize), or click your profile picture in Claude → **Customize**.

You’ll land on the *Customize Claude* screen. On the left sidebar you’ll see two options: **Skills** and **Connectors**. Click **Connectors**.

![](https://storage.crisp.chat/users/helpdesk/website/-/3/b/d/e/3bdeb53b8659ea00/screenshot-2026-05-15-at-11112_i7ihzd.png)

*(Tip: you can also go directly to [claude.ai/customize/connectors](https://claude.ai/customize/connectors) to skip this step.)*

### Step 2 — Add a Custom Connector

At the top of the **Connectors** panel, you’ll see a **+** icon next to the search bar. Click it. A small dropdown appears with two options:

* **Browse connectors** — Anthropic’s pre-built integrations (Gmail, Google Calendar, GitHub, etc.). **Don’t click this** — Gethookd isn’t in the public catalog yet.
* **Add custom connector** — this is what we want.

Click **Add custom connector**.

![](https://storage.crisp.chat/users/helpdesk/website/-/3/b/d/e/3bdeb53b8659ea00/screenshot-2026-05-15-at-11115_1meuztr.png)

### Step 3 — Fill in the Connector Modal

The *Add custom connector* modal opens with three fields:

1. **Name** — type `Gethookd` (or anything you like — this is just the label you’ll see in Claude’s connector list)
2. **Remote MCP server URL** — paste `https://app.gethookd.ai/api/mcp/v1`
3. Click **Advanced settings** to expand the section
4. **OAuth Client ID** — paste the OAuth Client ID you copied from the Gethookd **API & MCP** page
5. **OAuth Client Secret (optional)** — **leave this blank**. Gethookd uses PKCE for security, so no secret is required.
6. Click **Add**

![](https://storage.crisp.chat/users/helpdesk/website/-/3/b/d/e/3bdeb53b8659ea00/screenshot-2026-05-15-at-11120_1tx463q.png)

|| IMPORTANT: You **must** paste the OAuth Client ID in *Advanced settings* — pasting only the URL will fail with a *“Couldn’t reach the MCP server”* error. See [Troubleshooting](#troubleshooting) if that happens.

### Step 4 — Connect and Approve Access in Gethookd

After you click **Add**, the connector appears in the left list under *Not connected* with a **CUSTOM** badge. Select it, then click the **Connect** button on the right.

A new browser tab opens with the **Gethookd consent screen**, titled *“Authorize Claude Custom Connector to access your Gethookd account”*. On this screen:

1. **Tick the scopes you want to grant** — choose read-only scopes if you only want Claude to look up data, or include the matching `:write` scopes (e.g. `swipefile:write`, `brandspy:write`, `boards:write`, `searches:write`, `clone-ads:write`) if you want it to take actions like saving ads, starting Brand Spy, creating boards, or generating Clone Ads
2. **Pick the workspace** you want Claude to access from the dropdown — Claude will read and write data in this workspace only
3. Click **Allow**

You’ll be redirected back to Claude, and a *“Connected to Gethookd”* toast confirms the connection. The connector moves out of *Not connected* and into the **Web** group.

### Step 5 — Verify the Connection Works

On the right side of the connector’s detail panel, you’ll see a **Tool permissions** section listing the 27 available tools. Each defaults to **Needs approval** — Claude will ask your permission the first time it runs each tool. You can change this to **Allow automatically** later if you trust the connector.

To test, start a new Claude chat and ask:

> *List the brands I’m spying on.*

Claude should ask permission to run the `list_brand_spies` tool. Approve it, and you’ll see your tracked brands appear in the chat.

If it doesn’t work, jump to [Troubleshooting](#troubleshooting).

---

## Claude Desktop (Manual Setup)

The one-click flow above covers Claude Desktop too. If you'd rather do it by hand, for the Claude Desktop app (macOS / Windows / Linux), you connect by adding a JSON entry to a config file. Unlike the web app, this uses an **API token** (not OAuth).

### Get Your API Token

From **API & MCP** page → **Public API Tokens** → click **Create token**. Give it a name, grant the scopes you need (e.g. `explore:read`, `brand-spy:read`, plus any `:write` scopes if you want Claude to take actions), then copy the token immediately — you won’t be able to see it again.

### Edit the Config File

| OS | Config file path |
| ---- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

If the file doesn’t exist, create it. Open it in any text editor and paste the block below. If `mcpServers` already has other entries (e.g. for other MCP servers), add `gethookd` as a **sibling key** — don’t overwrite the file.

```json
{
  "mcpServers": {
    "gethookd": {
      "type": "http",
      "url": "https://app.gethookd.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer <PASTE_YOUR_API_TOKEN>"
      }
    }
  }
}
```

Replace `<PASTE_YOUR_API_TOKEN>` with the token you copied. Save the file, then **fully quit and relaunch Claude Desktop** — the config is only re-read at process start (a window reload is not enough).

To verify, start a new chat and ask: *“List the brands I’m spying on.”* Claude should call the `list_brand_spies` tool.

---

## Claude Code (Manual Setup)

The one-click flow above covers Claude Code too. If you'd rather do it by hand, Claude Code reads MCP server config from `.mcp.json` in your project root (per-project) or `~/.claude/mcp.json` (global). The shape is identical to Claude Desktop’s.

Add a `gethookd` entry:

```json
{
  "mcpServers": {
    "gethookd": {
      "type": "http",
      "url": "https://app.gethookd.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer <PASTE_YOUR_API_TOKEN>"
      }
    }
  }
}
```

Replace the token, save, then restart your Claude Code session (`/exit` and re-open) so the harness re-reads the config.

To verify, type `/mcp` — `gethookd` should appear as a connected server with the full tool list (27 tools across Explore, Brand Spy, Swipe File, Boards, Saved Searches, and Clone Ads).

---

## Other MCP Clients

Any MCP-compatible client that speaks JSON-RPC 2.0 + Bearer authentication will work — Cursor uses the same JSON config shape as Claude Desktop. For custom integrations or scripting, the MCP server accepts plain HTTP POST requests:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer <PASTE_YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://app.gethookd.ai/api/mcp/v1
```

This returns the full tool manifest with input schemas. To call a tool, use `tools/call` with the tool name in `params.name`. The MCP spec mandates an `initialize` handshake before any other call — most real clients handle this transparently. If you’re scripting against the server yourself, send `initialize` first.

Full JSON-RPC reference, error codes, and example requests are in the [Public API documentation](https://app.gethookd.ai/api/documentation).

---

## Available Tools

Once connected, Claude can call **more than 60 tools** on your behalf. The ones you’ll use most are grouped below by surface. Write tools require the matching `:write` scope on the token (or the equivalent scope ticked during OAuth consent).

### Explore — Search the Ad Library

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `search_ads` | Search the Gethookd ad library by query, platform, performance score, ad format, language, geo, date range, and more. Supports page-by-page navigation (up to 20 pages) and a variant-collapse option that groups near-duplicate creatives. You can also point a search at **one specific brand**, so asking for “this brand’s ads about free shipping” returns only that brand’s ads instead of a mixed result set. Results include `asset_type` (`video`, `image`, `carousel`) and the transcript/caption text for video ads. The tool description also documents the numeric boundaries for each performance bucket (`testing` 1–40, `scaling` 41–60, `growing` 61–80, `optimized` 81–90, `winning` 91+) so you can filter with confidence. Want **exact words only**? Ask for it, and results only include ads that contain every word exactly as you typed it — and every result list tells you which ads matched your words only loosely. | `explore:read` |
| `get_ad` | Fetch full details for a single ad by ID, including `asset_type` and transcript text. | `explore:read` |
| `search_brands` | Search brands by name. | `explore:read` |
| `get_brand` | Fetch full details for a brand by ID. | `explore:read` |
| `get_top_ads` | Get the top-performing ads from a tracked brand. Pages through the full list rather than stopping at a fixed cap. | `brand-spy:read` |
| `aggregate_ads` | Count how many ads match a set of filters, without downloading them. Useful for “how many video ads is this niche running?” — and much cheaper than fetching every ad just to count them. | `explore:read` |
| `get_domain_advertisers` | Find every advertiser account running ads that point at a given domain — handy when one company advertises from several pages. | `explore:read` |
| `list_page_types` | Look up the valid page-type values you can filter by, so your agent picks a real one instead of guessing. | `explore:read` |

Any answer that carries a count also says what was counted and when it was measured, so your agent never compares two numbers that mean different things. A country-filtered search additionally reports how many ads it left out because they carry no country data. And an invalid value — a country code that isn't two letters, or a language we don't recognise — comes back as a clear error naming the argument instead of a generic failure.

### Brand Spy — Track Competitors

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_brand_spies` | List the brands you’re currently tracking. Pages through your entire list instead of stopping at the first 100. | `brand-spy:read` |
| `get_brand_spy` | Get full details of one tracked brand. | `brand-spy:read` |
| `start_brand_spy` | Start tracking a new brand. | `brand-spy:write` |
| `stop_brand_spy` | Stop tracking a brand. | `brand-spy:write` |

### Swipe File — Saved Ads

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_swipe_file` | List your saved ads. Accepts both `limit` and the REST-style `per_page` parameter for paging. | `swipe-file:read` |
| `save_ad_to_swipe_file` | Save an ad to your Swipe File — and, if you like, place it straight onto one of your boards in the same step. | `swipe-file:write` |
| `remove_ad_from_swipe_file` | Remove an ad from your Swipe File. | `swipe-file:write` |

### Boards — Organize Collections

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_boards` | List your Boards. | `boards:read` |
| `list_folders` | List your folders — the containers your boards live in — so your agent can create a new board in the right place. Free to call. | `boards:read` |
| `get_board` | Get a board and its ads. | `boards:read` |
| `create_board` | Create a new board. | `boards:write` |
| `update_board` | Rename or update a board. | `boards:write` |
| `delete_board` | Delete a board. | `boards:write` |
| `add_ad_to_board` | Add an ad to a board. | `boards:write` |
| `remove_ad_from_board` | Remove an ad from a board. | `boards:write` |

### Saved Searches — Reusable Explore Filters

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_saved_searches` | List your saved searches. Free to call (no credit cost). | `searches:read` |
| `get_saved_search` | Get a single saved search. Free to call (no credit cost). | `searches:read` |
| `create_saved_search` | Create a saved search. Returns a clear validation error if you reuse a name that already exists in your workspace. | `searches:write` |
| `update_saved_search` | Update a saved search. | `searches:write` |
| `delete_saved_search` | Delete a saved search. | `searches:write` |

### Shops — Research Any Store

Shops tools are available when your plan includes Shops. Most are billed per shop, product or ad returned; the look-up tools marked free cost nothing.

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_shops` | Search the Shops catalog. | `shops:read` |
| `get_shop` | Get one shop's full details — traffic, growth, products, live ads, technologies and country. | `shops:read` |
| `get_shop_traffic` | A shop's estimated monthly visits, how visits have trended over time, and its top visitor countries. | `shops:read` |
| `get_shop_active_ads` | How many ads a shop has live each day, plus the growth over the period. | `shops:read` |
| `get_shop_active_ads_series` | The same active-ads trend, for just one of the shop's linked Meta pages. | `shops:read` |
| `get_shop_launched_ads` | How many **new** ads a shop launched each day. | `shops:read` |
| `list_shop_meta_ads` | Page through the Meta ads matched to a shop. | `shops:read` |
| `list_shop_products` | Page through a shop's product catalogue. | `shops:read` |
| `list_similar_shops` | Find shops similar to the one you're looking at. | `shops:read` |
| `get_shop_brand_group` | Find the other shops that belong to the same brand. Free to call. | `shops:read` |
| `get_shop_linked_pages` | See which Meta pages are linked to a shop. | `shops:read` |
| `get_shop_targeted_countries` | See which EU countries a shop's live ads reach. | `shops:read` |
| `list_shop_languages` | Look up the valid language values you can filter shops by. Free to call. | `shops:read` |
| `list_shop_technologies` | Look up the Shopify apps, themes and pixels you can filter shops by. Free to call. | `shops:read` |

### Your Account — Business Profile

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `get_user_profile` | Read the short business profile you filled in — what you sell and which markets you sell to. | `account:read` |
| `save_user_profile` | Save or update that business profile. | `account:write` |

The first time you connect an agent it will ask you a couple of quick questions about your business and save the answers here. After that, your agent’s searches use your niche and market automatically, so you don’t have to describe your business every time you ask something. If you already answered the same questions when you signed up on our website, it won’t ask again. You can say you’d rather skip it — you’ll just be asked again next time.

### Clone Ads — AI Ad Generation

| Tool | What It Does | Scope |
| ---- | ---- | ---- |
| `list_clone_ads` | List your Clone Ads generation history. | `clone-ads:read` |
| `get_clone_ad` | Get one Clone Ads generation, including all variations. | `clone-ads:read` |
| `create_clone_ad` | Kick off a new AI ad-variation generation from an existing ad. | `clone-ads:write` |

Write tools will only succeed if your token (or OAuth grant) includes the matching `:write` scope. If a scope is missing, the call returns `403 Forbidden. Missing scope: <name>` and nothing is changed on your account.

---

## Cost & Billing

The MCP server uses the same `public_api` credit system as the REST API. An MCP-driven request costs the same as a direct REST call.

Every charged response includes a running tally so you can see your usage in real time:

```json
{
  "errors": false,
  "data": [...],
  "used_credits": 0.05,
  "remaining_credits": 9.95
}
```

If your workspace doesn’t have enough credits, the call returns `402 Insufficient credits` **before** any work runs — you won’t be charged for failed requests.

Free tools never deduct credits and keep working even at 0 balance: `get_ad`, `get_brand`, `search_brands`, `get_top_ads`, `list_saved_searches`, `get_saved_search`, `list_folders`, `get_shop_brand_group`, `list_shop_languages`, and `list_shop_technologies`.

`credits_cost` per call is set by your plan — check the **API & MCP** page in your Gethookd account for the current rate.

---

## Who Has MCP Access

**Which plans include MCP?**
Every annual plan — Starter, Pro, Team and Agency — plus the monthly Team ($79) and Agency ($129) plans. Monthly Starter and Pro don't include it.

**I'm on a monthly Team or Agency plan. Do I need to switch to annual for MCP?**
No. MCP is included on monthly Team and Agency, whenever you signed up.

**I'm on monthly Starter or Pro. How do I get MCP?**
Switch to annual billing on your plan, or move up to Team or Agency (monthly or annual).

**I'm on a free trial. Can I connect an agent?**
If you picked Team or Agency (monthly or annual), or any annual plan, yes — MCP is part of that plan from day one.

---

## Troubleshooting

### *“Couldn’t reach the MCP server”* (Claude.ai web)

If you added Gethookd as a Custom Connector and got an error like:

> *Couldn’t reach the MCP server. You can check the server URL and verify the server is running. If this persists, share this reference with support: “ofid_…”*

**Almost always**, this means you pasted the URL but **didn’t paste the OAuth Client ID in *Advanced settings***. Claude tries to register itself dynamically (DCR), which Gethookd doesn’t support for security reasons.

**Fix:**

1. Remove the broken connector entry (see *Removing a stuck connector* below)
2. Re-add it cleanly — make sure you expand **Advanced settings** and paste the OAuth Client ID before clicking **Add**

### Removing a Stuck Custom Connector

If you already added Gethookd and it won’t connect, or you have leftover entries that look un-removable:

1. Open **Customize → Connectors** in Claude.ai
2. Find the Gethookd entry in the list
3. Click the **chevron** (`˅`) to the right of the connector name — a small menu with a **Remove** action appears
4. If you only see a **Connect** button and no chevron, **refresh the page once** — the chevron menu appears for never-connected entries after a reload
5. Click **Remove** on each stuck entry

If the chevron still doesn’t appear after a refresh, click **Connect** once (it’ll fail again, that’s fine), then refresh — the chevron will be there. This is a Claude UI quirk, not a Gethookd-side issue.

### Common Errors

| Symptom | Likely cause | Fix |
| ---- |
| Claude doesn’t see the server (Desktop / Code) | Invalid JSON in the config file | Validate the file in any JSON linter — common issue is a stray trailing comma |
| `401 Unauthenticated` | Token typo, or token revoked | Recreate the token on the **API & MCP** page; copy the full token (no whitespace) |
| `403 Forbidden. Missing scope: <name>` | Token doesn’t have the scope this tool needs | Edit the token on the **API & MCP** page, grant the missing scope (e.g. `swipefile:write` for save actions), restart your client |
| `429 Too Many Requests` | You hit the per-token rate-limit ceiling | Back off — the limit resets on a sliding window |
| `DNS_PROBE_FINISHED_NXDOMAIN` or *Couldn’t resolve host* | Wrong domain — `gethookd.com` is not a Gethookd hostname | Use `app.gethookd.ai` (with `.ai`, not `.com`) |

---

## Still Stuck?

Message us in the live chat (chat bubble bottom-right of the app) with:

* Your client (Claude.ai web / Claude Desktop / Claude Code / other)
* The exact error message you’re seeing
* If it’s Claude.ai web, the `ofid_…` reference string (helpful for our team to look up the request)

We’ll help you get connected. 🙂