MCP Server

Connect AI assistants to the Virlo API with our native Model Context Protocol (MCP) server. Supports Cursor, Claude Cowork, claude.ai, VS Code, Claude Code, Claude Desktop, and Windsurf with one-click or copy-paste setup.

The server exposes 46 tools that cover every capability of the public API — Content Research Agents (one-shot + recurring), Satellite creator/video/sound intel, long-term Tracking, Audience demographics, Sounds, Trends, and account utilities.

Quick Setup

Enter your API key below to get personalized, ready-to-use configuration for your AI client. Cursor users get a one-click install button.

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

How research tools map to Agents

Under the hood, keyword search and niche monitoring are the same product: Content Research Agents (/v1/agents). MCP keeps the legacy tool names (search_keywords, create_niche_monitor, …) as a stable public contract so existing Cursor / Claude / OpenClaw setups keep working — every call creates or reads a CRA.

You no longer pick a min_views floor or time_range at creation — collection is system-managed. Filter at read time (min_views, start_date, end_date, platforms, order_by, region) for free. Prefer intent on create (required upstream; MCP synthesizes one from keywords if omitted).

For full REST schemas, migration notes from Orbit/Comet, and autonomy details, see Content Research Agents. For how an assistant should use these tools (virality scoring, intelligence fields, spend discipline), load the Agent Playbook or the MCP resource virlo://docs/agent-playbook.

Available Tools

Tools are named for what they do. Creation costs credits; reads are free.

Analytics (instant)

Prefer get_emerging_trends when the user asks what is breaking, rising, or emerging; use get_trends / get_trends_digest for broader or editorial digests.

Content Research Agents — one-shot (async)

Legacy MCP names: Orbit / keyword search. Creates is_recurring: false agents.

Content Research Agents — recurring (async)

Legacy MCP names: Comet / niche monitor. Creates is_recurring: true agents with a cadence.

Satellite — Creator, Video & Sound Intelligence (async)

Every paid Satellite run persists a run_id. Prefer listing / re-reading before spending again.

Tracking — Long-term Monitoring

Pause with update_tracking_settings when you want to stop charges without losing the row; use untrack_* to deactivate entirely.

Audience — Demographics & Geography (cache-first)

Snapshots profile the creator's engaged audience (commenters), not raw followers. Every snapshot carries data_source, signal_breakdown, and confidence_level. Default cache window: 30 days. lookup_creator also accepts audience_demographics, audience_geography, and freshness_days for one-shot enrichment of untracked creators.

Sounds — Audio Intelligence

Sound data is also free via get_keyword_search_results / get_niche_monitor_data with data_type: "sounds". Use breakout for “what just took off,” trending for “what's biggest this week.”

Platform field availability: TikTok is richest (title, duration, cover, usage_count, commerce flag). YouTube has title, cover, owner. Instagram has title and owner_nickname. Unavailable fields return null.

Utility

Async Operations

Agent runs, Satellite lookups, video analysis, and post collection queue background work. MCP tools auto-poll for roughly 25 seconds, then hand back control:

1. The tool queues the job and polls briefly
2. If it finishes quickly, you get full results in one call
3. If still running, you get a job_id / job_type (and often a results-tool hint)
4. Use check_job_status or the matching get_* tool later — the assistant should not busy-wait

Canonical done signal: finalized: true. Status "completed" alone can mean secondary AI jobs (analysis, intelligence) are still running — null analysis/intelligence fields mean “not yet,” not “no data.” Agent runs take ~15–20 minutes median (up to ~45 for broad runs with Meta ads). Treat partial_failure as usable data.

Webhook for agent completion: content_research_agent.run.completed (legacy orbit.run.completed / comet.run.completed still fire during the REST migration window).

Resources & Playbook

The MCP server exposes three read-only resources:

Same playbook on the web: Agent Playbook · plain text at /agent-playbook.txt.

Workflow Prompts

Four pre-built prompts guide multi-step research (tool names stay as above):

full_niche_analysis

1. One-shot agent via search_keywords
2. Review videos, outliers, analysis, trends
3. Deep-dive top creators with lookup_creator
4. Recurring agent via create_niche_monitor
5. Actionable summary

Example: "Use the full_niche_analysis prompt for viral cooking content"

creator_deep_dive

1. lookup_creator with videos / outliers
2. Content pattern analysis
3. Optional track_creator

Example: "Run creator_deep_dive for @khaby.lame on TikTok"

trend_scout

1. get_emerging_trends + get_trends_digest
2. Top viral videos (optional get_breakout_sounds)
3. Rising hashtags
4. Actionable trend report

Example: "Use trend_scout to see what's trending across all platforms"

genre_monitor

1. Recurring TikTok agent via create_niche_monitor
2. Wait for finalized: true
3. Free discovery slices: sounds / hashtags / rising outliers / benchmarks / affinity
4. Genre brief

Example: "Use genre_monitor for progressive house"

Credit Costs

Creation costs credits; reads are free. Per-tool rates match the REST API — see Billing & Pricing and the MCP resource virlo://docs/credit-costs.