MCP

Connect Gethookd to Claude (and other AI agents) over the Model Context Protocol (MCP). Once connected, you can ask Claude things like “List the brands I’m spying on” or “Find me dropshipping ads with 4+ star performance” and it will pull the data straight from your Gethookd account.

This page covers four ways to connect:

1. Claude.ai web (recommended for most users) — 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. Other MCP clients (Cursor, custom agents, curl)

All four target the same MCP endpoint:

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

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 “MCP (all tools)” scope — this single scope covers all seven read tools (search ads, get ads, brand spy lookups, etc.)
2. Pick the workspace you want Claude to access from the dropdown — Claude will read data from 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 all seven tools:

• get_ad, get_brand, get_brand_spy, get_top_ads, list_brand_spies, search_ads, search_brands

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 it explore:read and brand-spy:read scopes, 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 seven tools listed.

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 seven read-only tools on your behalf:

All tools are read-only — Claude cannot modify your account, change your spied brands, or charge credit packs.

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 (get_ad, get_brand, search_brands, get_top_ads) never deduct credits and keep working even at 0 balance.

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: 15/05/2026