MCP server

Let your AI assistant use Virlo for you. Ask Claude, Cursor, or another assistant to research a niche or find trending sounds, and it fetches the data itself.

Quick setup

Pick your app's tab. If it uses an API key, paste the key first so the setup code includes it. Cursor then gets a one-click install button.

{
  "mcpServers": {
    "virlo": {
      "url": "https://dev.virlo.ai/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer virlo_tkn_YOUR_KEY"
      }
    }
  }
}

Any other MCP app

Any app that supports remote MCP servers can connect with:

If your app supports MCP sign-in (OAuth), skip the header and sign in. If it only runs local servers, use the mcp-remote bridge on the Windsurf and Codex tabs.

If something goes wrong

• Connected, but every tool says "Invalid or inactive API key". Setup only checks the virlo_tkn_ prefix. The real check comes on the first call. Copy the key again from your dashboard.
• Paid tools fail with error 402, free ones work. Your balance is too low. Add funds on the Billing page.
• A filter does nothing. Tools silently ignore settings they don't know, such as a misspelled name. Ask the assistant which settings it sent.

Content Research Agents

A Content Research Agent collects and analyzes short-form videos on a topic you describe. It runs once, or on a daily, weekly, or monthly cadence. Each collection is a run.

For historical reasons, one-time agent tools say "keyword search" and recurring ones say "niche monitor". Both create Content Research Agents.

Getting good results from an agent

1. Describe the goal in one sentence. This intent is required. Say who it's for and what you want to learn, like "beginner skincare routines that name drugstore products." See the Intent cookbook.
2. Get free keywords from suggest_keywords: usually 7 to 12 phrases, plus words to exclude. If it flags the intent as weak, sharpen it.
3. Start the agent with the same intent and both lists (up to 50 keywords, same price).
4. Wait for finalized: true, then read data_type: "summary" first.

Reading results is free. Ask to filter by views, dates, platform, sort order, or country (beta).

Data Intelligence (+$1.00 per run): AI tags collected videos with 79 details (70 for slideshows), such as hook, format, and tone. Turn it on when you start the agent (data_intelligence_enabled: true), or later with update_niche_monitor. It never applies to past runs. See Data Intelligence.

Available tools

Prices are per call.

Topic Trends and hashtags (instant)

• search_hashtags ($0.05): top hashtags by uses or views.
• get_hashtag_performance ($0.05): views, likes, and comments for one hashtag.
• get_trending_videos ($0.25): the most-viewed videos from the last 48 hours.
• get_trends ($0.25): Topic Trends, news and pop culture topics with example videos, by date and region.
• get_trends_digest ($0.25): today's Topic Trends list for a region.
• get_emerging_trends ($0.25): new and rising topic trends ranked by momentum.

Trend regions are global (the default), us, gb, au, and sg.

Format Trends

Video formats creators are copying right now, reviewed by the Virlo team before they are published. Topic Trends above are subjects people talk about; Format Trends are video formats you can make yourself. get_content_trends returns Format Trends. See Format Trends.

• get_content_trends ($0.25): the published formats, live ones by default, with filters for stage, platform, client type, and brand safety.
• get_content_trend ($0.05): one format with all its example videos and its 30-day history.

One-time agents

• suggest_keywords (free): turns an intent into graded keywords and exclude words. Creates nothing.
• search_keywords ($0.50, or $1.50 with Data Intelligence): starts a one-time agent. Needs intent.
• list_keyword_searches (free): lists them.
• get_keyword_search_results (free): reads results by data_type: status (the default), summary, videos, slideshows, ads, outliers, analysis, trends, or sounds.

Outliers are creators whose videos get far more views than their follower count predicts.

Recurring agents

• create_niche_monitor ($0.50 per run, or $1.50 with Data Intelligence): runs daily, weekly, or monthly. Needs intent. The first run starts right away and is billed.
• list_niche_monitors (free): lists them.
• get_niche_monitor_data (free): reads results. Uses overview (the default) instead of status, and adds hashtags, benchmarks, affinity (related topics, beta), and similar (look-alike creators, beta).
• update_niche_monitor (free): changes settings. is_active: false pauses the agent, and true resumes it.
• delete_niche_monitor (free): deletes the agent for good and stops billing. It drops off your list, but past results stay readable by ID, so save it. To stop for a while, pause instead.
• set_niche_monitor_autonomy (free): turns autopilot on or off with autopilot: true or false.
• get_niche_monitor_activity (free): the change log. What the agent noticed, what autopilot changed, and why.
• get_niche_monitor_events (free): breaking stories in the niche, scored 0 to 10.
• get_niche_monitor_proposals and review_niche_monitor_proposal (free, deprecated): list and act on suggested changes. Autopilot now applies changes itself, so read the activity log instead.

Creator, video, sound, and hashtag lookups

A lookup is a one-time deep dive on one creator, video, sound, or hashtag, saved as a run you can re-read for free. Tool names say satellite, the internal name for lookups.

• lookup_creator ($0.50, up to $1.75): profile, recent videos, and top performers. Add-ons: trend_analysis (+$0.50), data_intelligence (+$0.25), and audience data (+$0.50).
• batch_lookup_creators ($0.50 per creator, free if looked up in the last 6 hours with at least the same options): up to 25 creators at once.
• analyze_video ($0.50): how far one video beat the creator's usual numbers.
• lookup_sound ($0.50, or $1.00 with trend analysis): up to 100 videos using a TikTok or Instagram sound, or about 300 with trend analysis. Takes the sound's music_id (the number at the end of its link) or a Virlo sound ID.
• lookup_hashtag ($0.50, up to $2.50 with more videos and trend analysis): videos and stats for a TikTok, Instagram, or YouTube hashtag. Repeats within 6 hours are free.
• get_satellite_run (free): re-reads a past lookup by run_id. Each paid lookup has its own run, so older ones stay.
• list_satellite_runs (free): past lookups. Check here before paying again.

Tracking

Tracking checks a creator or video on a schedule (daily by default, from every 6 hours to monthly) and writes a short AI report.

• track_creator and track_video ($0.25 per check): start tracking. collection_depth also pulls a creator's older posts once, for $0.50 to $2.00.
• list_tracked_items (free): what you track.
• get_tracking_report (free): the latest AI report and snapshots.
• get_tracking_signals (free): alerts such as outlier videos and follower spikes.
• list_creator_posts (free): a tracked creator's posts and the sounds used.
• collect_creator_posts ($0.50, $1.00, or $2.00): pulls up to 50, 200, or 500 more posts now. Refunded if it finds none.
• get_posting_cadence (free): how often, and on which days, the creator posts.
• update_tracking_settings (free): pauses, resumes, or changes how often it checks. Paused items stay listed and stop costing.
• untrack_creator and untrack_video (free): stop tracking. Tracking a creator again restores the history. A video can't be tracked again.

Audience

Audience data describes who comments on a creator's videos: age, gender, language, and location. It covers creators you track. For others, add it to lookup_creator.

• refresh_creator_audience ($0.50): makes a new snapshot, or returns one under 30 days old, or one still being made, for free. Refunded if data is too thin.
• get_creator_audience_demographics (free): age, gender, and language.
• get_creator_audience_geography (free): top countries and cities.

Sounds

• get_trending_sounds ($0.25): sounds used in the most new videos in the last 7 days.
• get_breakout_sounds ($0.25): the fastest-growing sounds from a small start.
• search_sounds ($0.10): title search. Spelling must match; case doesn't.
• get_sound_details ($0.05): details and totals. resolve: true finds the original song for $0.10 more, the first time only.
• get_sound_videos ($0.25): videos using a sound, by views or date.
• get_sound_usage_history ($0.05): a daily snapshot of the sound's total use count and its daily growth.
• get_creator_sounds ($0.25): sounds a creator owns, and how many others use them.

get_sound_details, get_sound_videos, and get_sound_usage_history take Virlo's sound ID from search_sounds or get_trending_sounds. Agent-collected sounds are free with data_type: "sounds".

Hooks

A hook is a video's opening line or shot. They're ranked by Virality Score: how far a video beat its creator's follower count. See Hooks.

• get_trending_hooks ($0.25): the best opening lines right now, with source videos.
• search_hooks ($0.25): finds hooks by phrase or type.
• get_hook_types (free): which hook styles win most often.
• get_hook_library ($0.10): fill-in-the-blank hook templates.
• get_agent_hooks ($0.25, free with Data Intelligence or while the agent has no hooks): top hooks from your agent. Without Data Intelligence there are few or none, so use get_trending_hooks.

Raw data

Live, unprocessed data from the platform, with the same fields on TikTok, YouTube Shorts, and Instagram Reels. Each call costs $0.01, even when it finds nothing. See Raw data.

• raw_search: videos for a keyword.
• raw_hashtag: videos under a hashtag.
• raw_video: one video's details and counts right now.
• raw_comments: a video's comments.
• raw_transcript: what is said in a TikTok or YouTube video.
• raw_creator: a creator's profile and counts right now.
• raw_creator_videos: a creator's videos.

Lists come one page per call. To get the next page, the assistant passes the next_cursor it got back as cursor, and each page is charged.

Job status and balance

• check_job_status (free): checks any background job.
• get_credit_balance (free): your balance in dollars and credits (1 credit = $0.01), plus prices.
• build_virlo_skill (free, no API call): writes a personal Virlo skill file (SKILL.md) from what the assistant knows about you, with install steps for Claude, ChatGPT, Cursor and Claude Code.

Long-running jobs

Agents, lookups, post collection, and audience snapshots run in the background.

• search_keywords, lookup_creator, analyze_video, lookup_sound, and lookup_hashtag wait up to 25 seconds, checking every 2.5 seconds. If the job isn't done, you get status: "processing" and a job ID to check later with check_job_status, not in a loop.
• create_niche_monitor, batch_lookup_creators, collect_creator_posts, and refresh_creator_audience return an ID right away.

A job is done when finalized: true. completed can mean the AI report is still being written, so empty analysis fields mean "not yet". A video with intelligence_status: "skipped" is the exception: it was left out on purpose.

Half of agent runs finish collecting in under 8 minutes, and 9 in 10 in under 20. The AI report follows within minutes. Lookups take under a minute to about 3 minutes.

In a chat app, ask the assistant to check back in 10 to 20 minutes. Developers can use the content_research_agent.run.completed webhook instead.

Guides your assistant can read

The server has four read-only guides (MCP resources). Many apps don't read them unprompted, so start big research with "Read Virlo's agent playbook and intent cookbook first."

• virlo://docs/intent-cookbook: how to write a good intent.
• virlo://docs/agent-playbook: which tool fits which question, and how to avoid wasted spend.
• virlo://docs/api-overview: the tool catalog.
• virlo://docs/credit-costs: the price of each tool.

The first two are also plain text for AI assistants (/intent-cookbook.txt, /agent-playbook.txt) and pages for people (Intent cookbook, Research playbook).

Workflow prompts

These are built-in, multi-step research plans. Pick one from your app's menu or ask by name: "Use the full_niche_analysis prompt for viral cooking content."

• start (optional website and goal): a first-run tour. Checks what the assistant knows about you, reads your website, runs suggest_keywords (free), and asks before it spends anything. $0.50 if you say yes to the first research run.
• full_niche_analysis (you give niche): drafts keywords with suggest_keywords (free), runs a one-time agent, looks up the top 2 or 3 creators, and sets up a weekly agent. About $2.00 to $2.50, then $0.50 a week.
• creator_deep_dive (platform, username): looks up the creator and writes a profile, then asks before tracking them. $0.50, plus $0.25 per check if you track them.
• trend_scout (optional platform: youtube, tiktok, instagram, or all): turns emerging trends, today's digest, viral videos, and hashtag momentum into a trend report. About $0.90 to $1.25.
• genre_monitor (genre): drafts keywords with suggest_keywords (free), creates a weekly TikTok agent, and writes a genre brief. $0.50 a week until you stop it.
• competitor_landscape (subject, a creator or niche; optional platform): runs an agent with Data Intelligence, shortlists 3 to 5 competitors, looks each up after you confirm, and writes a positioning brief. About $3.00 to $4.50.

What it costs

MCP tools cost the same as the Virlo API and draw from your prepaid API balance. It's separate from any Virlo app plan. Recurring agents and tracking bill every run until you pause or stop them.

MCP replies don't show what a call cost. Run get_credit_balance before and after, or open Usage.