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 and sounds are rising, or start a research agent that searches a brief's keywords live and keeps watching.

Server: https://staging.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://staging.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://staging.hooktrend.com/.well-known/oauth-protected-resource/api/mcp". Authorization server metadata at https://staging.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": "Research agents is part of the paid HookTrend plans (Starter $29/month, Pro $99/month). This team is on the free plan.",
    "fix": "Tell the user once, and offer https://hooktrend.com/#pricing. 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; sound and 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). With research agents, the newest outliers they found; without, 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 sounds and 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": [
    "…"
  ],
  "sounds": [
    {
      "name": "<title · artist>",
      "platform": "tiktok",
      "lifecycle": "breakout",
      "videosThisWeek": "<n>",
      "growthPct": "<n>",
      "totalViews": "<n>",
      "firstSeenAt": "<ISO date>"
    }
  ],
  "hashtags": [
    "…"
  ],
  "present_as": "Three short blocks: what's breaking out, sounds and hashtags to use now, creators to study…"
}

trending_sounds

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

Sounds rising on TikTok and YouTube Shorts, overall or in one niche, each with its lifecycle (ignition → breakout → peak → saturated), videos this week and growth. Recommend ignition and breakout sounds; warn that saturated ones are late.

Call

{
  "name": "trending_sounds",
  "arguments": {
    "niche": "fitness",
    "limit": 10
  }
}

structuredContent

{
  "niche": "fitness",
  "count": 10,
  "sounds": [
    {
      "name": "<title · artist>",
      "platform": "tiktok",
      "lifecycle": "ignition",
      "videosThisWeek": "<n>",
      "growthPct": "<n>"
    },
    "…"
  ],
  "present_as": "List name, lifecycle, videos this week, growth…"
}

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, creators, sounds 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,
    "sounds": 2
  },
  "latestRun": {
    "status": "completed",
    "progress": 100,
    "outliersFound": 2,
    "creditsCharged": 15
  },
  "topOutliers": [
    "…"
  ],
  "topCreators": [
    "…"
  ]
}

get_agent_data

Agent data · Free

One agent's rows for a view: outliers, videos (newest), creators, hashtags, sounds 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
    }
  ]
}

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, and the upgrade link.

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"
}