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. Claude.ai web (recommended — easiest setup) — no token to paste, OAuth login
2. Claude Desktop — for the macOS / Windows / Linux app
3. Claude Code — for the Claude Code CLI / IDE harness
4. Any other MCP client (Cursor, custom agents, curl)

Before You Start

You’ll need:

• A paid Gethookd plan — MCP access is gated by the public_api feature flag (Team plan and above).
• 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.

Claude.ai Web (Recommended)

This is the easiest way to connect — 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

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

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 27 tools on your behalf, grouped into six surfaces. Write tools require the matching :write scope on the token (or the equivalent scope ticked during OAuth consent).

Explore — Search the Ad Library

Brand Spy — Track Competitors

Swipe File — Saved Ads

Boards — Organize Collections

Saved Searches — Reusable Explore Filters

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

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

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: 01/06/2026