Developer docs

HookTrend MCP server

HookTrend is a short-form trend research tool for TikTok and YouTube. It watches a library of videos refreshed every day and scores each one by "× usual": its views divided by the creator's usual views per video, so a 40,000-view video from a 2,000-view account stands out as a 20× outlier. Ask it what is breaking out in a niche or a topic, which creators are popping, or start a research agent that searches a brief's keywords live and keeps watching.

Server: https://hooktrend.com/api/mcp · Streamable HTTP, stateless, JSON responses. Agent guide (what the model is told): /agents/guide.md.

Connect

Step-by-step for Claude, ChatGPT, Cursor, Claude Code and n8n: /mcp. Any MCP client:

{
  "mcpServers": {
    "hooktrend": {
      "url": "https://hooktrend.com/api/mcp"
    }
  }
}

Authentication

OAuth 2.1 (Claude, ChatGPT, Cursor, Claude Code): a request without credentials answers 401 with WWW-Authenticate: Bearer resource_metadata="https://hooktrend.com/.well-known/oauth-protected-resource/api/mcp". Authorization server metadata at https://hooktrend.com/.well-known/oauth-authorization-server: dynamic client registration, client ID metadata documents, PKCE S256, refresh tokens with rotation. Tokens are bound to the HookTrend resource (RFC 8707).
API key (n8n, scripts, other agents): Authorization: Bearer <key> or x-api-key: <key>. Create it in Dashboard → Settings → API keys.

Plans, costs and limits

Library tools are free and count toward a daily read cap per team: 25 a day on the free plan, 500 on paid plans, 20 a minute on every plan. The cap resets at 00:00 UTC.
Paid tools quote first: the call without user_approved returns status: "approval_required" with the cost and the balance, and spends nothing. The same call with user_approved: true runs it.
Credits are Hooked credits: 1 credit = $0.03, the same price in the app and the MCP. Failed work is refunded.
Every result carries present_as: a one-line hint for the model on how to show it.

Errors

A failed call returns isError: true and a stable code, a message and the next step:

{
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "The free plan includes 1 research agent and the team already has 1. This team is on the free plan.",
    "fix": "Tell the user once, in one sentence, that this is beyond their plan's limit (plans are managed in their HookTrend account). Do not repeat it. Free alternatives: whats_breaking_out, niche_outliers, find_videos, find_creators, niche_report."
  }
}

Codes: INVALID_INPUT, NOT_FOUND, PLAN_REQUIRED, INSUFFICIENT_CREDITS, RATE_LIMITED, APPROVAL_REQUIRED, UPSTREAM_FAILED, INTERNAL.

Tools

Responses are trimmed. Video ids and numbers are real library captures; hashtag values show the fields, and the agent proposal is an example.

whats_breaking_out

What's breaking out · Free (counts toward the daily read cap)

The videos breaking out right now on TikTok and YouTube, ranked by × usual (views ÷ the creator's usual views), the same as the team's Radar: with research agents, the newest outliers they found; without, the outliers in the niches the team picked on its Radar (source: your_niches, niches lists them); with neither, the whole library. Use for 'what's trending', 'what's going viral this week', 'anything blowing up?' with no specific niche. For one niche use niche_outliers; for a topic that is not a niche use find_videos.

Call

{
  "name": "whats_breaking_out",
  "arguments": {
    "period": "7d",
    "limit": 5
  }
}

structuredContent

{
  "source": "library",
  "period": "7d",
  "count": 5,
  "videos": [
    {
      "id": "cslm4s7c18y0i9i29pfbubtm7",
      "platform": "tiktok",
      "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
      "handle": "seattlehanddoc",
      "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
      "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
      "views": 8689043,
      "usualViews": 421798,
      "xUsual": 20.6,
      "publishedAt": "2026-10-31T13:00:00.000Z",
      "isSlideshow": false
    },
    "…"
  ],
  "present_as": "Lead with one sentence on what the top videos share (hook, format, angle). Then the 3-5 best…"
}

niche_outliers

Outliers in a niche · Free (counts toward the daily read cap)

The outlier videos of one niche (fitness, cooking, personal finance, gaming…), highest × usual first, one per creator. Use for 'what's working in <niche> on TikTok'. The niche is an id from list_niches; when the user's words are not a niche, use find_videos instead.

Call

{
  "name": "niche_outliers",
  "arguments": {
    "niche": "cooking",
    "period": "30d",
    "limit": 10
  }
}

structuredContent

{
  "niche": "cooking",
  "count": 3,
  "videos": [
    {
      "id": "cslm4s7c18y0i9i29pfbubtm7",
      "platform": "tiktok",
      "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
      "handle": "seattlehanddoc",
      "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
      "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
      "views": 8689043,
      "usualViews": 421798,
      "xUsual": 20.6,
      "publishedAt": "2026-10-31T13:00:00.000Z",
      "isSlideshow": false
    },
    "…"
  ],
  "present_as": "Lead with one sentence on what the top videos share (hook, format, angle). Then the 3-5 best…"
}

find_videos

Find videos · Free (counts toward the daily read cap)

Search the library by topic ('protein breakfast', 'ai tools for students', 'skincare routine') and get the matching videos ranked by × usual. Use for any topic, product or keyword question. Set outliers_only to keep only videos at 3× usual or more.

Call

{
  "name": "find_videos",
  "arguments": {
    "query": "cinnamon rolls",
    "platform": "tiktok",
    "outliers_only": true
  }
}

structuredContent

{
  "query": "cinnamon rolls",
  "count": 1,
  "timedOut": false,
  "videos": [
    {
      "id": "cslm4s7c18y0i9i29pfbubtm7",
      "platform": "tiktok",
      "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
      "handle": "sugarspiceddreams",
      "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
      "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
      "views": 8689043,
      "usualViews": 421798,
      "xUsual": 12.6,
      "publishedAt": "2026-10-31T13:00:00.000Z",
      "isSlideshow": false
    }
  ],
  "present_as": "Lead with one sentence on what the top videos share (hook, format, angle). Then the 3-5 best…"
}

find_creators

Find creators · Free (counts toward the daily read cap)

The creators behind a topic's videos, ranked by how many outliers they posted and their best × usual. Use for 'who should I study / collaborate with in <topic>', 'small creators going viral in <topic>'.

Call

{
  "name": "find_creators",
  "arguments": {
    "query": "recipe",
    "limit": 10
  }
}

structuredContent

{
  "query": "recipe",
  "count": 2,
  "creators": [
    {
      "handle": "sugarspiceddreams",
      "platform": "tiktok",
      "followers": 789323,
      "videos": 1,
      "outliers": 1,
      "bestXUsual": 12.6,
      "totalViews": 16565366,
      "url": "https://www.tiktok.com/@sugarspiceddreams"
    },
    "…"
  ],
  "present_as": "A short ranked list: @handle (link), outliers posted, best × usual, followers…"
}

list_niches

List niches · Free (counts toward the daily read cap)

The niches HookTrend follows every day (id, label, description, videos and views in the last 30 days). Call it once to map the user's words to a niche id for niche_outliers or niche_report.

Call

{
  "name": "list_niches",
  "arguments": {}
}

structuredContent

{
  "count": 46,
  "niches": [
    {
      "id": "cooking",
      "label": "Cooking & Baking",
      "description": "Cooking tutorials, recipes, and food content",
      "videos30d": 10,
      "views30d": 50961273
    },
    "…"
  ],
  "present_as": "Internal: map the user's words to a niche id…"
}

niche_report

Niche report · Free (counts toward the daily read cap)

One niche at a glance: its numbers over 30 days, the top outliers, the creators popping, and the hashtags rising in it with their lifecycle. Use for 'give me a report on <niche>', 'what should I post in <niche> this week'.

Call

{
  "name": "niche_report",
  "arguments": {
    "niche": "cooking"
  }
}

structuredContent

{
  "niche": {
    "id": "cooking",
    "label": "Cooking & Baking",
    "videos30d": 10,
    "views30d": 50961273
  },
  "topOutliers": [
    {
      "id": "cslm4s7c18y0i9i29pfbubtm7",
      "platform": "tiktok",
      "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
      "handle": "seattlehanddoc",
      "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
      "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
      "views": 8689043,
      "usualViews": 421798,
      "xUsual": 20.6,
      "publishedAt": "2026-10-31T13:00:00.000Z",
      "isSlideshow": false
    },
    "…"
  ],
  "creators": [
    "…"
  ],
  "hashtags": [
    {
      "name": "<tag without #>",
      "platform": null,
      "lifecycle": "breakout",
      "videosThisWeek": "<n>",
      "growthPct": "<n>",
      "totalViews": "<n>",
      "firstSeenAt": "<ISO date>"
    }
  ],
  "present_as": "Three short blocks: what's breaking out, hashtags to use now, creators to study…"
}

trending_hashtags

Trending hashtags · Free (counts toward the daily read cap)

Hashtags rising overall or in one niche, with lifecycle (ignition → breakout → peak → saturated), videos this week and growth.

Call

{
  "name": "trending_hashtags",
  "arguments": {
    "limit": 15
  }
}

structuredContent

{
  "niche": null,
  "count": 15,
  "hashtags": [
    {
      "name": "<tag without #>",
      "platform": null,
      "lifecycle": "breakout",
      "videosThisWeek": "<n>",
      "growthPct": "<n>"
    },
    "…"
  ],
  "present_as": "List #tag, lifecycle, videos this week, growth…"
}

lookup_creator

Look up a creator · Free when HookTrend already analyzed the account; 8 credits for a fresh analysis (needs user_approved)

Profile and numbers of one TikTok or YouTube account (followers, videos, average views, engagement, top hashtags). Use when the user gives a @handle or a profile link. A saved analysis comes back free; a new one costs credits: the first call returns the quote, call again with user_approved: true once the user agrees.

Call

{
  "name": "lookup_creator",
  "arguments": {
    "handle": "https://www.tiktok.com/@khaby.lame"
  }
}

structuredContent

{
  "status": "approval_required",
  "handle": "khaby.lame",
  "platform": "tiktok",
  "cost": {
    "credits": 8,
    "usd": "$0.24"
  },
  "balance": 612,
  "next": "Call lookup_creator again with the same handle and user_approved: true once the user agrees.",
  "present_as": "Ask the user: analyzing @khaby.lame costs 8 credits ($0.24), balance 612. Wait for yes."
}

create_research_agent

Create a research agent · Proposal free; 15 credits per run (needs user_approved)

Start a research agent: from a one-sentence brief it picks the keywords, searches TikTok and YouTube live, scores every video by × usual and keeps watching on a cadence (once, daily, weekly, monthly). Call it first without user_approved: it answers a proposal (name, keywords, exclude words, cost per run, balance). Show it, let the user edit, then call again with the final keywords and user_approved: true. Use when the library tools are not enough or the user wants ongoing tracking.

Call

{
  "name": "create_research_agent",
  "arguments": {
    "brief": "Spanish home workouts for busy mums",
    "language": "es",
    "regions": [
      "ES",
      "MX"
    ],
    "cadence": "weekly"
  }
}

structuredContent

{
  "status": "approval_required",
  "proposal": {
    "name": "Spanish home workouts for busy mums",
    "cadence": "weekly",
    "platforms": [
      "tiktok",
      "youtube"
    ],
    "keywords": [
      {
        "keyword": "rutina en casa",
        "grade": 96
      },
      {
        "keyword": "ejercicio sin equipo",
        "grade": 90
      },
      "…"
    ],
    "exclude": [
      "gimnasio"
    ]
  },
  "cost": {
    "perRun": {
      "credits": 15,
      "usd": "$0.45"
    },
    "perMonth": {
      "credits": 60,
      "usd": "$1.80",
      "runs": 4
    }
  },
  "balance": 612,
  "next": "Show the proposal. After the user agrees (or edits it), call again with the final keywords… and user_approved: true."
}

list_agents

List research agents · Free

The team's research agents: name, brief, keywords, cadence, last and next run.

Call

{
  "name": "list_agents",
  "arguments": {}
}

structuredContent

{
  "count": 4,
  "agents": [
    {
      "id": "cmwf42gzc002n7ptzi4166ir1",
      "name": "Animals & pets",
      "cadence": "weekly",
      "active": true,
      "keywords": [
        "cute animals",
        "farm life",
        "pet tok"
      ],
      "lastRunAt": "2026-11-12T21:07:50.845Z",
      "url": "https://hooktrend.com/dashboard/trends/agents/cmwf42gzc002n7ptzi4166ir1"
    },
    "…"
  ]
}

get_agent_report

Agent report · Free

One agent's report: totals, the latest run (status, progress), top outliers, hooks that work (the opening line of the top outliers, typed question/claim/pov/list/story/shock), creators and hashtags. A run takes a few minutes; while it is queued or running, say so and offer to check again instead of polling.

Call

{
  "name": "get_agent_report",
  "arguments": {
    "agent_id": "cmwf42gzc002n7ptzi4166ir1"
  }
}

structuredContent

{
  "agent": {
    "name": "Animals & pets",
    "…": "…"
  },
  "kpis": {
    "videos": 11,
    "views": 62635629,
    "outliers": 2,
    "creators": 8
  },
  "latestRun": {
    "status": "completed",
    "progress": 100,
    "outliersFound": 2,
    "creditsCharged": 15
  },
  "topOutliers": [
    "…"
  ],
  "hooks": [
    {
      "videoId": "cslm4s7c18y0i9i29pfbubtm7",
      "text": "POV: your cat learns the treat drawer",
      "type": "pov",
      "source": "transcript",
      "creator": "milo.the.cat",
      "x_usual": 18.2
    },
    "…"
  ],
  "hookTypes": [
    {
      "type": "pov",
      "count": 3,
      "medianXUsual": 14.1
    }
  ],
  "topCreators": [
    "…"
  ]
}

get_agent_data

Agent data · Free

One agent's rows for a view: outliers, videos (newest), creators, hashtags or runs. Use when the user asks for more than the report shows.

Call

{
  "name": "get_agent_data",
  "arguments": {
    "agent_id": "cmwf42gzc002n7ptzi4166ir1",
    "view": "runs",
    "limit": 2
  }
}

structuredContent

{
  "agentId": "cmwf42gzc002n7ptzi4166ir1",
  "view": "runs",
  "total": 1,
  "items": [
    {
      "id": "cmwf42gzg00357ptze2c0o0o7",
      "status": "completed",
      "progress": 100,
      "videosFound": 2,
      "outliersFound": 2,
      "creditsCharged": 15,
      "creditsRefunded": 0
    }
  ]
}

share_agent_report

Share agent report · Free

Turn on the agent's public report link (hooktrend.com/r/...) and return it: a read-only page with the week's outliers, hooks and creators, no login needed, never indexed by search engines. Use when the user wants to send the report to a client or a teammate. enabled: false turns the link off (the old link stops working).

Call

{
  "name": "share_agent_report",
  "arguments": {
    "agent_id": "cmwf42gzc002n7ptzi4166ir1"
  }
}

structuredContent

{
  "status": "shared",
  "url": "https://hooktrend.com/r/animals-pets-k3f9a2",
  "weekOf": "2026-11-16",
  "present_as": "Give the link…"
}

save_video

Save a video · Free

Save a video to the team's Saved list in HookTrend, optionally on a board (a label like 'Client: Bake Co') with a note. Use when the user wants to keep a video to copy later. Pass the id another HookTrend tool returned. Saving twice keeps one entry and updates its board or note.

Call

{
  "name": "save_video",
  "arguments": {
    "video_id": "cslm4s7c18y0i9i29pfbubtm7",
    "board": "Client: Bake Co",
    "note": "Family reaction hook"
  }
}

structuredContent

{
  "status": "saved",
  "video": {
    "id": "cslm4s7c18y0i9i29pfbubtm7",
    "platform": "tiktok",
    "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
    "handle": "seattlehanddoc",
    "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
    "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
    "views": 8689043,
    "usualViews": 421798,
    "xUsual": 20.6,
    "publishedAt": "2026-10-31T13:00:00.000Z",
    "isSlideshow": false
  },
  "board": "Client: Bake Co",
  "created": true,
  "url": "https://hooktrend.com/dashboard/trends/saved?board=Client%3A%20Bake%20Co",
  "present_as": "Say it is saved…"
}

list_saved

List saved videos · Free

The team's saved videos, newest first, with their board and note, plus the boards and how many videos each holds. Filter by one board. Use for 'what did I save', 'my saved videos for client X'.

Call

{
  "name": "list_saved",
  "arguments": {
    "board": "Client: Bake Co",
    "limit": 5
  }
}

structuredContent

{
  "count": 1,
  "total": 9,
  "boards": [
    {
      "name": "Client: Bake Co",
      "count": 3
    },
    {
      "name": "Client: PawBox",
      "count": 2
    }
  ],
  "videos": [
    {
      "video": {
        "id": "cslm4s7c18y0i9i29pfbubtm7",
        "platform": "tiktok",
        "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
        "handle": "seattlehanddoc",
        "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
        "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
        "views": 8689043,
        "usualViews": 421798,
        "xUsual": 20.6,
        "publishedAt": "2026-10-31T13:00:00.000Z",
        "isSlideshow": false
      },
      "board": "Client: Bake Co",
      "note": "Family reaction hook",
      "savedAt": "2026-11-16T09:12:00.000Z"
    }
  ],
  "url": "https://hooktrend.com/dashboard/trends/saved",
  "present_as": "One line per video…"
}

follow_creator

Follow a creator · Free

Follow a TikTok or YouTube creator for the team: every night HookTrend checks their new videos and alerts the team (in the app, a daily email and the creator.outlier webhook) when one reaches 3× their usual views. The creator must already be in the library (find_creators or lookup_creator first). Plans follow 1 (Free), 25 (Starter) or 100 (Pro) creators. unfollow: true stops following.

Call

{
  "name": "follow_creator",
  "arguments": {
    "platform": "tiktok",
    "handle": "@seattlehanddoc"
  }
}

structuredContent

{
  "platform": "tiktok",
  "creatorUsername": "seattlehanddoc",
  "status": "following",
  "following": 4,
  "limit": 25,
  "url": "https://hooktrend.com/dashboard/trends/saved?tab=creators",
  "present_as": "Say the team now follows…"
}

list_followed_creators

List followed creators · Free

The creators the team follows, with their usual views, when they were last checked, how many new alerts each has and their latest outliers (videos at 3× usual or more). Use for 'who am I following', 'did any of my competitors break out'.

Call

{
  "name": "list_followed_creators",
  "arguments": {}
}

structuredContent

{
  "count": 1,
  "creators": [
    {
      "platform": "tiktok",
      "creatorUsername": "seattlehanddoc",
      "alertThreshold": 3,
      "usualViews": 423000,
      "followers": 1200000,
      "lastCheckedAt": "2026-11-17T06:31:00.000Z",
      "unseenAlerts": 1,
      "latestOutliers": [
        {
          "id": "cslm4s7c18y0i9i29pfbubtm7",
          "platform": "tiktok",
          "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
          "handle": "seattlehanddoc",
          "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
          "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
          "views": 8689043,
          "usualViews": 421798,
          "xUsual": 20.6,
          "publishedAt": "2026-10-31T13:00:00.000Z",
          "isSlideshow": false
        }
      ],
      "profileUrl": "https://hooktrend.com/dashboard/trends/creators/tiktok/seattlehanddoc"
    }
  ],
  "limit": 25,
  "unseenAlerts": 1,
  "url": "https://hooktrend.com/dashboard/trends/saved?tab=creators",
  "present_as": "One line per creator…"
}

show_outliers

Show outlier cards · Free

Render videos as outlier cards in the chat (cover, × usual, views vs usual, @handle, Open on TikTok/YouTube). Pass the video ids another tool returned. In clients without apps it answers markdown cards.

Call

{
  "name": "show_outliers",
  "arguments": {
    "video_ids": [
      "cslm4s7c18y0i9i29pfbubtm7"
    ],
    "title": "Cooking · this month"
  }
}

structuredContent

{
  "title": "Cooking · this month",
  "count": 1,
  "videos": [
    {
      "id": "cslm4s7c18y0i9i29pfbubtm7",
      "platform": "tiktok",
      "title": "When our son decided to come home from college for the weekend, we knew exactly what to make him!…",
      "handle": "seattlehanddoc",
      "url": "https://www.tiktok.com/@seattlehanddoc/video/7702945263173864735",
      "coverUrl": "https://media.hooked.so/social/tiktok/thumbnails/….jpeg",
      "views": 8689043,
      "usualViews": 421798,
      "xUsual": 20.6,
      "publishedAt": "2026-10-31T13:00:00.000Z",
      "isSlideshow": false
    }
  ],
  "present_as": "The cards are on screen…"
}

get_balance

Balance and plan · Free

The team's plan (free, starter or pro), its monthly plan credits left and when they reset, Hooked credits, research agents, the daily read cap and how much of it is used.

Call

{
  "name": "get_balance",
  "arguments": {}
}

structuredContent

{
  "team": "Demo team",
  "plan": "trends",
  "credits": 612,
  "agents": 4,
  "limits": {
    "readsPerDay": 500,
    "readsUsedToday": 3
  },
  "costs": {
    "researchAgentRun": 15,
    "creatorLookup": 8
  }
}

estimate_cost

Estimate cost · Free

What an action costs before doing it (credits and dollars) and whether the balance covers it: research agent runs (by cadence, per month), creator lookups, library reads.

Call

{
  "name": "estimate_cost",
  "arguments": {
    "action": "research_agent",
    "cadence": "weekly",
    "agents": 2
  }
}

structuredContent

{
  "action": "research_agent",
  "cadence": "weekly",
  "agents": 2,
  "perRun": {
    "credits": 15,
    "usd": "$0.45"
  },
  "perMonth": {
    "credits": 120,
    "usd": "$3.60"
  },
  "balance": 612,
  "covered": true,
  "plan": "trends"
}