Connect GetHookd to AI agents (MCP)

Public mirror of the canonical setup guide. Frontmatter-driven title (“MCP Server Setup Guide”) is the single document title; this ## heading is the body’s section opener.

The Gethookd MCP server lets any Model Context Protocol-compatible client (Claude Desktop, Claude Code, Cursor, custom agents) call the Gethookd read API through structured tools - no custom REST integration required.

This page bundles three setup guides:

1. Claude Desktop
2. Claude Code
3. Generic MCP client (curl)

All three guides target the same versioned endpoint:

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

The /api/ prefix is added by Laravel’s route service provider - it’s present in every Public API URL on this domain. Don’t drop the /v1 either - the unversioned /mcp form is reserved for protocol upgrades and will not respond.

Prerequisites

• A Gethookd account on a paid plan (Public API access is gated by the public_api feature flag).
• A Public API token. Create one in Settings → API Tokens in your Gethookd account, copy it, and keep it private - treat it like a password.
• The token’s scopes determine which tools you can call. The MCP server honours the same scope grants as /api/v1/*:
  • explore:read - search_ads, get_ad
  • brand-spy:read - get_brand, search_brands, list_brand_spies, get_brand_spy, get_top_ads

If a tool returns 403 Forbidden. Missing scope: <name>, edit the token in Settings and grant the missing scope.

Cost & billing

The MCP server uses the same public_api credit feature as the REST API, and each tool charges credits the same way the /api/v1/* endpoint it wraps does - so an MCP-driven request and a direct curl cost the same.

credits_cost is set on your plan; check Settings → API Tokens for the current rate. Every charged response includes the running tally:

{
  "errors": false,
  "data": [...],
  "meta": { "result_count": 5 },
  "used_credits": 0.05,
  "remaining_credits": "9.95"
}

If your workspace can’t afford the request’s upper bound, the call returns 402 Insufficient credits before any work runs:

{
  "errors": true,
  "code": "insufficient_credits",
  "message": "Not enough credits"
}

Free tools (get_ad, get_brand, search_brands, get_top_ads) never include used_credits / remaining_credits in the envelope and are unaffected by 402 gating - they keep working at 0 credits.

Limit-billed plans (plan_usage_type != credit) bypass the credit gate entirely; their quota is enforced by a separate downstream rate limiter rather than per-call deduction.

Claude Desktop

Claude Desktop reads MCP server config from a single JSON file. The file path depends on your OS:

If the file doesn’t exist, create it. Open it in your editor of choice and paste the block below. If mcpServers already has other entries, 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_KEY>"
      }
    }
  }
}

Replace <PASTE_YOUR_API_KEY> with the token you copied from Settings → API Tokens. Save the file, then fully quit and relaunch Claude Desktop (config is read at process start; a window reload is not enough).

To verify, open a new chat and type:

List the brands I’m spying on.

Claude should call the list_brand_spies MCP tool and return the brand list. If it doesn’t, see Troubleshooting below.

See also: Claude Code, Generic MCP client.

Claude Code

Claude Code reads MCP server config from .mcp.json in the current working directory (per-project), or ~/.claude/mcp.json (global). The shape is the same as Claude Desktop’s - only the file location differs.

Add a gethookd entry to your .mcp.json. If the file already has other servers (e.g. atlassian), add gethookd as a sibling:

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

Replace <PASTE_YOUR_API_KEY> with the token from Settings → API Tokens. Restart your Claude Code session (/exit then re-open) so the harness re-reads the config.

To verify:

/mcp

gethookd should show as a connected server with 27 tools listed — spanning ad search (search_ads, get_ad), brand spy (list_brand_spies, start_brand_spy), boards (list_boards, create_board, add_ad_to_board), swipe file (save_ad_to_swipe_file, list_swipe_file), saved searches (create_saved_search, list_saved_searches), and AI clone-ads (create_clone_ad, list_clone_ads).

See also: Claude Desktop, Generic MCP client.

Generic MCP client (curl)

The MCP server speaks plain HTTP under the hood. Any client that can issue authenticated HTTP requests can use it directly. Below are the two endpoints you’ll most commonly hit.

List the tool manifest

curl -sS \
  -H "Authorization: Bearer <PASTE_YOUR_API_KEY>" \
  -H "Accept: application/json" \
  https://app.gethookd.ai/api/mcp/v1/tools

Expected response (truncated):

{
  "protocol_version": "2024-11-05",
  "server": { "name": "gethookd-mcp", "version": "1.0.0" },
  "tools": [
    {
      "name": "search_ads",
      "description": "Search the Gethookd ad library by free-text query, platform, performance bucket, and other filters. ...",
      "input_schema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer" } } }
    }
  ]
}

Invoke a tool

curl -sS \
  -X POST \
  -H "Authorization: Bearer <PASTE_YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"tool":"search_ads","arguments":{"query":"dropshipping","limit":5}}' \
  https://app.gethookd.ai/api/mcp/v1/call

Expected response shape:

{
  "errors": false,
  "data": [ { "id": 12345, "external_id": "...", "platform": "facebook" } ],
  "meta": { "result_count": 5 }
}

Error envelopes follow { "errors": true, "code": "<machine-readable>", "message": "<human-readable>" }. Common codes:

The full tool list is the canonical source of truth - GET /api/mcp/v1/tools returns the manifest with descriptions, input schemas, and examples.

See also: Claude Desktop, Claude Code.

Troubleshooting

If none of those apply, file a support ticket with:

• Your client (Claude Desktop / Claude Code / curl / other)
• The exact request you made (token redacted)
• The full response (status code + body)

Versioning

The endpoint URL includes a major-version segment (/v1). Future protocol-breaking changes will ship under /v2 while /v1 keeps responding to existing clients. Setup guides on this page will be revised whenever /v1 adds non-breaking tools or properties - no client-side change needed for those.

If you ever see a 404 on /api/mcp/v1, the version was retired. Check the helpdesk index page at the top of this guide for the current supported versions.