Hooklayer

Official8 tools

by khan-ashifur

Viral-content intelligence for AI agents — 7 read-only MCP tools, evidence-layer scoring.

Content intelligence tool for AI agents analyzing viral content with evidence-based scoring.

Captured live from the server via tools/list.

analyze_account

Deep intelligence on a TikTok or YouTube creator by handle. Returns viral DNA scores (viral_dna_score, replicability_score, originality_score, consistency_score, audience_fatigue), format fingerprint, top 5 recent videos with metadata (and transcripts on TikTok), content gaps, AND a `recommended_chain` field with pre-filled next tool calls. USE WHEN the user references a creator by @handle, asks "analyze X", wants competitor research, or needs creator context before generating content. The recommended_chain suggests which tools to call next (match_voice, trend_pulse, viral_remix) with parameters pre-filled — review and execute them as appropriate. Supports platform: "tiktok" (default, full transcript extraction) and "youtube" (channel Shorts analysis; transcript extraction lands in v1.1, current YouTube responses surface a partial-data flag noting this). Costs 5 credits. 1-hour cache per (handle, platform). TOOL HEALTH: Every response includes a `quality` field with a level (full | partial | degraded) and a reason. If quality.level is partial or degraded, you MUST flag this to the user explicitly in chat (e.g. "Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface viral_dna.viral_dna_signals, viral_dna.replicability_signals, viral_dna.originality_signals (each as bullet lists with the cited evidence string verbatim) AND viral_dna.would_fail_because verbatim AND provenance.video_post_dates so the user can see freshness. Never hide the evidence array behind a paraphrase — these are the auditability layer.

Parameters (5)

handlestringrequired
Creator handle (with or without @ prefix) or YouTube channel ID. Examples: "@mrbeast", "mrbeast", "UCX6OQ3DkcsbYNE6H8uQQuVA".
platformstring
Platform to analyze. "tiktok" (default) returns full pipeline with transcripts. "youtube" analyzes the channel's recent Shorts via YouTube Data API + Innertube caption extraction (v1.1, 2026-06-10) — videos with captions disabled or geoblocked resolve to transcript: null and the response flags how many were extracted. Instagram ships in v1.2.
sincestring
Optional ISO date (e.g. "2026-04-01"). Filter the candidate video pool to those posted on/after this date. Useful when the user asks "show me what they've done THIS month" — the route returns honest empty + warning when the filter matches 0, no credits charged. Use either `since` or `window`, not both.
windowstring
Recency sugar — same effect as `since` but takes a friendlier bucket. Maps to a since-cutoff at request time. Use either `since` or `window`, not both.
recent_onlyboolean
When true, hard-cap the candidate pool to videos posted in the last 90 days. Stricter than `window=90d` because it never falls through to archival data on a thin recent corpus.

score_hook

Score a TikTok/Reels/Shorts hook against proven viral patterns. Returns a 0-100 score, percentile rank, matched viral pattern, three rewritten versions at higher quality, a one-sentence verdict naming the closest calibration anchor (10/30/50/70/85/95), a 6-element signals[] array with evidence per sub-score, and a would_fail_because counterfactual. USE WHEN the user has a draft hook to validate, wants to A/B between alternatives, or needs to catch AI-generated slop before publishing. Pairs after viral_remix to verify the generated hook. Costs 1 credit. TOOL HEALTH: Every response includes a `quality: { level: "full" | "partial" | "degraded", reason?: string }` field. If quality.level is "partial" or "degraded", you MUST flag this to the user explicitly in chat ("Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface (a) the score paired with the closest anchor from the why field, (b) the signals[] array as a bullet list with each evidence string verbatim — never paraphrase or drop signals, and (c) the would_fail_because field verbatim. If you score multiple hooks in sequence, also explicitly compare their signals[], not just the numeric scores — that's how the user judges which one wins.

Parameters (3)

textstringrequired
The hook to score (3-200 chars typical)
platformstringrequired
Target platform — affects pattern matching
nichestring
Optional niche context (e.g. "Beauty & Skincare", "Finance & Business")

viral_remix

Take a viral source video and produce a fresh script that mirrors its viral DNA — same scene structure, same energy pattern, different topic. Returns the extracted formula, scene-by-scene script, camera shots, text overlays, and a `verify_hook` block prompting you to score the generated hook via score_hook. USE WHEN the user finds a video they want to copy the structure of, or chained from analyze_account.recommended_chain. Pass EITHER source_url (auto-extracts transcript) OR transcript directly — one is required. Costs 3 credits. NO SELF-RATING: viral_remix deliberately does NOT return a self-rated hook score. The script generator rating its own hook is structurally invalid (cardinal coupling). After every viral_remix call, you MUST call score_hook with the verify_hook.hook_text to get a structurally-independent quality signal before reporting to the user. Skipping this step is hiding the self-grading loop.

Parameters (4)

source_urlstring
TikTok/YouTube/Instagram URL — transcript will be auto-extracted
transcriptstring
Pre-extracted transcript (alternative to source_url, faster)
my_topicstring
What the remix should be about. Default: same niche as original.
nichestring
Optional niche hint

trend_pulse

Surface what is actually peaking in short-form video right now for a niche. Returns 3 rising opportunities (format/hook/style/topic) with QUALITATIVE growth labels (e.g. "Rising", "Early signal", "Accelerating"), per-entry signal_strength (0-1, the QUANTITATIVE anchor), sources[] (Google Trends + YouTube velocity + Reddit hot + internal corpus), signal_window, plus 2 saturated patterns to avoid AND top-level provenance with cache_age_hours and cache_status. USE WHEN the user asks "what should I post about", "what's trending in [niche]", or before generating content for the first time. Pairs after analyze_account to validate a creator's formula against current trends. Costs 1 credit. 12-hour cache per niche. TOOL HEALTH: Every response includes a `quality: { level: "full" | "partial" | "degraded", reason?: string }` field. If quality.level is "partial" or "degraded", you MUST flag this to the user explicitly in chat ("Heads up — this call returned partial data: <reason>") before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST cite the data_sources array verbatim and surface cache_status (fresh|stale) — the user needs to know if they're looking at live data. For each rising/saturated entry, cite the growth label and the signal_strength numeric anchor verbatim — DO NOT FABRICATE NUMERIC GROWTH PERCENTAGES. The upstream pipeline deliberately does not compute "+178.4%"-style growth rates (no ground-truth dataset supports it); if you see a numeric percentage in the response it came from upstream LLM hallucination, not the tool. Cite the qualitative label as written.

Parameters (2)

nichestring
One of the 17 supported niches. Loose names like "travel" or "fitness" are accepted but pass the canonical form when possible. Omit for broadly applicable trends.
regionstring
Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to Google Trends geo + YouTube regionCode. Defaults to US when omitted. Reddit signals are global and ignore this param.

find_viral_template

Find proven viral templates in a niche with example videos. Returns niche-fit ranked templates with hook pattern, format structure, average views, and example URLs. USE WHEN the user asks "what's working in [niche]", "give me templates I can copy", or wants concrete copyable structures rather than abstract trends. Pairs with viral_remix for end-to-end script generation. Costs 1 credit. Short niche names like "travel" or "fitness" are auto-mapped to canonical names — but passing the canonical name from the enum below is fastest.

Parameters (4)

nichestringrequired
One of the 17 supported niches. Loose names like "travel" or "fitness" are accepted but pass the canonical form when possible.
min_viewsinteger
Optional filter — only return examples above this view count
windowstring
Recency filter. Drops example videos older than the window. Note: TikTok hashtag-corpus rows often lack timestamps and are excluded when window is set — surfaces as a quality warning so callers can decide whether to broaden.
regionstring
Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to YouTube Search regionCode + TikTok niche query. Reddit niche signals are global and ignore this param. Pass when the user wants templates that resonate with a specific local audience.

search_videos

Keyword search across the live TikTok corpus. Returns up to 20 videos matching a free-text query, ranked by engagement, with view/like/share/save/comment counts, hashtags, posted_at, author handle, and source URL. Optional filters: niche (drops videos whose description does not contain niche tokens), min_views, window ("24h"|"7d"|"30d"|"this-month"), and region (ISO country code: US, GB, BR, PH, JP, etc.). USE WHEN the user asks "find videos about X", "what is going viral with the keyword Y", or needs raw video discovery instead of niche-aggregated templates. Differs from find_viral_template: that one returns templates inferred from a niche; this one returns the raw video board for any query. Differs from trend_pulse: that one returns trending TOPICS; this one returns actual VIDEOS for a known query. Chain into viral_remix on any returned URL for a fresh script. Costs 2 credits. TOOL HEALTH: response includes a quality field (level: full | partial | degraded, plus reason). If level is partial or degraded, flag the reason verbatim to the user before reporting results. Zero-result responses come back with a warning AND no credits charged — surface the warning so the user can broaden their query.

Parameters (6)

querystringrequired
Free-text search term. Examples: "morning routine", "iphone case", "passive income".
nichestring
Optional — only return videos whose description contains niche-related tokens. Loose niche strings work ("fitness", "Beauty & Skincare").
min_viewsinteger
Optional view-count floor. Default 0.
windowstring
Recency filter. Maps to the closest ScrapeCreators date bucket AND applies a client-side cutoff for defense-in-depth.
regionstring
ISO country code (US, GB, BR, PH, JP, etc.). Note: corpus coverage varies by region — small regions may return zero results and a degraded quality flag.
limitinteger
Max videos to return after filtering. Default 12, max 20.

match_voice

Extract a creator's voice DNA from 3+ reference samples (URLs or text) and rewrite a draft in their voice. Returns voice profile (energy, humor, vocabulary, signature moves), reusable prompt instructions, the rewritten draft, AND a deterministic voice_metrics block: vocab_diversity_ttr (type-token ratio), filler_rate_per_100_words, avg_sentence_length_words, total_words, and signature_phrases[] (top 5 recurring 2-3-grams with counts). USE WHEN the user wants to write in another creator's style, has reference content to match, or chained from analyze_account.recommended_chain (which pre-fills reference_samples from the analyzed creator's videos). Costs 2 credits. TOOL HEALTH: Every response includes a quality field (level: full | partial | degraded, plus a reason string). If quality.level is partial or degraded, you MUST flag this to the user explicitly in chat ('Heads up — this call returned partial data: <reason>') before reporting any results. Never silently route around a degraded response. REPORTING: When you summarize this in chat, you MUST surface the voice_metrics block as numbers — TTR, filler rate, avg sentence length, and the top signature_phrases with their counts. The qualitative voice_profile labels (energy, personality) alone are vibes; the numeric metrics are the reproducible signature. Cite both.

Parameters (2)

draftstringrequired
The text to rewrite
reference_samplesarrayrequired
At least 3 reference samples — TikTok/YouTube/Instagram URLs or raw text

predict_virality

Score a draft script for viral potential with a mitigation-aware adversarial second-pass. Returns optimistic_score (upstream self-grade), virality_score (adversarial headline), calibration_gap (disagreement between them), vectors_summary (counts of present vs mitigated attack vectors), recommendation ({verdict: SHIP|REWORK|NO-GO, reason}), score_range, viral DNA breakdown, signals[] with evidence, would_fail_because, calibration_check, and attack_vectors[] each tagged status: present|mitigated. USE WHEN the user has a finished draft and wants pre-publish verification, or chained after viral_remix to validate the generated script. Pass either a script string or a video URL. Costs 2 credits. TOOL HEALTH: response includes a quality field (level: full | partial | degraded, plus reason). If level is partial or degraded, flag it in chat before reporting. Never silently route around degraded data. REPORTING (v1.1.1 reframe — calibration gap is the value proposition, not a deficiency): lead with the recommendation.verdict and reason in plain language. Then frame the calibration_gap explicitly: "Every other AI scoring tool ships the OPTIMISTIC value of X without checking. The adversarial pass disagrees by GAP points and lands at VIRALITY_SCORE." Then surface vectors_summary as "X total, Y mitigated by the script, Z still present" and enumerate each PRESENT vector with severity + mitigation hint. Surface would_fail_because and signals[] last. NEVER report optimistic_score alone (recreates the self-grading loop). NEVER apologize for the adversarial number being lower — the gap IS the value. A 24-point gap means the check is doing its job; a 0-point gap means the check is rubber-stamping and worthless.

Parameters (2)

scriptstringrequired
The draft script to predict on (or a video URL — auto-extracts transcript)
nichestring
Niche context

README.md10 KBView on GitHub

Hooklayer MCP

Viral-content intelligence for AI agents. Drop the Hooklayer MCP server into Claude Desktop, Cursor, n8n, or any HTTP MCP client and your agent gets 7 read-only tools for scoring hooks, remixing viral videos, surfacing live trends, and analyzing TikTok creators. The flagship analyze_account tool includes a recommended_chain field with suggested follow-up calls the agent can review and execute.

code

7 read-only tools · all return structured JSON · no mutations · no side effects

v1.1.0 (2026-05-14): The evidence layer ships. Every score includes signals[] with cited evidence, a would_fail_because counterfactual, and a quality health field. predict_virality runs an independent adversarial check. analyze_account.recommended_chain steps now expose confidence, cost, action_class (authority taxonomy), and expected_output. See CHANGELOG.md for the full ship.

🚀 Quick install

Claude Desktop

Claude Desktop doesn't natively support remote HTTP MCP servers — it needs the mcp-remote bridge. Two ways to install:

Option 1 — Custom Connector (easiest, no config file edit)

In Claude's web/desktop UI: Settings → Connectors → Add custom connector → paste this URL:

code

https://hooklayer.dev/api/mcp

Claude.ai will walk you through OAuth (no manual key paste). Done.

Option 2 — Direct config (for power users who want hl_live_ key auth)

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "hooklayer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://hooklayer.dev/api/mcp",
        "--header",
        "Authorization:Bearer hl_live_..."
      ]
    }
  }
}

Get your free hl_live_ key at https://hooklayer.dev/auth/signup — 100 lifetime credits, no card required.

Restart Claude Desktop. The 7 Hooklayer tools appear in the 🔌 connector list.

Cursor

~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "hooklayer": {
      "url": "https://hooklayer.dev/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer hl_live_..."
      }
    }
  }
}

n8n

In your workflow, add an MCP Client node and configure as a remote HTTP MCP server:

URL: https://hooklayer.dev/api/mcp
Transport: HTTP
Header: Authorization: Bearer hl_live_...

All 7 tools appear in the node's "Tool" dropdown.

OAuth 2.1 + PKCE (for Claude.ai connector + custom apps)

Hooklayer is fully OAuth 2.1 compliant — discovery, Dynamic Client Registration, PKCE, refresh token rotation. MCP clients that prefer OAuth over API keys work out of the box.

Discovery endpoints (no auth required, machine-readable):

bash

# Authorization server metadata (RFC 8414)
curl https://hooklayer.dev/.well-known/oauth-authorization-server

# Protected resource metadata (RFC 9728)
curl https://hooklayer.dev/.well-known/oauth-protected-resource

Dynamic Client Registration (create a client without a manual signup form):

bash

curl -X POST https://hooklayer.dev/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Your MCP client",
    "redirect_uris": ["https://yourapp.com/oauth/callback"]
  }'
# Returns: client_id, client_secret (for confidential clients)

Hitting tools/call without auth returns 401 plus a WWW-Authenticate header pointing at the resource metadata — Claude.ai, Cursor, and other MCP clients use this to auto-discover the OAuth flow.

Other clients

Any HTTP MCP client. Protocol negotiates 2024-11-05 (broadest compat) or 2025-06-18 (Streamable HTTP + structuredContent).

bash

# Quick test — initialize handshake works without auth:
curl -X POST https://hooklayer.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

🧠 The 7 tools

Tool	Credits	What it does
`analyze_account`	5	TikTok creator deep dive: viral DNA scores, format fingerprint, top 5 videos, content gaps, `recommended_chain` with suggested follow-up tools.
`score_hook`	1	Score any hook 0-100 against proven viral patterns. Returns 3 rewrites at higher quality.
`viral_remix`	3	URL or transcript → fresh script with mirrored viral DNA. Scene-by-scene with camera shots.
`trend_pulse`	1	Real-time rising opportunities + saturated patterns per niche. 12-hour cache.
`find_viral_template`	1	Niche-fit ranked templates with hook patterns + example URLs.
`match_voice`	2	Extract a creator's voice DNA from 3+ samples, rewrite a draft in their style.
`predict_virality`	2	Score a draft script for viral potential before publishing. Retention diagnosis.

Full schemas + curl examples: https://hooklayer.dev/docs

💡 The recommended-chain pattern

analyze_account returns a recommended_chain field with suggested follow-up tools and pre-filled parameters. The agent decides whether and when to execute them:

json

{
  "viral_dna_score": 87,
  "steal_map": [...],
  "recommended_chain": [
    {
      "tool": "match_voice",
      "params": {
        "draft": "<<<USER_DRAFT>>>",
        "reference_samples": ["https://tiktok.com/...", "...", "..."]
      },
      "reason": "High-signal voice DNA — consistent across top 5 videos"
    },
    {
      "tool": "trend_pulse",
      "params": { "niche": "challenge_videos" },
      "reason": "Verify their formula maps to current trends"
    },
    {
      "tool": "viral_remix",
      "params": { "source_url": "https://tiktok.com/..." },
      "reason": "Their #2 video has the highest copyable structure"
    }
  ]
}

The agent can review these suggestions and call the recommended tools if appropriate. Each tool still requires explicit invocation — nothing runs automatically without agent/user consent.

📦 Examples

examples/typescript-example.ts — TypeScript usage via the MCP SDK
examples/python-example.py — Python usage via anthropic-mcp client
examples/curl-test.sh — Raw curl tests for every endpoint

💵 Pricing

Free — 100 lifetime credits at signup, no card
Starter — $49/month, 5,000 credits, 60 req/min
Pro — $149/month, 25,000 credits, 300 req/min, brand voice memory
Agency — $499/month, 150,000 credits, 1,000 req/min, white-label, 10 seats
Pay-as-you-go — $25 for 5,000 credits, never expire

Full pricing: https://hooklayer.dev/pricing

🛠 Architecture

Hosted MCP server (no stdio install needed):

code

Your agent (Claude/Cursor/n8n)
        │
        │  JSON-RPC 2.0 over HTTP
        ▼
https://hooklayer.dev/api/mcp
        │
        ├── initialize / ping / tools/list  (no auth)
        └── tools/call                       (Bearer hl_live_*)
                │
                └── Routes internally to /v1/* REST endpoints
                    100K+ analyzed viral videos
                    ScrapeCreators + Whisper + Sonnet pipeline

Source code for the hosted server lives at hooklayer.dev (closed source — the analysis pipeline is the moat). This repo holds the public client docs, examples, and config snippets.

📚 Links

Install page: https://hooklayer.dev/mcp
Full docs: https://hooklayer.dev/docs
Playground (no signup): https://hooklayer.dev/playground
Pricing: https://hooklayer.dev/pricing
OAuth metadata: /.well-known/oauth-authorization-server
Issues + bug reports: GitHub Issues

🔒 Security

All 7 tools are read-only. They analyze, score, and generate content — none of them create, modify, or delete any user data, accounts, or external resources. Every tool carries readOnlyHint: true and destructiveHint: false in its MCP annotations.

Authentication: tools/call requires a Bearer token (hl_live_* API key or OAuth 2.1 access token). Public methods (initialize, ping, tools/list) work without auth so MCP clients can handshake and discover tools before authentication.

recommended_chain is advisory only. The analyze_account response includes suggested follow-up tools with pre-filled parameters. These are data — the agent and user decide whether to execute them. No tool call ever triggers additional tool calls server-side.

Data handling: Hooklayer processes the inputs you send (handles, hooks, scripts, URLs) to return analysis results. We do not store your content beyond the request lifecycle except for anonymous usage metrics.

To report a security issue: GitHub Issues or email security@hooklayer.dev.

📄 License

MIT — see LICENSE.

The MCP client examples and config snippets in this repo are MIT. The hosted Hooklayer service at hooklayer.dev is a commercial product with the pricing tiers listed above.

Install

Tools (8)

analyze_accountscore_hookviral_remixtrend_pulsefind_viral_templatesearch_videosmatch_voicepredict_virality

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://hooklayer.dev/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hooklayer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hooklayer.dev/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.