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 more than 80 tools — across Explore, Brand Spy, Swipe File, Boards, Saved Searches, Shops, Clone Ads and your account — so an AI agent can do nearly everything a logged-in user can do, including create, update, and delete actions. Your agent is only shown the tools your plan includes and your connection has permission for, so it never tries something it can't do.

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. ChatGPT (manual) — OAuth login through ChatGPT's Plugins page
4. Claude Desktop (manual) — the desktop app uses the same connector as Claude on the web
5. Claude Code (manual) — for the Claude Code CLI / IDE harness
6. 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 (web, desktop app and Cowork) and ChatGPT. No API token, no copy-paste of secrets.
• An API key — for 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 (one tile for Claude on the web, the desktop app and Cowork), 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 — Finish in Your Agent

What happens next depends on the client you picked:

• Claude — Claude opens in a new tab with the Gethookd connector already filled in, and your OAuth Client ID is copied to your clipboard. In the Claude tab: click Continue, open Advanced settings, paste the OAuth Client ID (leave the client secret blank), click Connect, then approve on the Gethookd page that opens. If your browser blocked the new tab, click Open Claude on the Gethookd page. If the dialog opens empty — or you only use the Claude desktop app or Cowork — add it by hand in Claude under Settings → Connectors → Add custom connector, and keep the name Gethookd.
• ChatGPT — Gethookd copies a ready-to-use message to your clipboard. Paste it into ChatGPT as a chat message; it gives you the server URL and OAuth Client ID and walks you through ChatGPT's Plugins page. You sign in with your Gethookd account — no API key. The same steps are written out under ChatGPT (Manual Setup).
• Claude Code, Codex, Cursor, Windsurf, Clawbot, Hermes, and Other agent — Gethookd copies a message that includes a fresh, private API key. Paste it into your agent as a chat message; it reads the message, fetches the setup steps on its own, and configures the connection for you. You don't touch a config file.

Step 4 — Watch It Connect

Leave the API & MCP page open. Once your agent finishes the handshake — or, for Claude and ChatGPT, you finish signing in and ask your first question — the page flips to Connected on its own. No separate "test it" step needed.

Prefer to do it by hand? Click Set up manually under the button for a step-by-step guide inside the app. 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 → AI Agent tab, click Set up manually and pick Claude. Copy these two values:

• AI Agent URL: https://app.gethookd.ai/api/mcp/v1
• OAuth Client ID — looks like a long alphanumeric string

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

Step 1 — Open the Customize Panel in Claude

In Claude — on the web, in the desktop app or in Cowork — open Settings → Connectors. On the web you can also 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, exactly. Claude uses this name to decide when to send a request to Gethookd, so with any other name the connector connects but never gets used
2. Remote MCP server URL — paste the AI Agent URL, 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. swipe-file:write, brand-spy: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 tools available to your connection. 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.

ChatGPT (Manual Setup)

ChatGPT signs in with your Gethookd account, like Claude — no API key. You need chatgpt.com in a browser (not the mobile app) on a Plus, Pro, Business, Enterprise or Edu plan.

1. Open chatgpt.com/plugins.
2. Click Add (top right), then Add custom MCP server.
3. Name it Gethookd. Leave Connection on Server URL and paste https://app.gethookd.ai/api/mcp/v1. Leave Authentication on OAuth.
4. Open Advanced OAuth settings. Set Registration method to User-Defined OAuth Client, paste your OAuth Client ID from the Gethookd API & MCP page into OAuth client ID, and leave OAuth client secret blank.
5. Tick I understand and want to continue, click Create as a plugin, then sign in to Gethookd and approve.

No Add menu? Your ChatGPT is still on its earlier screens: go to Settings → Plugins, turn on Developer mode, then Browse plugins and the + button. On a managed workspace, look under Workspace settings → Plugins. (OpenAI has also called this section Apps and Connectors.)

Claude Desktop (Manual Setup)

The Claude desktop app connects exactly like Claude on the web: through a custom connector that signs in with your Gethookd account. It doesn't use an API token, and adding Gethookd to claude_desktop_config.json won't work.

In the desktop app, open Settings → Connectors → Add custom connector, name it Gethookd, and follow the same steps as in Claude.ai Web (Manual Setup) above. The same goes for Cowork, which is part of the desktop app. Or use the one-click flow at the top of this page and pick the Claude tile.

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

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 its tool list.

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 Code above. 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 tools your token can use — the ones your plan includes and your token has the scope for — with their 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 API reference.

Available Tools

Once connected, Claude can call more than 80 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. (This needs the account:read scope — without it your agent skips the questions and you simply tell it your niche and market when you search.) 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 “skip survey” and your agent won’t ask again — and if you change your mind, say “start survey” any time to answer the questions later.

Clone Ads — AI Ad Generation

Write tools will only succeed if your token (or OAuth grant) includes the matching :write scope. Tools your connection has no scope for aren't shown to your agent at all. If one is called anyway, the call returns Forbidden. Missing scope: <name> together with what to do about it (create a new token with that scope ticked, then reconnect), 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, get_top_hooks, get_ad_hooks, list_niches, list_page_types, list_saved_searches, get_saved_search, list_folders, list_clone_ad_models, the transcription tools (transcribe_ad, transcribe_ads, get_transcription_status), get_shop_brand_group, list_shop_languages, and list_shop_technologies.

To see the current rates, open Credits & Usage from your profile menu and click see what actions cost — the API & MCP group lists what a read and each write costs.

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: 13/10/2026