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:

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

This page covers how to connect:

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

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.

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.

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, 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.

(Tip: you can also go directly to 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.

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

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.

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

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.

{
  "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:

{
  "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:

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.

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

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

Swipe File — Saved Ads

Boards — Organize Collections

Saved Searches — Reusable Explore Filters

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.

Your Account — Business Profile

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

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:

{
  "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

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. 🙂

Updated on: 21/09/2026